Using Filters
The Assets query can take an option “filters” parameter. These filters use “RESTful Service Query Language” (RSQL), a query language that lets you filter things.
The RSQL logic only matches the attributes and components in the asset (more specifically, the latest asset revision) itself. For example, currently it cannot:
- Match against the parent assets/projects
- Match any relationships from or into the asset
The first part of this topic shows you various examples that you can use right away while the second part is more of a reference.
There are two types of queries: the string version where the query is
one expression string and a structured version where the expression is
a json object. The examples here are string versions, as they are
easier to read. See Structured Queries below for how to convert the
string version to a structured version.
Examples
Find all the assets with a certain name (case-sensitive match):
"filter": "attribute.name=='asset alpha'"
Find all the assets that have a description that contains descr
(case-insensitive):
"filter": "attribute.description=like=*descr*"
Find all the assets with a last version greater than zero:
"filter": "attribute.version>0"
Find all the assets with an id that contains the characters “3Y”:
"filter": "attribute.id=like='*3Y*'"
Conditionals can be combined using the ; (and) operator. You can use
, for (or):
"filter": "attribute.description=like=*descr*;attribute.version>0"
Find all the assets that have at least one component of this type:
"filter": "components.typeId==autodesk.data.l2fs:components.link-1.0.0"
Find all the assets that have at least one component of this type (any version):
"filter": "components.typeId=like=autodesk.data.l2fs:components.link-*"
Find all the assets that have a component with the name “name1”:
"filter": "components.name==name1"
To look at the data fields of components, use the .data field. For
example, this query matches an asset if at least one component`s path
value (under a data value) has the value “maya.txt”. The extra
.data field here is intentional, as the component itself contains a
field called “data”:
"filter": "components.data.data.path==maya.txt"
The previous query will look at all the components of the asset. You should filter these down to those of a certain type to reduce false positives. To look at just the binary components, for example:
"filter": "components[typeId:autodesk.me:component.binary-1.0.0].data.data.path==maya.txt"
You can even use wild cards in the typeId:
"filter": "components[typeId:*:components.binary-*].data.data.path==maya.txt"
"filter": "components[typeId:autodesk.me:components.playlist-*].data.assets.objectId==sA1nVsmrEuP1Z8A1GhPgl_L2C::zIUCyp0CGUABqXT6HsgmQV_ags::CfVyIaehs5G7NVCUsUDOei_aga"
You can examine only the components with a certain name if you know it:
"filter": "components[name:multi_files].data.data.path==maya.txt"
components.data now allows you to also filter by object types. This
means that it will only check sub-data objects that have a typeid (lower
case id) of a certain field. Once matched, you can match fields under
that class. The first use case for this is finding all the reference
data objects within any components that might be referring to a certain
asset or revision. For example:
"filter": "components.data[typeId:autodesk.data:reference-1.0.0].objectId=='G4CjSeJiWxwrkHG6D5ErBF_L2C::LQntOvVgAxUSdXMwAdPszS_ags::9vME4XqZHrQFsJG4OPTgNS_aga'"
This would match the following the component:
{
"name": "capture1",
"typeId": "movieLabs.omc:capture-1.0.0",
"data": {
"slate": {
"typeid": "autodesk.data:reference-1.0.0",
"objectId": "G4CjSeJiWxwrkHG6D5ErBF_L2C::LQntOvVgAxUSdXMwAdPszS_ags::9vME4XqZHrQFsJG4OPTgNS_aga",
"revisionId": "",
"objectTypeId": "Asset"
},
"productionScene": {
"typeid": "autodesk.data:reference-1.0.0",
"objectId": "",
"revisionId": "",
"objectTypeId": ""
}
}
}
RSQL Reference
This section describes all the operators available in the RSQL processor.
attribute field
The attribute field lets you compare the attributes of an asset or task. The form is:
attribute.X
where X specifies the attributes in the asset or task.
components field
The components condition allows you to query the types, names and data values of components. The full form is:
components[selectorfilter].topField.subfields
components[selectorfilter].data[dataFilter].subfields
where:
- selectorfilter is an optional filter of the form name:X or
typeId:X. name: will match the components name/id while typeId will
match the components type string. Both are interpreted as
likeexpressions, which means they can contain * (wild cards) and are matched case-insensitively. - topField must be one of
typeIdnameordata. These correspond to the main top level fields of a component. - subfields are only valid for
dataand when provided and go into thedatavalues of a component - dataFiler is only valid for
dataand must be of the form typeId:X. When provided it means that data of the matched components will be recursively searched. For each sub object that has a typeid=like=X (note the lower case typeid here), then the subfields will be applied and evaluated
Note that the components field often matches many things and the final condition is true if at least one field matches. For example:
components.typeId==autodesk.data.l2fs:components.link-1.0.0 means:
components.typeIdwill be a (possibly empty) list of all the types of all the components- a strict equality (==) check will be done between each member of the list and the given string
- if any of those are true, then the whole expression is true
- EXCEPTION: If the operator is a negative type
(!= =nlike= =out=)then the whole expression is true only if ALL of the checks are true This list collection logic applies to data types as well. For example,components.data.assets.objectIdwill produce a list by iterating over all: - components,
- assets fields in each component
- objectId fields in each assets field
- EXCEPTION: If the operator is a negative type
has.component.type field
This is a field kept for backwards compatibility. It`s effectively the same as “components.typeId”. This is implemented as an APS Asset Graph and has a very important caveat: When it fails to match an asset, it will stop the search down that asset`s containment path. For example, if you have any folders that don`t match the condition, its child assets will not be checked and won`t be included in the results even if they would have matched.
Conditional & Comparison Operators
| Operator | Description | Example |
|---|---|---|
| ; and | AND operator | attribute.name==alex;attribute. description==description attribute.name==alex and attribute.description==description |
| , or | OR operator | attribute.name==alex,attribute.description==description attribute.name==alex or attribute.description==description |
Structured Queries
Rather than passing a string, the API supports a “structured” (JSON-based) API that lets you formulate the query in terms of objects and strings. The main advantage of this is that its easier for programs to assemble queries without messing up string escaping.
Note: The current structured isn`t 1:1 feature equivalent to the string
version. For example, it assumes an and operation between all the
fields. If or is desired, it can be added.
The form of the structured query is:
{
"attribute.name": {
"$eq": "alex"
}
"components[name:compname].data.field": {
"$ne": "some value"
}
"attribute.description": "value with assumed $eq"
}
This structure lists some field comparisons that will be ANDed together.
For each field, you can specify the comparison operator (such as
:math: eq’ for equality) and the value to compare against. You can omit the comparison operator to imply ‘\ eq
(as shown in the “value with assumed $eq” example above).
Structured Operators
| Structured | RSQL | Notes | Example |
|---|---|---|---|
| $eq | == | Exact match for strings. Also works on numbers. | attribute.name==Alex |
| $ne | != | Inverse of == | attribute.name!=Alex |
| $gte | >=, =ge= | Comparisons. Mostly for numbers. | components.data.fileSize >= 10000 |
| $lt | <, =lt= | Comparisons. Mostly for numbers. | components.data.fileSize < 10000 |
| $lte | <=, =le= | Comparisons. Mostly for numbers. | components.data.fileSize <= 10000 |
| $in | =in= | Returns true if left appears at least once in right array | attribute.name=in= (Alex,Bob) |
| $nin | =out= | inverse of $in | attribute.name=out= (Alex,Bob) |
| $like | =like= | Uses wildcards (just *) and
case insensitive matching |
attribute.name=like= lex |
| $nlike | =nlike= | inverse of $like | attribute.name=nlike= lex |