Retrieve a list of assets in the same project. This operation supports pagination by cursor. Apply Filtering and Advanced filtering criteria to select a subset of assets.
Advanced filter lets you create complex filtering expressions that combine simple operations,
such as equals
, prefix
, exists
, etc., using boolean operators and
, or
, and not
.
It applies to basic fields as well as metadata.
See the advancedFilter
attribute in the example.
See more information about filtering DSL here.
Leaf filter | Supported fields | Description |
---|---|---|
containsAll |
Array type fields | Only includes results which contain all of the specified values. {"containsAll": {"property": ["property"], "values": [1, 2, 3]}} |
containsAny |
Array type fields | Only includes results which contain at least one of the specified values. {"containsAny": {"property": ["property"], "values": [1, 2, 3]}} |
equals |
Non-array type fields | Only includes results that are equal to the specified value. {"equals": {"property": ["property"], "value": "example"}} |
exists |
All fields | Only includes results where the specified property exists (has value). {"exists": {"property": ["property"]}} |
in |
Non-array type fields | Only includes results that are equal to one of the specified values. {"in": {"property": ["property"], "values": [1, 2, 3]}} |
prefix |
String type fields | Only includes results which start with the specified value. {"prefix": {"property": ["property"], "value": "example"}} |
range |
Non-array type fields | Only includes results that fall within the specified range. {"range": {"property": ["property"], "gt": 1, "lte": 5}} Supported operators: gt , lt , gte , lte |
search |
["name"] , ["description"] |
Introduced to provide functional parity with /assets/search endpoint. {"search": {"property": ["property"], "value": "example"}} |
The search
leaf filter provides functional parity with the /assets/search
endpoint.
It's available only for the ["description"]
and ["name"]
properties. When specifying only this filter with no explicit ordering,
behavior is the same as of the /assets/search/
endpoint without specifying filters.
Explicit sorting overrides the default ordering by relevance.
It's possible to use the search
leaf filter as any other leaf filter for creating complex queries.
See the search
filter in the advancedFilter
attribute in the example.
and
and or
clauses must have at least one elementproperty
array of each leaf filter has the following limitations:containsAll
, containsAny
, and in
filter values
array size must be in the range [1, 100]containsAll
, containsAny
, and in
filter values
array must contain elements of a primitive type (number, string)range
filter must have at least one of gt
, gte
, lt
, lte
attributes.
But gt
is mutually exclusive to gte
, while lt
is mutually exclusive to lte
.
At least one of the bounds must be specified.gt
, gte
, lt
, lte
in the range
filter must be a primitive valuesearch
filter value
must not be blank and the length must be in the range [1, 128]externalId
- 255name
- 128 for the search
filter and 255 for other filtersdescription
- 128 for the search
filter and 255 for other filterslabels
item - 255source
- 128metadata
key - 128By default, assets are sorted by id
in the ascending order.
Use the search
leaf filter to sort the results by relevance.
Sorting by other fields can be explicitly requested. The order
field is optional
and defaults to desc
for _score_
and asc
for all other fields.
The nulls
field is optional and defaults to auto
. auto
is translated to
last
for the asc
order and to first
for the desc
order by the service.
Partitions are done independently of sorting; there's no guarantee of the sort order between elements from different partitions.
See the sort
attribute in the example.
In case the nulls
attribute has the auto
value or the attribute isn't specified,
null (missing) values are considered to be bigger than any other values.
They are placed last when sorting in the asc
order and first when sorting in desc
.
Otherwise, missing values are placed according to the nulls
attribute (last or first), and their placement doesn't depend on the order
value.
Values, such as empty strings, aren't considered as nulls.
Use a special sort property _score_
when sorting by relevance.
The more filters a particular asset matches, the higher its score is. This can be useful,
for example, when building UIs. Let's assume we want exact matches to be be displayed above matches by
prefix as in the request below. An asset named pump
will match both equals
and prefix
filters and, therefore, have higher score than assets with names like pump valve
that match only prefix
filter.
"advancedFilter" : {
"or" : [
{
"equals": {
"property": ["name"],
"value": "pump"
}
},
{
"prefix": {
"property": ["name"],
"value": "pump"
}
}
]
},
"sort": [
{
"property" : ["_score_"]
}
]
This endpoint is meant for data analytics/exploration usage and is not suitable for high load data retrieval usage. It is a subject of the new throttling schema (limited request rate and concurrency). Please check Assets resource description for more information.
object (Filter) Filter on assets with strict matching. | |||||||||||||||||||||||||||||
(BoolFilter (and (object) or or (object) or not (object))) or (LeafFilter (equals (object) or in (object) or range (object) or prefix (object) or exists (object) or containsAny (object) or containsAll (object) or search (object))) A filter DSL (Domain Specific Language) to define advanced filter queries. See more information about filtering DSL here. Supported properties:
Note: Filtering on the | |||||||||||||||||||||||||||||
limit | integer <int32> [ 1 .. 1000 ] Default: 100 Limits the number of results to return. | ||||||||||||||||||||||||||||
Array of objects (AssetSortProperty) [ 1 .. 2 ] items Sort by array of selected properties. | |||||||||||||||||||||||||||||
cursor | string | ||||||||||||||||||||||||||||
aggregatedProperties | Array of strings (AggregatedProperty) Set of aggregated properties to include | ||||||||||||||||||||||||||||
partition | string (PartitionLimited10) Splits the data set into The maximum number of allowed partitions ( Cognite rejects requests if you specify more than 10 partitions. When Cognite enforces this behavior, the requests result in a 400 Bad Request status. |
Paged response with list of assets.
The response for a bad request.
The response for too many requests (concurrency or rate throttling).
{- "filter": {
- "name": "string",
- "parentIds": [
- 1
], - "parentExternalIds": [
- "my.known.id"
], - "rootIds": [
- {
- "id": 1
}
], - "assetSubtreeIds": [
- {
- "id": 1
}
], - "dataSetIds": [
- {
- "id": 1
}
], - "metadata": {
- "property1": "string",
- "property2": "string"
}, - "source": "string",
- "createdTime": {
- "max": 0,
- "min": 0
}, - "lastUpdatedTime": {
- "max": 0,
- "min": 0
}, - "root": true,
- "externalIdPrefix": "my.known.prefix",
- "labels": {
- "containsAny": [
- {
- "externalId": "my.known.id"
}
]
}, - "geoLocation": {
- "relation": "INTERSECTS",
- "shape": {
- "type": "Point",
- "coordinates": [
- 0,
- 0
]
}
}
}, - "advancedFilter": {
- "or": [
- {
- "not": {
- "and": [
- {
- "equals": {
- "property": [
- "metadata",
- "asset_type"
], - "value": "gas pump"
}
}, - {
- "in": {
- "property": [
- "source"
], - "values": [
- "blueprint",
- "inventory"
]
}
}, - {
- "range": {
- "property": [
- "dataSetId"
], - "gte": 1,
- "lt": 10
}
}
]
}
}, - {
- "and": [
- {
- "containsAny": {
- "property": [
- "labels"
], - "values": [
- "pump",
- "cooler"
]
}
}, - {
- "equals": {
- "property": [
- "parentId"
], - "value": 95867294876
}
}
]
}, - {
- "search": {
- "property": [
- "description"
], - "value": "My favorite pump"
}
}
]
}, - "limit": 100,
- "sort": [
- {
- "property": [
- "createdTime"
], - "order": "desc"
}, - {
- "property": [
- "metadata",
- "customMetadataKey"
], - "nulls": "first"
}
], - "cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
- "aggregatedProperties": [
- "childCount"
], - "partition": "1/3"
}
{- "items": [
- {
- "createdTime": 0,
- "lastUpdatedTime": 0,
- "rootId": 1,
- "aggregates": {
- "childCount": 0,
- "depth": 0,
- "path": [
- {
- "id": 1
}
]
}, - "parentId": 1,
- "parentExternalId": "my.known.id",
- "externalId": "my.known.id",
- "name": "string",
- "description": "string",
- "dataSetId": 1,
- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "source": "string",
- "labels": [
- {
- "externalId": "my.known.id"
}
], - "geoLocation": {
- "type": "Feature",
- "geometry": {
- "type": "Point",
- "coordinates": [
- 0,
- 0
]
}, - "properties": { }
}, - "id": 1
}
], - "nextCursor": "string"
}