Query files/folders by metadata
Create a search using SQL-like syntax to return items that match specific metadata.
This feature currently has limited availability. To enable this feature, contact our Metadata Query team.
Request
Request Body
0The ID of the folder that you are restricting the query to. A value of zero will return results from all folders you have access to. A non-zero value will only return results found in the folder corresponding to the ID or in any of its subfolders.
enterprise_123456.someTemplateSpecifies the template used in the query. Must be in the form
scope.templateKey.
50100100A value between 0 and 100 that indicates the maximum number of results to return for a single request. This only specifies a maximum boundary and will not guarantee the minimum number of results returned.
AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ffMarker to use for requesting the next page.
A list of template fields and directions to sort the metadata query results by.
The ordering direction must be the same for each item in the array.
ascThe direction to order by, either ascending or descending.
The ordering direction must be the same for each item in the
array.
Value is one of ASC,DESC,asc,desc
amountThe metadata template field to order by.
The field_key represents the key value of a field from the
metadata template being searched for.
value >= :amountThe query to perform. A query is a logical expression that is very similar
to a SQL SELECT statement. Values in the search query can be turned into
parameters specified in the query_param arguments list to prevent having
to manually insert search values into the query string.
For example, a value of :amount would represent the amount value in
query_params object.
Set of arguments corresponding to the parameters specified in the
query. The type of each parameter used in the query_params must match
the type of the corresponding metadata template field.
100The value for the argument being used in the metadata search.
The type of this parameter must match the type of the corresponding metadata template field.
amountAscThe name of the search index to use for this query. A search index is required when a metadata template is assigned to more than 10,000 files and folders.
Please contact our Metadata Query team to create a search index.
Response
Returns a list of files and folders that match this metadata query.
Returns an error when the request body is not valid.
invalid_query- Any of the provided body parameters might be incorrect. This can mean thequeryis incorrect, as well as some cases where thefromvalue does not represent a valid template.unexpected_json_type- An argument from thequerystring is not present inquery_param. For example,queryofname = :namerequires thequery_paramto include a value for thenameargument, for example{ "name": "Box, Inc" }.
Returns an error when a metadata template with the given scope and
templateKey can not be found. The error response will include extra
details.
instance_not_found- The template could not be found. Please make sure to use the full template scope including the enterprise ID, likeenterprise_12345.
An unexpected client error.
Request Example
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
-H 'Content-Type: application/json" '
-d '{
"from": "enterprise_123456.contractTemplate",
"query": "amount >= :value",
"query_params": {
"value": 100
},
"ancestor_folder_id": "5555",
"use_index": "amountAsc",
"order_by": [
{
"field_key": "amount",
"direction": "asc"
}
],
"limit": 100
}'String from = "enterprise_341532.test";
String query = "testfield = :arg";
String ancestorFolderId = "0";
JsonObject queryParameters = new JsonObject().add("arg", "test");
BoxResourceIterable<BoxMetadataQueryItem> results = MetadataTemplate.executeMetadataQuery(api, from, query, queryParameters, ancestorFolderId);
for (BoxMetadataQueryItem r: results) {
String customFieldValue = r.getMetadata().get("enterprise_341532").get(0).get("/customField");
System.out.println(customFieldValue);
}var from = 'enterprise_12345.someTemplate',
ancestorFolderId = '5555',
options = {
query: 'amount >= :arg',
queryParams: {
arg: 100
},
useIndex: 'amountAsc',
orderBy: [
{
field_key: 'amount',
direction: 'asc'
}
],
limit: 100,
marker: 'AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff'
};
client.metadata.query(from, ancestorFolderId, options)
.then(items => {
/* items -> {
"entries": [
{
"item": {
"type": "file",
"id": "1617554169109",
"file_version": {
"type": "file_version",
"id": "1451884469385",
"sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6"
},
"sequence_id": "0",
"etag": "0",
"sha1": "69888bb1bff455d1b2f8afea75ed1ff0b4879bf6",
"name": "My Contract.docx",
"description": "",
"size": 25600,
"path_collection": {
"total_count": 4,
"entries": [
{
"type": "folder",
"id": "0",
"sequence_id": null,
"etag": null,
"name": "All Files"
},
{
"type": "folder",
"id": "15017998644",
"sequence_id": "0",
"etag": "0",
"name": "Contracts"
},
{
"type": "folder",
"id": "15286891196",
"sequence_id": "1",
"etag": "1",
"name": "North America"
},
{
"type": "folder",
"id": "16125613433",
"sequence_id": "0",
"etag": "0",
"name": "2017"
}
]
},
"created_at": "2017-04-20T12:55:27-07:00",
"modified_at": "2017-04-20T12:55:27-07:00",
"trashed_at": null,
"purged_at": null,
"content_created_at": "2017-01-06T17:59:01-08:00",
"content_modified_at": "2017-01-06T17:59:01-08:00",
"created_by": {
"type": "user",
"id": "193973366",
"name": "Box Admin",
"login": "admin@company.com"
},
"modified_by": {
"type": "user",
"id": "193973366",
"name": "Box Admin",
"login": "admin@company.com"
},
"owned_by": {
"type": "user",
"id": "193973366",
"name": "Box Admin",
"login": "admin@company.com"
},
"shared_link": null,
"parent": {
"type": "folder",
"id": "16125613433",
"sequence_id": "0",
"etag": "0",
"name": "2017"
},
"item_status": "active"
},
"metadata": {
"enterprise_123456": {
"someTemplate": {
"$parent": "file_161753469109",
"$version": 0,
"customerName": "Phoenix Corp",
"$type": "someTemplate-3d5fcaca-f496-4bb6-9046-d25c37bc5594",
"$typeVersion": 0,
"$id": "ba52e2cc-371d-4659-8d53-50f1ac642e35",
"amount": 100,
"claimDate": "2016-04-10T00:00:00Z",
"region": "West",
"$typeScope": "enterprise_123456"
}
}
}
}
],
"next_marker": ""
}
*/
});