Drupal - What's the proper use of EntityFieldQuery?

EntityFieldQuery uses a set of hooks to interface with field storage modules, such as Field SQL Storage, in order to work for fields as well as other node properties. Long term, EntityFieldQuery is a much more reliable way to query any type of entity, and in some situations it can perform cross entity queries (see field_has_data or _list_values_in_use() for an example.

Here's a simple example of using EntityFieldQuery to get a list of all nodes published before a specific timestamp:

$query = new EntityFieldQuery();

$query
  ->entityCondition('entity_type', 'node', '=')
  ->propertyCondition('status', 1, '=')
  ->propertyCondition('created', '1294694496', '<');

$result = $query->execute();

$results from that query would look something like this:

Array
(
    [node] => Array
        (
            [1] => stdClass Object
                (
                    [nid] => 1
                    [vid] => 49
                    [type] => article
                )

            [2] => stdClass Object
                (
                    [nid] => 2
                    [vid] => 2
                    [type] => page
                )

        )

)

You could then use that array as input to node_load_multiple:

$nodes = node_load_multiple(array_keys($result['node']));

I found an issue on Drupal about adding examples for EntityFieldQuery. I've been using it for examples as well as to voice my opinion on the call for more examples.

"Do we need an EntityFieldQuery example?"

The comment #11 shows usage of node_load_multiple() as seen below:

$query = new EntityFieldQuery();
$entities = $query->entityCondition('entity_type', 'node')
                        ->entityCondition('bundle', 'event')
                        ->propertyCondition('status', 1)
                        ->fieldCondition('field_date', 'value', array('2011-03-01', '2011-03-31'), 'BETWEEN')
                        ->fieldOrderBy('field_date', 'value', 'ASC')
                        ->execute();

$nodes = entity_load('node', array_keys($entities['node']));
return node_view_multiple($nodes, 'teaser');

Here is an example from one of the test modules:

http://api.drupal.org/api/drupal/modules--node--tests--node_access_test.module/function/node_access_entity_test_page/7

This selects nodes whose body field starts with "A". See also EntityFieldQuery::execute() on how to use the returned result.

There are many use cases, the typical example is querying entities for specific field value like the body field as shown in the first example.

The advantage is that it works whatever field_storage you are using. For example, you can have your fields in MongoDB and EntityQuery will still work while querying field_data_body manually wouldn't.