Limitations

A few limits apply to the the metadata query APIs.

Files and folders

​A metadata query will only return items (files or folders) to which the requesting user has at least previewer access.

Enterprise vs Global templates

A metadata query only works with metadata templates that have been created by that enterprise. A query will not return results based on the content of free form key-value pairs stored in the ​global.properties template.

Classification metadata templates

Box uses metadata templates to power its content classification. These metadata templates can not be used in metadata queries, as they will most likely run into issues regarding large results sets. More on this next.

There are no immediate plans to start supporting these queries in the future.

Recommended result set size

Where possible it is recommended to only send requests for which the result set is less than 2,000 items.​ The ​result set​ is the entire collection of files and folder that match the metadata query exclusively based on evaluating the ​from​, ​query​, and ​query_params​ parameters - before the requesting user’s permissions and the ​ancestor_folder​ scope are considered.

When sending a metadata query request for which the result set exceeds 2,000 items, the API can only guarantee that it returns all all matching results if both the following conditions are met.

1. The requesting user has at least ​Previewer ​permission to all items in the result set
2. The ancestor folder contains all of the files in the result set

When sending a metadata query request for which the result set exceeds 2,000 items and for which these conditions are not true, the API might return error with a 4XX response code indicating that the query will need to be restricted to return fewer results.

For example, consider the following simplified representation of a metadata template called catalogImages​ which has one string field called ​photographer.

{
  "templateKey": "catalogImages",
  "fields": [
    {
      "type": "string",
      "key": "photographer"
    }
  ]
}

In this example, assume that there are 10 photographers, each of which have captured the same number of images that have the ​catalogImages​ template applied.

Now consider assume that there are 4,000 files in your Box enterprise which have the catalogImages template ​applied and which are split evenly between the two folders,​ Parts​ and Products, ​which are children of the parent folder ​Catalog​ as shown below.

Catalog/
|
|- Parts/
   |
   |- file_0000.jpeg
   |- ...
   |- file_1999.jpeg
|- Products/
   |
   |- file_2000.jpeg
   |- ...
   |- file_3999.jpeg

The following table indicates the outcome of several possible queries. The query is described in plain language for readability.

Remember that the ​result set ​is defined as a collection of items (files and folders) which match the metadata query exclusively based on evaluating the ​from​, ​query​, and ​query_params parameters before the requesting user’s permissions and the ​ancestor_folder​ scope are considered.