interface QueryInterface in Drupal 9

Interface for entity queries.

Never instantiate classes implementing this interface directly. Always use the QueryFactory class.

Hierarchy

• interface \Drupal\Core\Database\Query\AlterableInterface
  • interface \Drupal\Core\Entity\Query\QueryInterface

Related topics

Database abstraction layer

Allow the use of different database servers using the same code base.

12 files declare their use of QueryInterface

ConfigEntityStorageTest.php in core/tests/Drupal/Tests/Core/Config/Entity/ConfigEntityStorageTest.php

DrupalTest.php in core/tests/Drupal/Tests/Core/DrupalTest.php

EntityResource.php in core/modules/jsonapi/src/Controller/EntityResource.php

EntityStorageBase.php in core/lib/Drupal/Core/Entity/EntityStorageBase.php

Filter.php in core/modules/jsonapi/src/Query/Filter.php

... See full list

File

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

Namespace

Drupal\Core\Entity\Query

interface QueryInterface extends AlterableInterface {

  /**
   * Gets the ID of the entity type for this query.
   *
   * @return string
   *   The entity type ID.
   */
  public function getEntityTypeId();

  /**
   * 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:
   * @code
   *   $entity_ids = \Drupal::entityQuery($entity_type)
   *     ->accessCheck(FALSE)
   *     ->condition('greetings', 'merhaba', '=', 'tr')
   *     ->condition('greetings.value', 'siema', '=', 'pl')
   *     ->execute();
   * @endcode
   *
   * @param string|\Drupal\Core\Entity\Query\ConditionInterface $field
   *   Name of the field being queried or an instance of ConditionInterface.
   *   In the case of the name, 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.
   *   @code
   *   ->condition('tags.5.value', 'news')
   *   @endcode
   *   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,
   *   @code
   *   ->condition('tags.%delta', 5)
   *   @endcode
   *   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,
   *   @code
   *   ->condition('tags.%delta', 0, '>'))
   *   ->condition('tags.%delta.value', 'news'))
   *   @endcode
   *   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.
   * @param string|int|bool|array|null $value
   *   (optional) 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.
   *   Defaults to NULL, for most operators (except: 'IS NULL', 'IS NOT NULL')
   *   it always makes the condition false.
   * @param string|null $operator
   *   (optional) The comparison 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.
   *   - 'IS NULL', 'IS NOT NULL': These operators ignore $value, for that
   *     reason it is recommended to use a $value of NULL for clarity.
   *   - 'BETWEEN', 'NOT BETWEEN': These operators expect $value to be an array
   *     of two literals of the same type as the column.
   *   If NULL, defaults to the '=' operator.
   * @param string|null $langcode
   *   (optional) The language code allows filtering results by specific
   *   language. 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. If omitted (NULL), any translation satisfies the condition.
   *
   * @return $this
   *
   * @see \Drupal\Core\Entity\Query\QueryInterface::andConditionGroup()
   * @see \Drupal\Core\Entity\Query\QueryInterface::orConditionGroup()
   * @see \Drupal\Core\Entity\Query\ConditionInterface
   * @see \Drupal\Core\Entity\Query\QueryInterface::exists()
   * @see \Drupal\Core\Entity\Query\QueryInterface::notExists()
   */
  public function condition($field, $value = NULL, $operator = NULL, $langcode = NULL);

  /**
   * Queries for a non-empty value on a field.
   *
   * @param string $field
   *   Name of a field.
   * @param string|null $langcode
   *   (optional) The language code allows filtering results by specific
   *   language. If omitted (NULL), any translation satisfies the condition.
   *
   * @return $this
   */
  public function exists($field, $langcode = NULL);

  /**
   * Queries for an empty field.
   *
   * @param string $field
   *   Name of a field.
   * @param string|null $langcode
   *   (optional) The language code allows filtering results by specific
   *   language. If omitted (NULL), any translation satisfies the condition.
   *
   * @return $this
   */
  public function notExists($field, $langcode = NULL);

  /**
   * Enables a pager for the query.
   *
   * @param int $limit
   *   (optional) An integer specifying the number of elements per page. If
   *   passed 0, the pager is disabled.
   * @param int|null $element
   *   (optional) An integer to distinguish between multiple pagers on one page.
   *   If not provided, one is automatically calculated by incrementing the
   *   next pager element value.
   *
   * @return $this
   */
  public function pager($limit = 10, $element = NULL);

  /**
   * Defines the range of the query.
   *
   * @param int|null $start
   *   (optional) The first record from the result set to return. If NULL,
   *   removes any range directives that are set.
   * @param int|null $length
   *   (optional) The maximum number of rows to return. If $start and $length
   *   are NULL, then a complete result set will be generated. If $start is
   *   not NULL and $length is NULL, then an empty result set will be
   *   generated.
   *
   * @return $this
   */
  public function range($start = NULL, $length = NULL);

  /**
   * Sorts the result set by a given field.
   *
   * @param string $field
   *   Name of a field.
   * @param string $direction
   *   (optional) The direction to sort. Allowed values are "ASC" and "DESC".
   *   Defaults to "ASC".
   * @param string|null $langcode
   *   (optional) The language code allows filtering results by specific
   *   language. If omitted (NULL), any translation satisfies the condition.
   *
   * @return $this
   *
   * @todo standardize $direction options in
   * https://www.drupal.org/project/drupal/issues/3079258
   */
  public function sort($field, $direction = 'ASC', $langcode = NULL);

