Element Queries

You can fetch elements (entries, categories, assets, etc.) in your templates or PHP code using element queries.

Working with element queries consists of three steps:

  1. Create the element query. You do this by calling a “factory function” that is named after the element type you are going to fetch. For example, if you want to fetch entries, you’d call craft.entries(), which returns a new entry query.
  2. Set some parameters. By default, element queries will be configured to return all elements of the specified type. You can narrow that down to just the elements you care about by setting parameters on the query.
  3. Execute the query. Once you’ve specified the query parameters, you’re ready for Craft to fetch the elements and give you the results. You do that by calling .all() or .one(), depending on whether you need multiple elements, or just one.

Here’s what a typical element query might look like:

{# Create an entry query and set some parameters on it #}
{% set entryQuery = craft.entries()
  .section('news')
  .orderBy('postDate DESC')
  .limit(10) %}

{# Execute the query and get the results #}
{% set entries = entryQuery.all() %}

Each type of element has its own function for creating element queries, and they each have their own parameters you can set. See the individual element query pages for more details on working with them:

Most custom fields support element query parameters as well, named after the field handles. See each field type’s documentation for examples.

# Executing Element Queries

Once you’ve defined your parameters on the query, there are multiple functions available to execute it, depending on what you need back.

# all()

Most of the time, you just want to get the elements that you’re querying for. You do that with the all() function.

{% set entries = craft.entries()
  .section('news')
  .limit(10)
  .all() %}

# one()

If you only need a single element, call one() instead of all(). It will either return the element or null if no matching element exists.

{% set entry = craft.entries()
  .section('news')
  .slug('hello-world')
  .one() %}

# exists()

If you just need to check if any elements exist that match the element query, you can call exists(), which will return either true or false.

{% set exists = craft.entries()
  .section('news')
  .slug('hello-world')
  .exists() %}

# count()

If you want to know how many elements match your element query, you can call count().

{% set count = craft.entries()
  .section('news')
  .count() %}

The limit and offset parameters will be ignored when you call count().

# ids()

If you just want a list of matching element IDs, you can call ids().

{% set entryIds = craft.entries()
  .section('news')
  .ids() %}

# Caching Element Queries

# cache()

Craft’s element query results can be cached with the cache() function:

{% set entries = craft.entries()
  .section('news')
  .limit(10)
  .cache()
  .all() %}

This is a layer on top of data caching that’s different from the template {% cache %} tag.

Craft registers an ElementQueryTagDependency (opens new window) for you by default, so cache dependencies and invalidation are handled automatically.

# Advanced Element Queries

Element queries are specialized query builders (opens new window) under the hood, so they support most of the same methods provided by craft\db\Query (opens new window).

# Selections

# Joins

# Conditions

# Query Execution

If you need to reference a custom field column in any of the above methods, you will need to use its complete column name (e.g. field_altText_xssyxqvs).

When customizing an element query, you can call getRawSql() (opens new window) to get the full SQL that is going to be executed by the query, so you have a better idea of what to modify.

{{ dump(query.getRawSql()) }}