README.md

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:

::: code

{# 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() %}

use craft\elements\Entry;

// Create an entry query and set some parameters on it
$entryQuery = Entry::find()
    ->section('news')
    ->orderBy('postDate desc')
    ->limit(10);

// Execute the query and get the results
$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:

• Asset Queries
• Category Queries
• Entry Queries
• Global Set Queries
• Matrix Block Queries
• Tag Queries
• User Queries

::: tip Most custom fields support element query parameters as well, named after the field handles. :::

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.

::: code

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

use craft\elements\Entry;

$entries = Entry::find()
    ->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.

::: code

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

use craft\elements\Entry;

$entry = Entry::find()
    ->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.

::: code

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

use craft\elements\Entry;

$exists = Entry::find()
    ->section('news')
    ->slug('hello-world')
    ->exists();

:::

count()

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

::: code

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

use craft\elements\Entry;

$count = Entry::find()
    ->section('news')
    ->count();

:::

::: tip 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().

::: code

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

use craft\elements\Entry;

$entryIds = Entry::find()
    ->section('news')
    ->ids();

:::

Advanced Element Queries

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

Selections

• select()
• addSelect()
• distinct()
• groupBy()

Joins

• innerJoin()
• leftJoin()
• rightJoin()

Conditions

• where()
• andWhere()
• orWhere()
• filterWhere()
• andFilterWhere()
• orFilterWhere()

Query Execution

• all()
• one()
• nth()
• exists()
• count()
• column()
• scalar()
• sum()
• average()
• min()
• max()

::: tip 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()) }}