Drupal 7 introduced the EntityFieldQuery API. This class is a mechanism for quickly building queries of entities and fields - typically nodes, but of course not limited to that.

Drupal 7 features a much richer database abstraction layer than previous versions of Drupal, but in the end you are still more or less building SQL. EntityFieldQuery allows you to construct queries without much knowledge of SQL at all.

Drupal core itself mostly uses EntityFieldQuery as a utility function, in many cases simply to check that a given field has a value somewhere in the system or not. It’s strange that such a powerful mechanism is put to so little use by core, but no matter. Let’s see how we can use it.

Starting Your Query

Starting an entity field query looks like this:

Extremely simple, right? That's all it takes to get started. Let's now add some conditions to our query.

Let's take a look at what's going on here. First of all, notice the lack of semicolons between method calls. Each EntityFieldQuery method returns the same EntityFieldQuery object the method is called on. This allows us to chain method calls together, which speeds up coding and makes it easier to read. This will look familiar to anyone who uses jQuery. This could just as easily be written like so:

But, that is really not easy at all to read. I recommend putting each method on its own line. Future generations of coders will thank you.

Now let's look at each method and see what's happening.

The first method uses an entityCondition to tell the query to look for node entities. It may seem like specifying this is redundant, but as many other things in Drupal 7 are also entities - users, taxonomy terms, etc - you need to restrict your set.

The second method tells the query which node types to restrict the set to. This can be left out if you would like to query all available nodes, but in most cases you will be looking for specific node types. Note also that the second argument, 'article' in this case, can be either a string or an array; the query will adjust automatically. So if you were looking for both article and page node types, you could rewrite that part of the chain as follows:

As you can see, it's extremely easy to expand your query.

The third method is a propertyCondition. A property in this case is any column in the base table for the given entity type. In the case of nodes, this could be whether it is published, the user that created the node, time of creation, etc. In our example above, we are modifying our query to only return published values.

The last method in our example above uses propertyOrderBy to set an order. In this case, we're simply asking for the results to be returned in reverse chronological order.

Querying Fields and Limiting

Now let's add a query on a field value using a fieldCondition. Let's assume each of the node types in our example has a field 'field_us_state' assigned to it. We're going to find nodes that are associated with the New York Tri-state area, which also includes Connecticut and New Jersey. This would look like this:

We can order by field values as well, if that is useful to us. Note that ordering conditions are processed in the order that they are added to the query.

Perhaps for our purposes, we want to limit our query to the 10 most recent items. Let’s add a range:

Et Voilà

Finally, we execute the query and assign that to a variable:

This returns us an array of entity ids that match the conditions specified for the query. If we are querying nodes, the information will be under $result['node']. In most cases, what you actually want are the nids that have been returned. This is easily accomplished:

Putting that all together, we have:

This is not very much code at all for this result. Moreover, we don’t need to know anything about SQL or even about the underlying storage engine being used. We simply write the query in this simple syntax, and EntityFieldQuery API does the job of translating that into a query that Drupal’s database abstraction layer understands and executes it for us.

What would we do with this list of nids? Pretty much anything. We might load them, for starters:

We might want to display these 10 nodes in a teaser style. That’s also easily done. Let’s generate a Drupal render array:

More To Come

This is just the beginning. Look for part 2 of this post, where we will show more concrete examples of putting EntityFieldQuery to use. Also look out for posts from other Treehouse engineers explaining more advanced topics related to EntityFieldQuery.