List assets

List assets.

Parameters:

name (str | None) – Name of asset. Often referred to as tag.
parent_ids (Sequence[int] | None) – Return only the direct descendants of the specified assets.
parent_external_ids (SequenceNotStr[str] | None) – Return only the direct descendants of the specified assets.
asset_subtree_ids (int | Sequence[int] | None) – Only include assets in subtrees rooted at any of the specified assetIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
asset_subtree_external_ids (str | SequenceNotStr[str] | None) – Only include assets in subtrees rooted at any of the specified assetExternalIds. If the total size of the given subtrees exceeds 100,000 assets, an error will be returned.
data_set_ids (int | Sequence[int] | None) – Return only assets in the specified data set(s) with this id / these ids.
data_set_external_ids (str | SequenceNotStr[str] | None) – Return only assets in the specified data set(s) with this external id / these external ids.
labels (LabelFilter | None) – Return only the assets matching the specified label filter.
geo_location (GeoLocationFilter | None) – Only include files matching the specified geographic relation.
metadata (dict[str, str] | None) – Custom, application specific metadata. String key -> String value.
source (str | None) – The source of this asset.
created_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.
last_updated_time (dict[str, Any] | TimestampRange | None) – Range between two timestamps. Possible keys are min and max, with values given as time stamps in ms.
root (bool | None) – filtered assets are root assets or not.
external_id_prefix (str | None) – Filter by this (case-sensitive) prefix for the external ID.
aggregated_properties (Sequence[AggregateAssetProperty] | None) – Set of aggregated properties to include. Options are childCount, path, depth.
partitions (int | None) – Retrieve resources in parallel using this number of workers (values up to 10 allowed), limit must be set to None (or -1).
limit (int | None) – Maximum number of assets to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
advanced_filter (Filter | dict[str, Any] | None) – Advanced filter query using the filter DSL (Domain Specific Language). It allows defining complex filtering expressions that combine simple operations, such as equals, prefix, exists, etc., using boolean operators and, or, and not. See examples below for usage.
sort (SortSpec | list[SortSpec] | None) – The criteria to sort by. Defaults to desc for _score_ and asc for all other properties. Sort is not allowed if partitions is used.

Returns:

List of requested assets

Return type:

AssetList

Note

When using partitions, there are few considerations to keep in mind:

limit has to be set to None (or -1).
API may reject requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests result in a 400 Bad Request status.
Partitions are done independently of sorting: there’s no guarantee of the sort order between elements from different partitions. For this reason providing a sort parameter when using partitions is not allowed.

Examples

List assets:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> asset_list = client.assets.list(limit=5)

Iterate over assets, one-by-one:

>>> for asset in client.assets():
...     asset  # do something with the asset

Iterate over chunks of assets to reduce memory load:

>>> for asset_list in client.assets(chunk_size=2500):
...     asset_list  # do something with the assets

Filter assets based on labels:

>>> from cognite.client.data_classes import LabelFilter
>>> my_label_filter = LabelFilter(contains_all=["PUMP", "VERIFIED"])
>>> asset_list = client.assets.list(labels=my_label_filter)

Using advanced filter, find all assets that have a metadata key ‘timezone’ starting with ‘Europe’, and sort by external id ascending:

>>> from cognite.client.data_classes import filters
>>> in_timezone = filters.Prefix(["metadata", "timezone"], "Europe")
>>> res = client.assets.list(advanced_filter=in_timezone, sort=("external_id", "asc"))

Note that you can check the API documentation above to see which properties you can filter on with which filters.

To make it easier to avoid spelling mistakes and easier to look up available properties for filtering and sorting, you can also use the AssetProperty and SortableAssetProperty Enums.

>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.assets import AssetProperty, SortableAssetProperty
>>> in_timezone = filters.Prefix(AssetProperty.metadata_key("timezone"), "Europe")
>>> res = client.assets.list(
...     advanced_filter=in_timezone, sort=(SortableAssetProperty.external_id, "asc")
... )

Combine filter and advanced filter:

>>> from cognite.client.data_classes import filters
>>> not_instrument_lvl5 = filters.And(
...     filters.ContainsAny("labels", ["Level5"]),
...     filters.Not(filters.ContainsAny("labels", ["Instrument"])),
... )
>>> res = client.assets.list(
...     asset_subtree_ids=[123456], advanced_filter=not_instrument_lvl5
... )