Request

Response

    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": ""
        }
      }
    }
    
    Show More

    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 like expressions, which means they can contain * (wild cards) and are matched case-insensitively.
    • topField must be one of typeId name or data. These correspond to the main top level fields of a component.
    • subfields are only valid for data and when provided and go into the data values of a component
    • dataFiler is only valid for data and 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.typeId will 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.objectId will produce a list by iterating over all:
      • components,
      • assets fields in each component
      • objectId fields in each assets field

    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

    OperatorDescriptionExample
    ; 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"
    }
    
    Show More

    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

    StructuredRSQLNotesExample
    $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