Craft 5 Class Reference

Appearance

NestedElementQueryInterface ​

Type
Interface
Namespace
craft\elements\db
Extends
craft\elements\db\ElementQueryInterface
Implemented by
craft\elements\db\AddressQuery, craft\elements\db\EntryQuery
Since
5.4.9

NestedElementQueryInterface defines the common interface to be implemented by element query classes which can query for nested elements.

View source

Public Methods ​

MethodDescription
addOrderBy()Adds additional ORDER BY columns to the query.
afterPopulate()Performs any post-population processing on elements.
all()Executes the query and returns all results as an array.
allowOwnerDrafts()Narrows the query results based on whether the {elements}’ owners are drafts.
allowOwnerRevisions()Narrows the query results based on whether the {elements}’ owners are revisions.
ancestorDist()Narrows the query results to only {elements} that are up to a certain distance away from the {element} specified by ancestorOf().
ancestorOf()Narrows the query results to only {elements} that are ancestors of another {element} in its structure.
andFilterWhere()Adds an additional WHERE condition to the existing one ignoring empty parameters.
andNotRelatedTo()Narrows the query results to only {elements} that are not related to certain other elements.
andRelatedTo()Narrows the query results to only {elements} that are related to certain other elements.
andWhere()Adds an additional WHERE condition to the existing one.
andWith()Causes the query to return matching {elements} eager-loaded with related elements, in addition to the elements that were already specified by with().
archived()Sets the $archived property.
asArray()Causes the query to return matching {elements} as arrays of data, rather than [[{element-class}]] objects.
collect()Executes the query and returns all results as a collection.
count()Returns the number of records.
createElement()Converts a found row into an element instance.
dateCreated()Narrows the query results based on the {elements}’ creation dates.
dateUpdated()Narrows the query results based on the {elements}’ last-updated dates.
descendantDist()Narrows the query results to only {elements} that are up to a certain distance away from the {element} specified by descendantOf().
descendantOf()Narrows the query results to only {elements} that are descendants of another {element} in its structure.
draftCreator()Narrows the query results to only drafts created by a given user.
draftId()Narrows the query results based on the {elements}’ draft’s ID (from the drafts table).
draftOf()Narrows the query results to only drafts of a given {element}.
drafts()Narrows the query results to only drafts {elements}.
eagerly()Causes the query to be used to eager-load results for the query’s source element and any other elements in its collection.
emulateExecution()Sets whether to emulate query execution, preventing any interaction with data storage.
exists()Returns a value indicating whether the query result contains any row of data.
extraFields()Returns the list of additional fields that can be returned by toArray() in addition to those listed in fields().
field()Narrows the query results based on the field the {elements} are contained by.
fieldId()Narrows the query results based on the field the {elements} are contained by, per the fields’ IDs.
fields()Returns the list of fields that should be returned by default by toArray() when no specific fields are specified.
filterWhere()Sets the WHERE part of the query ignoring empty parameters.
fixedOrder()Causes the query results to be returned in the order specified by id().
hasDescendants()Narrows the query results based on whether the {elements} have any descendants in their structure.
id()Narrows the query results based on the {elements}’ IDs.
ids()Executes the query and returns the IDs of the resulting elements.
ignorePlaceholders()Causes the query to return matching {elements} as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement().
inBulkOp()Narrows the query results to only {elements} that were involved in a bulk element operation.
inReverse()Causes the query results to be returned in reverse order.
indexBy()Sets the indexBy() property.
language()Determines which site(s) the {elements} should be queried in, based on their language.
leaves()Narrows the query results based on whether the {elements} are “leaves” ({elements} with no descendants).
level()Narrows the query results based on the {elements}’ level within the structure.
limit()Sets the LIMIT part of the query.
nextSiblingOf()Narrows the query results to only the {element} that comes immediately after another {element} in its structure.
notRelatedTo()Narrows the query results to only {elements} that are not related to certain other elements.
nth()Executes the query and returns a single row of result at a given offset.
offset()Sets the OFFSET part of the query.
one()Executes the query and returns a single row of result.
orFilterWhere()Adds an additional WHERE condition to the existing one ignoring empty parameters.
orWhere()Adds an additional WHERE condition to the existing one.
orderBy()Sets the ORDER BY part of the query.
owner()Sets the ownerId() and siteId() parameters based on a given element.
ownerId()Narrows the query results based on the owner element of the {elements}, per the owners’ IDs.
positionedAfter()Narrows the query results to only {elements} that are positioned after another {element} in its structure.
positionedBefore()Narrows the query results to only {elements} that are positioned before another {element} in its structure.
preferSites()If unique() is set, this determines which site should be selected when querying multi-site elements.
prepForEagerLoading()Prepares the query for lazy eager loading.
prevSiblingOf()Narrows the query results to only the {element} that comes immediately before another {element} in its structure.
primaryOwner()Sets the primaryOwnerId() and siteId() parameters based on a given element.
primaryOwnerId()Narrows the query results based on the primary owner element of the {elements}, per the owners’ IDs.
provisionalDrafts()Narrows the query results to only provisional drafts.
ref()Narrows the query results based on a reference string.
relatedTo()Narrows the query results to only {elements} that are related to certain other elements.
revisionCreator()Narrows the query results to only revisions created by a given user.
revisionId()Narrows the query results based on the {elements}’ revision’s ID (from the revisions table).
revisionOf()Narrows the query results to only revisions of a given {element}.
revisions()Narrows the query results to only revision {elements}.
savedDraftsOnly()Narrows the query results to only unpublished drafts which have been saved after initial creation.
search()Narrows the query results to only {elements} that match a search query.
siblingOf()Narrows the query results to only {elements} that are siblings of another {element} in its structure.
site()Determines which site(s) the {elements} should be queried in.
siteId()Determines which site(s) the {elements} should be queried in, per the site’s ID.
siteSettingsId()Narrows the query results based on the {elements}’ IDs in the elements_sites table.
slug()Narrows the query results based on the {elements}’ slugs.
status()Narrows the query results based on the {elements}’ statuses.
structureId()Determines which structure data should be joined into the query.
title()Narrows the query results based on the {elements}’ titles.
toArray()Converts the object into an array.
trashed()Narrows the query results to only {elements} that have been soft-deleted.
uid()Narrows the query results based on the {elements}’ UIDs.
unique()Determines whether only elements with unique IDs should be returned by the query.
uri()Narrows the query results based on the {elements}’ URIs.
wasCountEagerLoaded()Returns whether the query result count was already eager loaded by the query's source element.
wasEagerLoaded()Returns whether the query results were already eager loaded by the query's source element.
where()Sets the WHERE part of the query.
with()Causes the query to return matching {elements} eager-loaded with related elements.
withCustomFields()Sets whether custom fields should be factored into the query.
withStructure()Explicitly determines whether the query should join in the structure data.

