element-queries.md

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:

• 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.

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

{tip} If you loop through an element query as if it were an array, all() will be called automatically for you, and you will actually be looping through its results.

one()

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

{note} 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.

{note} 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.

{note} 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.

{note} 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

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