8.2.x QueryInterface.php public QueryInterface::condition($field, $value = NULL, $operator = NULL, $langcode = NULL)
8.0.x QueryInterface.php public QueryInterface::condition($field, $value = NULL, $operator = NULL, $langcode = NULL)
8.1.x QueryInterface.php public QueryInterface::condition($field, $value = NULL, $operator = NULL, $langcode = NULL)
8.3.x QueryInterface.php public QueryInterface::condition($field, $value = NULL, $operator = NULL, $langcode = NULL)

Add a condition to the query or a condition group.

For example, to find all entities containing both the Turkish 'merhaba' and the Polish 'siema' within a 'greetings' text field:

  $entity_ids = \Drupal::entityQuery($entity_type)
    ->condition('greetings', 'merhaba', '=', 'tr')
    ->condition('greetings.value', 'siema', '=', 'pl')
    ->execute();

Parameters

$field: Name of the field being queried. It must contain a field name, optionally followed by a column name. The column can be the reference property, usually "entity", for reference fields and that can be followed similarly by a field name and so on. Additionally, the target entity type can be specified by appending the ":target_entity_type_id" to "entity". Some examples:

  • nid
  • tags.value
  • tags
  • tags.entity.name
  • tags.entity:taxonomy_term.name
  • uid.entity.name
  • uid.entity:user.name

"tags" "is the same as "tags.value" as value is the default column. If two or more conditions have the same field names they apply to the same delta within that field. In order to limit the condition to a specific item a numeric delta should be added between the field name and the column name.

  ->condition('tags.5.value', 'news')
  

This will require condition to be satisfied on a specific delta of the field. The condition above will require the 6th value of the field to match the provided value. Further, it's possible to create a condition on the delta itself by using '%delta'. For example,

  ->condition('tags.%delta', 5)
  

will find only entities which have at least six tags. Finally, the condition on the delta itself accompanied with a condition on the value will require the value to appear in the specific delta range. For example,

  ->condition('tags.%delta', 0, '>'))
  ->condition('tags.%delta.value', 'news'))
  

will only find the "news" tag if it is not the first value. It should be noted that conditions on specific deltas and delta ranges are only supported when querying content entities.

$value: The value for $field. In most cases, this is a scalar and it's treated as case-insensitive. For more complex operators, it is an array. The meaning of each element in the array is dependent on $operator.

$operator: Possible values:

  • '=', '<>', '>', '>=', '<', '<=', 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH': These operators expect $value to be a literal of the same type as the column.
  • 'IN', 'NOT IN': These operators expect $value to be an array of literals of the same type as the column.
  • 'BETWEEN': This operator expects $value to be an array of two literals of the same type as the column.

$langcode: Language code (optional). If omitted, any translation satisfies the condition. However, if two or more conditions omit the langcode within one condition group then they are presumed to apply to the same translation. If within one condition group one condition has a langcode and another does not they are not presumed to apply to the same translation.

Return value

\Drupal\Core\Entity\Query\QueryInterface

See also

\Drupal\Core\Entity\Query\andConditionGroup

\Drupal\Core\Entity\Query\orConditionGroup

1 method overrides QueryInterface::condition()
QueryBase::condition in core/lib/Drupal/Core/Entity/Query/QueryBase.php
Add a condition to the query or a condition group.

File

core/lib/Drupal/Core/Entity/Query/QueryInterface.php, line 101

Class

QueryInterface
Interface for entity queries.

Namespace

Drupal\Core\Entity\Query

Code

public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL);

Comments

colan’s picture

If you want to check for the lack of a value, say for an empty entity reference field, you need to use notExists() instead of condition(). There's also an exists().

hughbris’s picture

I think it would be beneficial to emphasise that string matches are not case sensitive, as this is a very important detail I couldn't find anywhere else.

I don't seem to be able to edit these docs myself, or I would make that change.