Search
Search
The Box API provides a way to find content in Box using full-text search queries. Support for the Box search API is available in all our supported SDKs and the CLI.
curl -i -X GET "https://api.box.com/2.0/search?query=sales" \
-H "authorization: Bearer <ACCESS_TOKEN>"
await client.search.searchForContent({
ancestorFolderIds: ['0' as string],
mdfilters: [
{
filters: {
['stringField']: 'stringValue',
['dateField']: {
lt: dateTimeFromString('2035-01-01T00:00:00Z'),
gt: dateTimeFromString('2035-01-03T00:00:00Z'),
} satisfies MetadataFieldFilterDateRange,
['floatField']: {
lt: 9.5,
gt: 10.5,
} satisfies MetadataFieldFilterFloatRange,
['enumField']: 'enumValue2',
['multiSelectField']: ['multiSelectValue1', 'multiSelectValue2'],
},
scope: 'enterprise' as MetadataFilterScopeField,
templateKey: templateKey,
} satisfies MetadataFilter,
],
} satisfies SearchForContentQueryParams);
client.search.search_for_content(
ancestor_folder_ids=["0"],
mdfilters=[
MetadataFilter(
filters={
"stringField": "stringValue",
"dateField": MetadataFieldFilterDateRange(
lt=date_time_from_string("2035-01-01T00:00:00Z"),
gt=date_time_from_string("2035-01-03T00:00:00Z"),
),
"floatField": MetadataFieldFilterFloatRange(lt=9.5, gt=10.5),
"enumField": "enumValue2",
"multiSelectField": ["multiSelectValue1", "multiSelectValue2"],
},
scope=MetadataFilterScopeField.ENTERPRISE.value,
template_key=template_key,
)
],
)
// Find the first 10 files matching "taxes"
long offsetValue = 0;
long limitValue = 10;
BoxSearch boxSearch = new BoxSearch(api);
BoxSearchParameters searchParams = new BoxSearchParameters();
searchParams.setQuery("taxes");
searchParams.setType("file");
PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc'])
for item in items:
print(f'The item ID is {item.id} and the item name is {item.name}')
// Search for PDF or Word documents matching "Meeting Notes"
BoxCollection<BoxItem> results = await client.SearchManager
.QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });
// Search for PDF or Word documents matching "Mobile"
client.search.query(
'Mobile',
{
fields: 'name,modified_at,size,extension,permissions,sync_state',
file_extensions: 'pdf,doc',
limit: 200,
offset: 0
})
.then(results => {
/* results -> {
total_count: 1,
entries:
[ { type: 'file',
id: '11111',
sequence_id: '1',
etag: '1',
sha1: 'f89d97c5eea0a68e2cec911s932eca34a52355d2',
name: 'Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf',
description: '',
size: 408979,
path_collection:
{ total_count: 2,
entries:
[ { type: 'folder',
id: '0',
sequence_id: null,
etag: null,
name: 'All Files' },
{ type: 'folder',
id: '22222',
sequence_id: '1',
etag: '1',
name: 'Marketing Active Work' } ] },
created_at: '2014-05-17T12:59:45-07:00',
modified_at: '2014-05-17T13:00:20-07:00',
trashed_at: null,
purged_at: null,
content_created_at: '2014-05-17T12:58:58-07:00',
content_modified_at: '2014-05-17T12:58:58-07:00',
created_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
modified_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
owned_by:
{ type: 'user',
id: '33333',
name: 'Example User',
login: 'user@example.com' },
shared_link: null,
parent:
{ type: 'folder',
id: '22222',
sequence_id: '1',
etag: '1',
name: 'Marketing Active Work' },
item_status: 'active' } ],
limit: 200,
offset: 0 }
*/
});
let iterator = client.search.query(query: "Quarterly Business Review")
iterator.next { results in
switch results {
case let .success(page):
for item in page.entries {
switch item {
case let .file(file):
print("- File \(file.name) (ID: \(file.id))")
case let .folder(folder):
print("- Folder \(file.name) (ID: \(file.id))")
case let .webLink(webLink):
print("- Web Link \(file.name) (ID: \(file.id))")
}
}
case let .failure(error):
print(error)
}
}
Query operators
The search API supports a few different
search operators, including
AND
, OR
, NOT
and ""
. These operators can be used to refine the search
results to only return items that match a more complicated combination of
search terms.
curl -i -X GET "https://api.box.com/2.0/search?query=box%20AND%20sales" \
-H "Authorization: Bearer <ACCESS_TOKEN>"
Learn more about using logical operators
Search Indexing
Box keeps a search index for any files or folder stored in Box. Every time a file or folder is changed, those words are added to the index. When a search is performed, the API looks in the search index for files and folders that match the query. When content is added, updated, or deleted in Box, the search index is updated accordingly.
Learn more about the Box search index
Comparison to Metadata Queries
At the surface the search API seems very similar to the Metadata Query API, but there are several important differences in how they operate. At a high level the Metadata Queries are optimized for exactness and throughput, while regular search is optimized for relevance to a human user.
Metadata Query API | Search API | |
---|---|---|
What is indexed? | This API only return files/folders based on the values in the metadata templates that are searched | This API returns files, folders and web links based on values in the item names, descriptions, contents (up to the first 10,000 bytes) as well as the associated metadata template instances |
Indexing time | This API will return accurate results as soon as metadata has been added, removed, updated or deleted for a file or folder | This API is subject to a search indexing delay, which is typically 10 minutes yet may be longer in some cases. This means that items may not be returned for more than 10 minutes after metadata has been updated |
Matching | This API uses exact matching based on SQL conventions. Results are returned based on a specified sort order | This API uses fuzzy matching and may return results that vary based on string tokenization, removal of special characters, and other search concepts. Result order is based on either relevance or the updated date of the item |
Conditional logic | This API supports multi-part boolean expressions with comparison operators | This API has limited support for querying by metadata. It only supports querying 1 metadata template at a time and only allows simple query operations. |
Response type | This API returns both the matched file/folder and the associated metadata matched by the query | This API only returns the matched item. A subsequent API call is needed to return each item's metadata |
Throughput | This API is currently subject to per-user rate limits and to a 10 requests per second per enterprise limit | This API supports 6 searches per second per user, up to 60 searches per minute and 12 searches per second per enterprise |
Scale | This API has no limit on the number of items with the specified metadata template that can be returned. It is recommended to only send queries which match no more than 2,000 results. | This API has no limit on number of items with the specified metadata template that can be returned, yet the response time increases significantly as the number of items matching the search grows. This API does have a limit of up to 10 million results for a query. It is recommended to only send queries which match no more than 50,000 results. |
Scope | This API is always limited to the content to which the user has access | This API may be either limited to the content to which the user has access (user_content ) or to all content in the enterprise (enterprise_content ). |
Learn more about the metadata query API