Introduction to 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()
    .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.

Attribute Parameters

Many parameters correspond to a particular element attribute. For example, entry queries have a postDate parameter that allows you to limit the results to entries with a matching Post Date.

Attribute parameters generally support a variety of syntaxes:

SyntaxFind elements where the param’s attribute…
param('X')is X.
param('= X')is X.
param('not X')is not X.
param('!= X')is not X.
param('<= X')is less than or equal to X.
param('>= X')is greater than or equal to X.
param('< X')is less than X.
param('> X')is greater than X.
param('*X*')contains X.
param('not *X*')doesn’t contain X.
param(':empty:)has no value.
param(':notempty:')has any value.

You can also specify multiple parameter values by setting the parameter to an array:

SyntaxFind elements where the param’s attribute…
param(['X', 'Y']is either X or Y.
param(['or', 'X', 'Y'])is either X or Y.
param(['and', 'X', 'Y'])is both X and Y.

In these cases, X and Y can follow any of the supported parameter syntaxes.

For example, let’s say you wanted to load entries that were posted sometime in the last month.


{# Set the first and last dates that we want to fetch entries from #}
{% set start = date('first day of last month')|atom %}
{% set end = date('last day of last month')|atom %}

{# Get all the entries that were posted between those dates #}
{% set entries = craft.entries()
    .postDate(['and', ">= #{start}", "<= #{end}"])
    .all() %}


We’re using interpolation to inject the start and end variables into the value strings, which felt a little cleaner than the ~ operator:


{% set entries = craft.entries()
    .postDate(['and', '>= '~start, '<= '~end])
    .all() %}

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.


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()


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()


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()


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

{% set count = craft.entries()


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


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

{% set entryIds = craft.entries()

Advanced Element Queries

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




Query Execution


When customizing an element query, you can call getRawSql() 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()) }}