allowOwnerDrafts() ​

Narrows the query results based on whether the {elements}’ owners are drafts.

Possible values include:

ValueFetches {elements}…
truewhich can belong to a draft.
falsewhich cannot belong to a draft.

View source

Arguments ​

Returns ​

static – Self reference

allowOwnerRevisions() ​

Narrows the query results based on whether the {elements}’ owners are revisions.

Possible values include:

ValueFetches {elements}…
truewhich can belong to a revision.
falsewhich cannot belong to a revision.

View source

Arguments ​

Returns ​

static – Self reference

field() ​

Narrows the query results based on the field the {elements} are contained by.

Possible values include:

ValueFetches {elements}…
'foo'in a field with a handle of foo.
['foo', 'bar']in a field with a handle of foo or bar.
a \craft\elements\db\craft\fields\Matrix objectin a field represented by the object.

View source

Arguments ​

  • $value (mixed) – The property value

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} in the Foo field #}
{% set {elements-var} = {twig-method}
  .field('foo')
  .all() %}
php
// Fetch {elements} in the Foo field
${elements-var} = {php-method}
    ->field('foo')
    ->all();

fieldId() ​

Narrows the query results based on the field the {elements} are contained by, per the fields’ IDs.

Possible values include:

ValueFetches {elements}…
1in a field with an ID of 1.
'not 1'not in a field with an ID of 1.
[1, 2]in a field with an ID of 1 or 2.
['not', 1, 2]not in a field with an ID of 1 or 2.

View source

Arguments ​

  • $value (mixed) – The property value

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} in the field with an ID of 1 #}
{% set {elements-var} = {twig-method}
  .fieldId(1)
  .all() %}
php
// Fetch {elements} in the field with an ID of 1
${elements-var} = {php-method}
    ->fieldId(1)
    ->all();

owner() ​

Sets the ownerId() and siteId() parameters based on a given element.

View source

Arguments ​

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} created for this entry #}
{% set {elements-var} = {twig-method}
  .owner(myEntry)
  .all() %}
php
// Fetch {elements} created for this entry
${elements-var} = {php-method}
    ->owner($myEntry)
    ->all();

ownerId() ​

Narrows the query results based on the owner element of the {elements}, per the owners’ IDs.

Possible values include:

ValueFetches {elements}…
1created for an element with an ID of 1.
[1, 2]created for an element with an ID of 1 or 2.

View source

Arguments ​

  • $value (mixed) – The property value

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} created for an element with an ID of 1 #}
{% set {elements-var} = {twig-method}
  .ownerId(1)
  .all() %}
php
// Fetch {elements} created for an element with an ID of 1
${elements-var} = {php-method}
    ->ownerId(1)
    ->all();

primaryOwner() ​

Sets the primaryOwnerId() and siteId() parameters based on a given element.

View source

Arguments ​

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} created for this entry #}
{% set {elements-var} = {twig-method}
  .primaryOwner(myEntry)
  .all() %}
php
// Fetch {elements} created for this entry
${elements-var} = {php-method}
    ->primaryOwner($myEntry)
    ->all();

primaryOwnerId() ​

Narrows the query results based on the primary owner element of the {elements}, per the owners’ IDs.

Possible values include:

ValueFetches {elements}…
1created for an element with an ID of 1.
[1, 2]created for an element with an ID of 1 or 2.

View source

Arguments ​

  • $value (mixed) – The property value

Returns ​

static – Self reference

Example ​

twig
{# Fetch {elements} created for an element with an ID of 1 #}
{% set {elements-var} = {twig-method}
  .primaryOwnerId(1)
  .all() %}
php
// Fetch {elements} created for an element with an ID of 1
${elements-var} = {php-method}
    ->primaryOwnerId(1)
    ->all();