entity-type-manager-query.md

EntityQuery Conditions

The EntityQuery class can be loaded manually (if you know the entity type):

$query = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery();

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

The $operator can take one of several options see core/lib/Drupal/Core/Entity/Query/QueryInterface.php::condition

// Example 1
// Use conditions to get a list of published articles.
$node_ids = $query
    ->condition('type', 'article')
    ->condition('status', 1)
    // Once we have our conditions specified we use the execute() method to run the query
    ->execute();

// Example 2
// Find all users with the Administrator role.
$admin_user_ids = \Drupal::service('entity_type.manager')->getStorage('user')->getQuery()
  ->condition('roles', 'Administrator', 'CONTAINS')
  ->execute();

// Example 3
// Chaining
// Articles created by a particular user name (rather than by ID)
$articles_by_name = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery()
  ->condition('type', 'article')
  ->condition('uid.entity.name', 'admin')
  ->execute();

// Example 3  
// Find particular nodes published in the last year.
$now = time();
$last_year = $now - 60*60*24*365;

$last_years_articles = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery()
  ->condition('type', 'article')
  ->condition('created', $last_year, '>=')
  ->execute();

Two other methods that come in handy when building up the conditions of a query, orConditionGroup() and andConditionGroup(). Either allows you to define a group of conditions which will subsequently be either OR'ed or AND'ed together.

$query = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery();

$group = $query->orConditionGroup()
  ->condition('uid', 22)
  ->condition('uid', 14)
  ->condition('uid.entity.name', 'admin')

$entity_ids = $query->condition('type', 'article')
  ->condition($group)
  ->execute();

Other query helper methods

exists() or notExists()

If you need a simple check whether or not a particular field exists you can use the exists() or notExists() methods.

$query = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery();

$untagged_articles = $query->condition('type', 'article')
  ->notExists('field_tags')
  ->execute();

sort()

The sort() method can be useful to order the results returned from EntityQuery in a particular way.

$query = \Drupal::service('entity_type.manager')->getStorage('user')->getQuery();

$time = time();
$yesterday = $time - 60*60*24;

$new_users = $query->condition('created', $yesterday, '>=')
  ->sort('created', 'DESC')
  ->execute();

count()

If you're less interested in the actual entity ids, and more interested in how many entities match a particular query the count method returns the number of entities found matching your conditions.

$query = \Drupal::service('entity_type.manager')->getStorage('user')->getQuery();

$time = time();
$yesterday = $time - 60*60*24;

$new_user_count = $query->condition('created', $yesterday, '>=')
  ->count()
  ->execute();

range() and pager()

Especially when working with a site that has a large amount of content it's important to think about limiting the number of results your query might return. Imagine the amount of memory required to load all of the published issue queue nodes from drupal.org with an entity query. That wouldn't be a very smart idea. This is where the pager() and range() methods come in handy. Pager allows us to specify a particular number of results, while the range method allows us to specify an index (or starting) number and the length (or page size) or results to return. Together these can be used to return a subset of any size from a result set.

$query = \Drupal::service('entity_type.manager')->getStorage('node')->getQuery();

$newest_articles = $query->condition('type', 'article')
  ->condition('status', 1)
  // Only return the newest 10 articles
  ->sort('created', 'DESC')
  ->pager(10)
  ->execute();

$not_quite_as_new_articles = $query->condition('type', 'article')
  ->condition('status', 1)
  // Only return the next newest 10 articles
  ->sort('created', 'DESC')
  ->range(10, 10)
  ->execute();