Craft 3 Documentation

Element Queries

Element queries are query builders that are tuned for fetching elements in Craft. They have several custom parameters, and they abstract away all the complexities of the actual SQL query needed to fetch the elements. Rather than raw data, they return element models.

Creating Element Queries #

You can create element queries in both PHP and Twig code. Here’s how:

Element Type PHP Twig
Assets \craft\elements\Asset::find() craft.assets()
Categories \craft\elements\Category::find() craft.categories()
Entries \craft\elements\Entry::find() craft.entries()
Matrix blocks \craft\elements\MatrixBlock::find() craft.matrixBlocks()
Tags \craft\elements\Tag::find() craft.tags()
Users \craft\elements\User::find() craft.users()

Setting Parameters #

Once you’ve created an element query, you can set parameters on it.

The available parameters varies by element type. Here are the lists of parameters supported by Craft’s built-in element types:

The parameters should be set with chained method calls, like so:

PHP #

use craft\elements\Entry;

$query = Entry::find()
    ->section('news')
    ->limit(10);

Twig #

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

Batch-Setting Parameters #

You can also batch-set parameters like so:

PHP #

use craft\elements\Entry;

$query = Entry::find();
\Craft::configure($query, [
    'section' => 'news',
    'limit' => 10
]);

Twig #

{% set query = craft.entries({
    section: 'news',
    limit: 10
}) %}

Param Value Syntax #

Most parameter values will get processed through craft\helpers\Db::parseParam() before being applied as a condition on the element query. That method makes things like the following possible:

Custom Field Parameters #

In addition to the core parameters, most custom fields support their own parameters as well.

{% set query = craft.entries()
    .section('news')
    .myCustomFieldHandle('param-value')
    .all() %}
``

## Executing Element Queries

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

### `exists()`

Returns whether any elements match the query.

#### PHP

```php
use craft\elements\Entry;

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

Twig #

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

count() #

Returns the total number of elements that are matched by the query.

PHP #

use craft\elements\Entry;

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

Twig #

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

all() #

Returns all of the elements in an array.

If the asArray param was set to true, then the elements will be represented as raw arrays, rather than element objects.

PHP #

use craft\elements\Entry;

$entries = Entry::find()
    ->section('news')
    ->limit(10)
    ->all();

Twig #

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

one() #

Returns the first matching element, or null if there isn’t one.

If the asArray param was set to true, then the element will be represented as a raw array, rather than an element object.

PHP #

use craft\elements\Entry;

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

Twig #

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

nth() #

Returns the nth matching element, or null if there isn’t one. Note that n is 0-indexed, so nth(0) will give you the first element, nth(1) will give you the second, etc.

If the asArray param was set to true, then the element will be represented as a raw array, rather than an element object.

PHP #

use craft\elements\Entry;

$entry = Entry::find()
    ->section('news')
    ->nth(4);

Twig #

{% set entry = craft.entries()
    .section('news')
    .nth(4) %}

ids() #

Returns an array of the IDs of the matching elements.

PHP #

use craft\elements\Entry;

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

Twig #

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

column() #

Returns an array of all the first column’s values.

By default the first column will be the elements’ IDs, but you can customize that with the select() param.

PHP #

use craft\elements\Entry;

$uris = Entry::find()
    ->section('news')
    ->select('uri')
    ->column();

Twig #

{% set uris = craft.entries()
    .section('news')
    .select('uri')
    .column() %}

scalar() #

Returns the first column’s value of the first matching element.

By default the first column will be the element’s ID, but you can customize that with the select() param.

PHP #

use craft\elements\Entry;

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

Twig #

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

Aggregate Methods #

The following methods will run an aggregate method on the first column of matching elements, and return the result:

By default the first column will be the elements’ IDs, but you can customize that with the select() param.

PHP #

use craft\elements\Entry;

$sum = Entry::find()
    ->section('news')
    ->select('field_someNumberField')
    ->sum();

Twig #

{% set sum = craft.entries()
    .section('news')
    .select('field_someNumberField')
    .sum() %}