  /**
   * Makes this a count query.
   *
   * For count queries, execute() returns the number entities found.
   *
   * @return $this
   */
  public function count();

  /**
   * Enables sortable tables for this query.
   *
   * @param array $headers
   *   An array of headers of the same structure as described in
   *   template_preprocess_table(). Use a 'specifier' in place of a 'field' to
   *   specify what to sort on. This can be an entity or a field as described
   *   in condition().
   *
   * @return $this
   */
  public function tableSort(&$headers);

  /**
   * Enables or disables access checking for this query.
   *
   * @param bool $access_check
   *   (optional) Whether access check is requested or not. Defaults to TRUE.
   *
   * @return $this
   */
  public function accessCheck($access_check = TRUE);

  /**
   * Execute the query.
   *
   * @return int|array
   *   Returns an integer for count queries or an array of ids. The values of
   *   the array are always entity ids. The keys will be revision ids if the
   *   entity supports revision and entity ids if not.
   */
  public function execute();

  /**
   * Creates a new group of conditions ANDed together.
   *
   * For example, consider a drawing entity type with a 'figures' multi-value
   * field containing 'shape' and 'color' columns. To find all drawings
   * containing both a red triangle and a blue circle:
   * @code
   *   $query = \Drupal::entityQuery('drawing')->accessCheck(FALSE);
   *   $group = $query->andConditionGroup()
   *     ->condition('figures.color', 'red')
   *     ->condition('figures.shape', 'triangle');
   *   $query->condition($group);
   *   $group = $query->andConditionGroup()
   *     ->condition('figures.color', 'blue')
   *     ->condition('figures.shape', 'circle');
   *   $query->condition($group);
   *   $entity_ids = $query->execute();
   * @endcode
   *
   * @return \Drupal\Core\Entity\Query\ConditionInterface
   *   A condition object whose conditions will be combined with AND.
   */
  public function andConditionGroup();

  /**
   * Creates a new group of conditions ORed together.
   *
   * For example, consider a map entity with an 'attributes' field
   * containing 'building_type' and 'color' columns. To find all green and
   * red bikesheds:
   * @code
   *   $query = \Drupal::entityQuery('map')->accessCheck(FALSE);
   *   $group = $query->orConditionGroup()
   *     ->condition('attributes.color', 'red')
   *     ->condition('attributes.color', 'green');
   *   $entity_ids = $query
   *     ->condition('attributes.building_type', 'bikeshed')
   *     ->condition($group)
   *     ->execute();
   * @endcode
   * Note that this particular example can be simplified:
   * @code
   *   $entity_ids = $query
   *     ->condition('attributes.color', ['red', 'green'])
   *     ->condition('attributes.building_type', 'bikeshed')
   *     ->execute();
   * @endcode
   *
   * @return \Drupal\Core\Entity\Query\ConditionInterface
   *   A condition object whose conditions will be combined with OR.
   */
  public function orConditionGroup();

  /**
   * Limits the query to only default revisions.
   *
   * See the @link entity_api Entity API topic @endlink for information about
   * the current revision.
   *
   * @return $this
   */
  public function currentRevision();

  /**
   * Queries the latest revision.
   *
   * The latest revision is the most recent revision of an entity. This will be
   * either the default revision, or a pending revision if one exists and it is
   * newer than the default.
   *
   * @return $this
   */
  public function latestRevision();

  /**
   * Queries all the revisions.
   *
   * @return $this
   */
  public function allRevisions();

}

Members

Name	Modifiers	Type	Description	Overrides
AlterableInterface::addMetaData	public	function	Adds additional metadata to the query.	3
AlterableInterface::addTag	public	function	Adds a tag to a query.	3
AlterableInterface::getMetaData	public	function	Retrieves a given piece of metadata.	3
AlterableInterface::hasAllTags	public	function	Determines if a given query has all specified tags.	3
AlterableInterface::hasAnyTag	public	function	Determines if a given query has any specified tag.	3
AlterableInterface::hasTag	public	function	Determines if a given query has a given tag.	3
QueryInterface::accessCheck	public	function	Enables or disables access checking for this query.	1
QueryInterface::allRevisions	public	function	Queries all the revisions.	1
QueryInterface::andConditionGroup	public	function	Creates a new group of conditions ANDed together.	1
QueryInterface::condition	public	function	Add a condition to the query or a condition group.	1
QueryInterface::count	public	function	Makes this a count query.	1
QueryInterface::currentRevision	public	function	Limits the query to only default revisions.	1
QueryInterface::execute	public	function	Execute the query.	5
QueryInterface::exists	public	function	Queries for a non-empty value on a field.	1
QueryInterface::getEntityTypeId	public	function	Gets the ID of the entity type for this query.	1
QueryInterface::latestRevision	public	function	Queries the latest revision.	1
QueryInterface::notExists	public	function	Queries for an empty field.	1
QueryInterface::orConditionGroup	public	function	Creates a new group of conditions ORed together.	1
QueryInterface::pager	public	function	Enables a pager for the query.	1
QueryInterface::range	public	function	Defines the range of the query.	1
QueryInterface::sort	public	function	Sorts the result set by a given field.	1
QueryInterface::tableSort	public	function	Enables sortable tables for this query.	1