Query syntax

The query syntax for the metadata query API is similar to that of a SQL database. To query for all files and folders that match a contract metadata template with a contract value of over $100 the following metadata query could be created.

{
  "from": "enterprise_123456.contractTemplate",
  "query": "amount >= :value",
  "query_params": {
    "value": 100
  },
  "fields": [
    "name",
    "metadata.enterprise_123456.contractTemplate.amount"
  ],
  "ancestor_folder_id": "5555"
}

In this case the from value represents the scope and templateKey of the metadata template, and the ancestor_folder_id represents the folder ID to search within, including its subfolders.

The fields parameter

By default, this API will only return the base-representation of a file or folder, which includes their id, type, and etag values. To request any additional data the fields parameter can be used to query any additional fields, as well as any metadata associated to the item.

For example:

• created_by will add the details of the user who created the item to the response.
• metadata.<scope>.<templateKey> will return the base-representation of the metadata instance identified by the scope and templateKey.
• metadata.<scope>.<templateKey>.<field> will return all fields in the base-representation of the metadata instance identified by the scope and templateKey plus the field specified by the field name. Multiple fields for the same scope and templateKey can be defined.

The query parameter

The query parameter represents the SQL-like query to perform on the selected metadata instance. This parameter is optional, and without this parameter the API would return all files and folders for this template.

Every left hand field name, like amount, needs to match the key of a field on the associated metadata template. In other words, you can only search for fields that are actually present on the associated metadata instance. Any other field name will result in the error returning an error.

The query_params parameter

To make it less complicated to embed dynamic values into the query string, an argument can be defined using a colon syntax, like :value. Each argument that is specified like this needs a subsequent value with that key in the query_params object, for example:

{
  ...,
  "query": "amount >= :amount AND country = :country",
  "query_params": {
    "amount": 100,
    "country": "United States"
  },
  ...
}

Logical operators

A query supports the following logical operators.

Comparison operators

A query supports the following comparison operators.

Pattern matching

The LIKE, NOT LIKE, ILIKE, and NOT ILIKE operators match a string to a pattern. The pattern supports the following reserved characters.

• % The percent sign represents zero, one, or multiple characters, for example %Contract matches Contract, Sales Contract, but not Contract (Sales),
• _ The underscore represents a single character, for example Bo_ matches Box, Bot, but not Bots,

Both of these reserved characters can be used before, after, or in between other characters. A pattern can include multiple reserved characters, for example Box% (____) would match Box Contract (2020).

An example query would looks something like this. Note that the %-wrapped string is not in the query attribute but in the list of query_params.

{
  ...,
  "query": "country ILIKE :country",
  "query_params": {
    "country": "%United%"
  },
  ...
}