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:

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:

• Assets
• Categories
• Entries
• Matrix blocks
• Tags
• Users

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
}) %}

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 #

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:

• sum() – Returns the sum of all the values in the first column
• average() – Returns the average number of all the values in the first column
• min() – Returns the minimum number of all the values in the first column
• max() – Returns the maximum number of all the values in the first column

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