Asset Queries

You can fetch assets in your templates or PHP code using asset queries.

::: code

{# Create a new asset query #}
{% set myAssetQuery = craft.assets() %}

// Create a new asset query
$myAssetQuery = \craft\elements\Asset::find();

:::

Once you’ve created an asset query, you can set parameters on it to narrow down the results, and then execute it by calling .all(). An array of Asset objects will be returned.

::: tip See Introduction to Element Queries to learn about how element queries work. :::

Example

We can display a list of thumbnails for images in a “Photos” volume by doing the following:

Create an asset query with craft.assets().
Set the volume and kind parameters on it.
Fetch the assets with .all().
Loop through the assets using a for tag to create the thumbnail list HTML.

{# Create an asset query with the 'volume' and 'kind' parameters #}
{% set myAssetQuery = craft.assets()
    .volume('photos')
    .kind('image') %}

{# Fetch the assets #}
{% set images = myAssetQuery.all() %}

{# Display the thumbnail list #}
<ul>
    {% for image in images %}
        <li><img src="{{ image.getUrl('thumb') }}" alt="{{ image.title }}"></li>
    {% endfor %}
</ul>

::: warning When using asset.url or asset.getUrl(), the asset’s source volume must have “Assets in this volume have public URLs” enabled and a “Base URL” setting. Otherwise, the result will always be empty. :::

Parameters

Asset queries support the following parameters:

Param	Description
anyStatus	Clears out the status() and enabledForSite() parameters.
asArray	Causes the query to return matching assets as arrays of data, rather than Asset objects.
clearCachedResult	Clears the cached result.
dateCreated	Narrows the query results based on the assets’ creation dates.
dateModified	Narrows the query results based on the assets’ files’ last-modified dates.
dateUpdated	Narrows the query results based on the assets’ last-updated dates.
filename	Narrows the query results based on the assets’ filenames.
fixedOrder	Causes the query results to be returned in the order specified by id.
folderId	Narrows the query results based on the folders the assets belong to, per the folders’ IDs.
height	Narrows the query results based on the assets’ image heights.
id	Narrows the query results based on the assets’ IDs.
ignorePlaceholders	Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement().
inReverse	Causes the query results to be returned in reverse order.
includeSubfolders	Broadens the query results to include assets from any of the subfolders of the folder specified by folderId.
kind	Narrows the query results based on the assets’ file kinds.
limit	Determines the number of assets that should be returned.
offset	Determines how many assets should be skipped in the results.
orderBy	Determines the order that the assets should be returned in. (If empty, defaults to `dateCreated DESC`.)
preferSites	If unique is set, this determines which site should be selected when querying multi-site elements.
relatedTo	Narrows the query results to only assets that are related to certain other elements.
search	Narrows the query results to only assets that match a search query.
site	Determines which site(s) the assets should be queried in.
siteId	Determines which site(s) the assets should be queried in, per the site’s ID.
size	Narrows the query results based on the assets’ file sizes (in bytes).
title	Narrows the query results based on the assets’ titles.
trashed	Narrows the query results to only assets that have been soft-deleted.
uid	Narrows the query results based on the assets’ UIDs.
unique	Determines whether only elements with unique IDs should be returned by the query.
uploader	Narrows the query results based on the user the assets were uploaded by, per the user’s IDs.
volume	Narrows the query results based on the volume the assets belong to.
volumeId	Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs.
width	Narrows the query results based on the assets’ image widths.
with	Causes the query to return matching assets eager-loaded with related elements.
withTransforms	Causes the query to return matching assets eager-loaded with image transform indexes.

`anyStatus`

Clears out the status() and enabledForSite() parameters.

::: code

{# Fetch all assets, regardless of status #}
{% set assets = craft.assets()
    .anyStatus()
    .all() %}

// Fetch all assets, regardless of status
$assets = \craft\elements\Asset::find()
    ->anyStatus()
    ->all();

:::

`asArray`

Causes the query to return matching assets as arrays of data, rather than Asset objects.

::: code

{# Fetch assets as arrays #}
{% set assets = craft.assets()
    .asArray()
    .all() %}

// Fetch assets as arrays
$assets = \craft\elements\Asset::find()
    ->asArray()
    ->all();

:::

`clearCachedResult`

Clears the cached result.

`dateCreated`

Narrows the query results based on the assets’ creation dates.

Possible values include:

Value	Fetches assets…
`'>= 2018-04-01'`	that were created on or after 2018-04-01.
`'< 2018-05-01'`	that were created before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were created between 2018-04-01 and 2018-05-01.

::: code

{# Fetch assets created last month #}
{% set start = date('first day of last month')|atom %}
{% set end = date('first day of this month')|atom %}

{% set assets = craft.assets()
    .dateCreated(['and', ">= #{start}", "< #{end}"])
    .all() %}

// Fetch assets created last month
$start = (new \DateTime('first day of last month'))->format(\DateTime::ATOM);
$end = (new \DateTime('first day of this month'))->format(\DateTime::ATOM);

$assets = \craft\elements\Asset::find()
    ->dateCreated(['and', ">= {$start}", "< {$end}"])
    ->all();

:::

`dateModified`

Narrows the query results based on the assets’ files’ last-modified dates.

Possible values include:

Value	Fetches assets…
`'>= 2018-04-01'`	that were modified on or after 2018-04-01.
`'< 2018-05-01'`	that were modified before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were modified between 2018-04-01 and 2018-05-01.

::: code

{# Fetch assets modified in the last month #}
{% set start = date('30 days ago')|atom %}

{% set assets = craft.assets()
    .dateModified(">= #{start}")
    .all() %}

// Fetch assets modified in the last month
$start = (new \DateTime('30 days ago'))->format(\DateTime::ATOM);

$assets = \craft\elements\Asset::find()
    ->dateModified(">= {$start}")
    ->all();

:::

`dateUpdated`

Narrows the query results based on the assets’ last-updated dates.

Possible values include:

Value	Fetches assets…
`'>= 2018-04-01'`	that were updated on or after 2018-04-01.
`'< 2018-05-01'`	that were updated before 2018-05-01
`['and', '>= 2018-04-04', '< 2018-05-01']`	that were updated between 2018-04-01 and 2018-05-01.

::: code

{# Fetch assets updated in the last week #}
{% set lastWeek = date('1 week ago')|atom %}

{% set assets = craft.assets()
    .dateUpdated(">= #{lastWeek}")
    .all() %}

// Fetch assets updated in the last week
$lastWeek = (new \DateTime('1 week ago'))->format(\DateTime::ATOM);

$assets = \craft\elements\Asset::find()
    ->dateUpdated(">= {$lastWeek}")
    ->all();

:::

`filename`

Narrows the query results based on the assets’ filenames.

Possible values include:

Value	Fetches assets…
`'foo.jpg'`	with a filename of `foo.jpg`.
`'foo*'`	with a filename that begins with `foo`.
`'*.jpg'`	with a filename that ends with `.jpg`.
`'foo'`	with a filename that contains `foo`.
`'not foo'`	with a filename that doesn’t contain `foo`.
`['foo', 'bar']`	with a filename that contains `foo` or `bar`.
`['not', 'foo', 'bar']`	with a filename that doesn’t contain `foo` or `bar`.

::: code

{# Fetch all the hi-res images #}
{% set assets = craft.assets()
    .filename('*@2x*')
    .all() %}

// Fetch all the hi-res images
$assets = \craft\elements\Asset::find()
    ->filename('*@2x*')
    ->all();

:::

`fixedOrder`

Causes the query results to be returned in the order specified by id.

::: code

{# Fetch assets in a specific order #}
{% set assets = craft.assets()
    .id([1, 2, 3, 4, 5])
    .fixedOrder()
    .all() %}

// Fetch assets in a specific order
$assets = \craft\elements\Asset::find()
    ->id([1, 2, 3, 4, 5])
    ->fixedOrder()
    ->all();

:::

`folderId`

Narrows the query results based on the folders the assets belong to, per the folders’ IDs.

Possible values include:

Value	Fetches assets…
`1`	in a folder with an ID of 1.
`'not 1'`	not in a folder with an ID of 1.
`[1, 2]`	in a folder with an ID of 1 or 2.
`['not', 1, 2]`	not in a folder with an ID of 1 or 2.

::: code

{# Fetch assets in the folder with an ID of 1 #}
{% set assets = craft.assets()
    .folderId(1)
    .all() %}

// Fetch assets in the folder with an ID of 1
$assets = \craft\elements\Asset::find()
    ->folderId(1)
    ->all();

:::

::: tip This can be combined with includeSubfolders if you want to include assets in all the subfolders of a certain folder. :::

`height`

Narrows the query results based on the assets’ image heights.

Possible values include:

Value	Fetches assets…
`100`	with a height of 100.
`'>= 100'`	with a height of at least 100.
`['>= 100', '<= 1000']`	with a height between 100 and 1,000.

::: code

{# Fetch XL images #}
{% set assets = craft.assets()
    .kind('image')
    .height('>= 1000')
    .all() %}

// Fetch XL images
$assets = \craft\elements\Asset::find()
    ->kind('image')
    ->height('>= 1000')
    ->all();

:::

`id`

Narrows the query results based on the assets’ IDs.

Possible values include:

Value	Fetches assets…
`1`	with an ID of 1.
`'not 1'`	not with an ID of 1.
`[1, 2]`	with an ID of 1 or 2.
`['not', 1, 2]`	not with an ID of 1 or 2.

::: code

{# Fetch the asset by its ID #}
{% set asset = craft.assets()
    .id(1)
    .one() %}

// Fetch the asset by its ID
$asset = \craft\elements\Asset::find()
    ->id(1)
    ->one();

:::

::: tip This can be combined with fixedOrder if you want the results to be returned in a specific order. :::

`ignorePlaceholders`

Causes the query to return matching assets as they are stored in the database, ignoring matching placeholder elements that were set by craft\services\Elements::setPlaceholderElement().

`inReverse`

Causes the query results to be returned in reverse order.

::: code

{# Fetch assets in reverse #}
{% set assets = craft.assets()
    .inReverse()
    .all() %}

// Fetch assets in reverse
$assets = \craft\elements\Asset::find()
    ->inReverse()
    ->all();

:::

`includeSubfolders`

Broadens the query results to include assets from any of the subfolders of the folder specified by folderId.

::: code

{# Fetch assets in the folder with an ID of 1 (including its subfolders) #}
{% set assets = craft.assets()
    .folderId(1)
    .includeSubfolders()
    .all() %}

// Fetch assets in the folder with an ID of 1 (including its subfolders)
$assets = \craft\elements\Asset::find()
    ->folderId(1)
    ->includeSubfolders()
    ->all();

:::

::: warning This will only work if folderId was set to a single folder ID. :::

`kind`

Narrows the query results based on the assets’ file kinds.

Supported file kinds:

access
audio
compressed
excel
flash
html
illustrator
image
javascript
json
pdf
photoshop
php
powerpoint
text
video
word
xml
unknown

Possible values include:

Value	Fetches assets…
`'image'`	with a file kind of `image`.
`'not image'`	not with a file kind of `image`..
`['image', 'pdf']`	with a file kind of `image` or `pdf`.
`['not', 'image', 'pdf']`	not with a file kind of `image` or `pdf`.

::: code

{# Fetch all the images #}
{% set assets = craft.assets()
    .kind('image')
    .all() %}

// Fetch all the images
$assets = \craft\elements\Asset::find()
    ->kind('image')
    ->all();

:::

`limit`

Determines the number of assets that should be returned.

::: code

{# Fetch up to 10 assets  #}
{% set assets = craft.assets()
    .limit(10)
    .all() %}

// Fetch up to 10 assets
$assets = \craft\elements\Asset::find()
    ->limit(10)
    ->all();

:::

`offset`

Determines how many assets should be skipped in the results.

::: code

{# Fetch all assets except for the first 3 #}
{% set assets = craft.assets()
    .offset(3)
    .all() %}

// Fetch all assets except for the first 3
$assets = \craft\elements\Asset::find()
    ->offset(3)
    ->all();

:::

`orderBy`

Determines the order that the assets should be returned in. (If empty, defaults to dateCreated DESC.)

::: code

{# Fetch all assets in order of date created #}
{% set assets = craft.assets()
    .orderBy('dateCreated asc')
    .all() %}

// Fetch all assets in order of date created
$assets = \craft\elements\Asset::find()
    ->orderBy('dateCreated asc')
    ->all();

:::

`preferSites`

If unique is set, this determines which site should be selected when querying multi-site elements.

For example, if element “Foo” exists in Site A and Site B, and element “Bar” exists in Site B and Site C, and this is set to ['c', 'b', 'a'], then Foo will be returned for Site C, and Bar will be returned for Site B.

If this isn’t set, then preference goes to the current site.

::: code

{# Fetch unique assets from Site A, or Site B if they don’t exist in Site A #}
{% set assets = craft.assets()
    .site('*')
    .unique()
    .preferSites(['a', 'b'])
    .all() %}

// Fetch unique assets from Site A, or Site B if they don’t exist in Site A
$assets = \craft\elements\Asset::find()
    ->site('*')
    ->unique()
    ->preferSites(['a', 'b'])
    ->all();

:::

`relatedTo`

Narrows the query results to only assets that are related to certain other elements.

See Relations for a full explanation of how to work with this parameter.

::: code

{# Fetch all assets that are related to myCategory #}
{% set assets = craft.assets()
    .relatedTo(myCategory)
    .all() %}

// Fetch all assets that are related to $myCategory
$assets = \craft\elements\Asset::find()
    ->relatedTo($myCategory)
    ->all();

:::

`search`

Narrows the query results to only assets that match a search query.

See Searching for a full explanation of how to work with this parameter.

::: code

{# Get the search query from the 'q' query string param #}
{% set searchQuery = craft.app.request.getQueryParam('q') %}

{# Fetch all assets that match the search query #}
{% set assets = craft.assets()
    .search(searchQuery)
    .all() %}

// Get the search query from the 'q' query string param
$searchQuery = \Craft::$app->request->getQueryParam('q');

// Fetch all assets that match the search query
$assets = \craft\elements\Asset::find()
    ->search($searchQuery)
    ->all();

:::

`site`

Determines which site(s) the assets should be queried in.

The current site will be used by default.

Possible values include:

Value	Fetches assets…
`'foo'`	from the site with a handle of `foo`.
`['foo', 'bar']`	from a site with a handle of `foo` or `bar`.
`['not', 'foo', 'bar']`	not in a site with a handle of `foo` or `bar`.
a craft\models\Site object	from the site represented by the object.
`'*'`	from any site.

::: tip If multiple sites are specified, elements that belong to multiple sites will be returned multiple times. If you only want unique elements to be returned, use unique in conjunction with this. :::

::: code

{# Fetch assets from the Foo site #}
{% set assets = craft.assets()
    .site('foo')
    .all() %}

// Fetch assets from the Foo site
$assets = \craft\elements\Asset::find()
    ->site('foo')
    ->all();

:::

`siteId`

Determines which site(s) the assets should be queried in, per the site’s ID.

The current site will be used by default.

::: code

{# Fetch assets from the site with an ID of 1 #}
{% set assets = craft.assets()
    .siteId(1)
    .all() %}

// Fetch assets from the site with an ID of 1
$assets = \craft\elements\Asset::find()
    ->siteId(1)
    ->all();

:::

`size`

Narrows the query results based on the assets’ file sizes (in bytes).

Possible values include:

Value	Fetches assets…
`1000`	with a size of 1,000 bytes (1KB).
`'< 1000000'`	with a size of less than 1,000,000 bytes (1MB).
`['>= 1000', '< 1000000']`	with a size between 1KB and 1MB.

::: code

{# Fetch assets that are smaller than 1KB #}
{% set assets = craft.assets()
    .size('< 1000')
    .all() %}

// Fetch assets that are smaller than 1KB
$assets = \craft\elements\Asset::find()
    ->size('< 1000')
    ->all();

:::

`title`

Narrows the query results based on the assets’ titles.

Possible values include:

Value	Fetches assets…
`'Foo'`	with a title of `Foo`.
`'Foo*'`	with a title that begins with `Foo`.
`'*Foo'`	with a title that ends with `Foo`.
`'Foo'`	with a title that contains `Foo`.
`'not Foo'`	with a title that doesn’t contain `Foo`.
`['Foo', 'Bar']`	with a title that contains `Foo` or `Bar`.
`['not', 'Foo', 'Bar']`	with a title that doesn’t contain `Foo` or `Bar`.

::: code

{# Fetch assets with a title that contains "Foo" #}
{% set assets = craft.assets()
    .title('*Foo*')
    .all() %}

// Fetch assets with a title that contains "Foo"
$assets = \craft\elements\Asset::find()
    ->title('*Foo*')
    ->all();

:::

`trashed`

Narrows the query results to only assets that have been soft-deleted.

::: code

{# Fetch trashed assets #}
{% set assets = craft.assets()
    .trashed()
    .all() %}

// Fetch trashed assets
$assets = \craft\elements\Asset::find()
    ->trashed()
    ->all();

:::

`uid`

Narrows the query results based on the assets’ UIDs.

::: code

{# Fetch the asset by its UID #}
{% set asset = craft.assets()
    .uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    .one() %}

// Fetch the asset by its UID
$asset = \craft\elements\Asset::find()
    ->uid('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx')
    ->one();

:::

`unique`

Determines whether only elements with unique IDs should be returned by the query.

This should be used when querying elements from multiple sites at the same time, if “duplicate” results is not desired.

::: code

{# Fetch unique assets across all sites #}
{% set assets = craft.assets()
    .site('*')
    .unique()
    .all() %}

// Fetch unique assets across all sites
$assets = \craft\elements\Asset::find()
    ->site('*')
    ->unique()
    ->all();

:::

`uploader`

Narrows the query results based on the user the assets were uploaded by, per the user’s IDs.

Possible values include:

Value	Fetches assets…
`1`	uploaded by the user with an ID of 1.
a craft\elements\User object	uploaded by the user represented by the object.

::: code

{# Fetch assets uploaded by the user with an ID of 1 #}
{% set assets = craft.assets()
    .uploader(1)
    .all() %}

// Fetch assets uploaded by the user with an ID of 1
$assets = \craft\elements\Asset::find()
    ->uploader(1)
    ->all();

:::

`volume`

Narrows the query results based on the volume the assets belong to.

Possible values include:

Value	Fetches assets…
`'foo'`	in a volume with a handle of `foo`.
`'not foo'`	not in a volume with a handle of `foo`.
`['foo', 'bar']`	in a volume with a handle of `foo` or `bar`.
`['not', 'foo', 'bar']`	not in a volume with a handle of `foo` or `bar`.
a Volume object	in a volume represented by the object.

::: code

{# Fetch assets in the Foo volume #}
{% set assets = craft.assets()
    .volume('foo')
    .all() %}

// Fetch assets in the Foo group
$assets = \craft\elements\Asset::find()
    ->volume('foo')
    ->all();

:::

`volumeId`

Narrows the query results based on the volumes the assets belong to, per the volumes’ IDs.

Possible values include:

Value	Fetches assets…
`1`	in a volume with an ID of 1.
`'not 1'`	not in a volume with an ID of 1.
`[1, 2]`	in a volume with an ID of 1 or 2.
`['not', 1, 2]`	not in a volume with an ID of 1 or 2.

::: code

{# Fetch assets in the volume with an ID of 1 #}
{% set assets = craft.assets()
    .volumeId(1)
    .all() %}

// Fetch assets in the volume with an ID of 1
$assets = \craft\elements\Asset::find()
    ->volumeId(1)
    ->all();

:::

`width`

Narrows the query results based on the assets’ image widths.

Possible values include:

Value	Fetches assets…
`100`	with a width of 100.
`'>= 100'`	with a width of at least 100.
`['>= 100', '<= 1000']`	with a width between 100 and 1,000.

::: code

{# Fetch XL images #}
{% set assets = craft.assets()
    .kind('image')
    .width('>= 1000')
    .all() %}

// Fetch XL images
$assets = \craft\elements\Asset::find()
    ->kind('image')
    ->width('>= 1000')
    ->all();

:::

`with`

Causes the query to return matching assets eager-loaded with related elements.

See Eager-Loading Elements for a full explanation of how to work with this parameter.

::: code

{# Fetch assets eager-loaded with the "Related" field’s relations #}
{% set assets = craft.assets()
    .with(['related'])
    .all() %}

// Fetch assets eager-loaded with the "Related" field’s relations
$assets = \craft\elements\Asset::find()
    ->with(['related'])
    ->all();

:::

`withTransforms`

Causes the query to return matching assets eager-loaded with image transform indexes.

This can improve performance when displaying several image transforms at once, if the transforms have already been generated.

::: code

{# Fetch assets with the 'thumbnail' and 'hiResThumbnail' transform data preloaded #}
{% set assets = craft.assets()
    .kind('image')
    .withTransforms(['thumbnail', 'hiResThumbnail'])
    .all() %}

// Fetch assets with the 'thumbnail' and 'hiResThumbnail' transform data preloaded
$assets = \craft\elements\Asset::find()
    ->kind('image')
    ->withTransforms(['thumbnail', 'hiResThumbnail'])
    ->all();

:::

Files

asset-queries.md

Latest commit

History

asset-queries.md

File metadata and controls

Asset Queries

Example

Parameters

anyStatus

asArray

clearCachedResult

dateCreated

dateModified

dateUpdated

filename

fixedOrder

folderId

height

id

ignorePlaceholders

inReverse

includeSubfolders

kind

limit

offset

orderBy

preferSites

relatedTo

search

site

siteId

size

title

trashed

uid

unique

uploader

volume

volumeId

width

with

withTransforms

`anyStatus`

`asArray`

`clearCachedResult`

`dateCreated`

`dateModified`

`dateUpdated`

`filename`

`fixedOrder`

`folderId`

`height`

`id`

`ignorePlaceholders`

`inReverse`

`includeSubfolders`

`kind`

`limit`

`offset`

`orderBy`

`preferSites`

`relatedTo`

`search`

`site`

`siteId`

`size`

`title`

`trashed`

`uid`

`unique`

`uploader`

`volume`

`volumeId`

`width`

`with`

`withTransforms`