Search for documents

> **Required capabilities:** `filesAcl:READ` This endpoint lets you search for documents by using advanced filters and free text queries. Free text queries are matched against the documents' filenames and contents. ### Free text search #### Boolean operators The `+` symbol represents an AND operation, and the `|` symbol represents an OR. Searching for `lorem + ipsum` will match documents containing both "lorem" AND "ipsum" in the filename or content. Similarly, searching for `lorem | ipsum` will match documents containing either "lorem" OR "ipsum" in the filename or content. The default operator between the search keywords is AND. That means that searching for two terms without any operator, for example, `lorem ipsum`, will match documents containing both the words "lorem" and "ipsum" in the filename or content. You can use the operator `-` to exclude documents containing a specific word. For instance, the search `lorem -ipsum` will match documents that contain the word "lorem", but does NOT contain the word "ipsum". #### Phrases Enclose multiple words inside double quotes `"` to group these words together. Normally, the search query `lorem ipsum` will match not only "lorem ipsum" but also "lorem cognite ipsum", and in general, there can be any number of words between the two words in the query. The search query `"lorem ipsum"`, however, will match only exactly "lorem ipsum" and not "lorem cognite ipsum". #### Escape To search for the special characters (`+`, `|`, `-`, `"`. `\`), escape with a preceding backslash `\`. #### Ordering When you search for a term, the endpoint tries to return the most relevant documents first, with less relevant documents further down the list. There are a few factors that determine the relevance of a document: - If the search terms are found multiple times within a document, the relevance of that document is higher. - For searches with multiple terms, documents containing all the terms are considered more relevant than documents containing only some. - Matches of the terms in the filename field of the document are more relevant than matches in the document's content. #### Examples The following request will return documents matching the specified search query. ```json { "search": { "query": "cognite \"lorem ipsum\"" } } ``` The following example combines a query with a filter. The search request will return documents matching the search query, where `externalId` starts with "1". The results will be ordered by how well they match the query string. ```json { "search":{ "query":"cognite \"lorem ipsum\"" }, "filter":{ "prefix":{ "property":[ "externalId" ], "value":"1" } } } ``` ### Highlights When you enable highlights for your search query, the response contains an additional highlight field for each search hit, including the highlighted fragments for your query matches. However, the result limit is 20 documents due to the operation costs. ### Filtering Filtering uses a special JSON filtering language. It's quite flexible and consists of a number of different "leaf" filters, which can be combined arbitrarily using the boolean clauses `and`, `or`, and `not`. #### Supported leaf filters <table> <tr> <th> <div style="width:150px"> Leaf filter </div> </th> <th> <div style="width:200px"> Supported fields </div> </th> <th> Description </th> </tr> <tr> <td> <code>equals</code> </td> <td> Non-array type fields </td> <td> Only includes results that are equal to the specified value. ```json { "equals":{ "property":[ "property" ], "value":"example" } } ``` </td> </tr> <tr> <td> <code>in</code> </td> <td> Non-array type fields </td> <td> Only includes results that are equal to one of the specified values. ```json { "in":{ "property":[ "property" ], "values":[ 1, 2, 3 ] } } ``` </td> </tr> <td> <code>containsAll</code> </td> <td> Array type fields </td> <td> Only includes results which contain all of the specified values. ```json { "containsAll":{ "property":[ "property" ], "values":[ 1, 2, 3 ] } } ``` </td> <tr> <td> <code>containsAny</code> </td> <td> Array type fields </td> <td> Only includes results which contain all of the specified values. ```json { "containsAny":{ "property":[ "property" ], "values":[ 1, 2, 3 ] } } ``` </td> <tr> <td> <code>exists</code> </td> <td> All fields </td> <td> Only includes results where the specified property exists (has value). ```json { "exists":{ "property":[ "property" ] } } ``` </td> </tr> <tr> <td> <code>prefix</code> </td> <td> String type fields </td> <td> Only includes results which start with the specified value. ```json { "prefix":{ "property":[ "property" ], "value":"example" } } ``` </td> </tr> <tr> <td> <code>range</code> </td> <td> Non-array type fields </td> <td> Only includes results that fall within the specified range. Supported operators: <code>gt</code>, <code>lt</code>, <code>gte</code>, <code>lte</code> ```json { "range":{ "property":[ "property" ], "gt":1, "lte":5 } } ``` </td> </tr> <tr> <td> <code>geojsonIntersects</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape intersects with the specified geometry. ```json { "geojsonIntersects":{ "property":[ "sourceFile", "geoLocation" ], "geometry":{ "type":"Polygon", "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]], } } } ``` </td> </tr> <tr> <td> <code>geojsonDisjoint</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape has nothing in common with the specified geometry. ```json { "geojsonDisjoint":{ "property":[ "sourceFile", "geoLocation" ], "geometry":{ "type":"Polygon", "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]], } } } ``` </td> </tr> <tr> <td> <code>geojsonWithin</code> </td> <td> <code>geoLocation</code> </td> <td> Only includes results where the geoshape falls within the specified geometry. ```json { "geojsonWithin":{ "property":[ "sourceFile", "geoLocation" ], "geometry":{ "type":"Polygon", "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]], } } } ``` </td> </tr> <tr> <td> <code>inAssetSubtree</code> </td> <td> <code>assetIds</code>, <code>assetExternalIds</code> </td> <td> Only includes results with a related asset in a subtree rooted at any specified IDs. ```json { "filter":{ "inAssetSubtree":{ "property":[ "sourceFile", "assetIds" ], "values":[ 1, 2, 3 ] } } } ``` </td> </tr> <tr> <td> <code>search</code> </td> <td> <code>name</code>, <code>content</code> </td> <td> ```json { "search":{ "property":[ "property" ], "value":"example" } } ``` </td> </tr> </table> #### Properties The following overview shows the properties you can filter and which filter applies to which property. | Property | Type | Applicable filters | |------------------------------------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `["id"]` | integer | equals, in, range, exists | | `["externalId"]` | string | equals, in, prefix, exists | | `["instanceId"]` | string | equals, in | | `["instanceId", "space"]` | string | equals, in, prefix, exists | | `["instanceId", "externalId"]` | string | equals, in, prefix, exists | | `["title"]` | string | equals, in, prefix, exists | | `["author"]` | string | equals, in, prefix, exists | | `["createdTime"]` | integer | equals, in, range, exists | | `["modifiedTime"]` | integer | equals, in, range, exists | | `["lastIndexedTime"]` | integer | equals, in, range, exists | | `["mimeType"]` | string | equals, in, prefix, exists | | `["extension"]` | string | equals, in, prefix, exists | | `["pageCount"]` | integer | equals, in, range, exists | | `["type"]` | string | equals, in, prefix, exists | | `["geoLocation"]` | geometry object | geojsonIntersects, geojsonDisjoint, geojsonWithin, exists | | `["language"]` | string | equals, in, prefix, exists | | `["assetIds"]` | array of integers | containsAny, containsAll, exists, inAssetSubtree | | `["assetExternalIds"]` | array of strings | containsAny, containsAll, exists, inAssetSubtree | | `["labels"]` | array of Labels | containsAny, containsAll, exists | | `["content"]` | string | search | | `["sourceFile", "name"]` | string | equals, in, prefix, exists, search | | `["sourceFile", "mimeType"]` | string | equals, in, prefix, exists | | `["sourceFile", "size"]` | integer | equals, in, range, exists | | `["sourceFile", "source"]` | string | equals, in, prefix, exists | | `["sourceFile", "directory"]` | string | equals, in, prefix, exists | | `["sourceFile", "assetIds"]` | array of integers | containsAny, containsAll, exists, inAssetSubtree | | `["sourceFile", "assetExternalIds"]` | array of strings | containsAny, containsAll, exists, inAssetSubtree | | `["sourceFile", "datasetId"]` | integer | equals, in, range, exists | | `["sourceFile", "securityCategories"]` | array of integers | containsAny, containsAll, exists | | `["sourceFile", "geoLocation"]` | geometry object | geojsonIntersects, geojsonDisjoint, geojsonWithin, exists | | `["sourceFile", "labels"]` | array of Labels | containsAny, containsAll, exists | | `["sourceFile", "metadata", <key>]` | string | equals, in, prefix, exists | | `["sourceFile", "metadata"]` | string | equals, in, prefix, exists<br><br>This is a special filter field that targets all metadata values. <br>An alternative to creating a filter for each key in the metadata field. | #### Full example ```json { "filter": { "and": [ { "or": [ { "equals": { "property": [ "type" ], "value": "PDF" } }, { "prefix": { "property": [ "externalId" ], "value": "hello" } } ] }, { "range": { "property": [ "createdTime" ], "lte": 1519862400000 } }, { "not": { "in": { "property": [ "sourceFile", "name" ], "values": [ "My Document.doc", "My Other Document.docx" ] } } } ] } } ``` ### Sorting By default, search results are ordered by relevance, meaning how well they match the given query string. However, it's possible to specify a different property to sort by. Sorting can be ascending or descending. The sort order is ascending if none is specified. #### Properties The following overview shows all properties that can be sorted on. | Property | |---------------------------------| | `["id"]` | | `["externalId"]` | | `["mimeType"]` | | `["extension"]` | | `["pageCount"]` | | `["author"]` | | `["title"]` | | `["language"]` | | `["type"]` | | `["createdTime"]` | | `["modifiedTime"]` | | `["lastIndexedTime"]` | | `["sourceFile", "name"]` | | `["sourceFile", "mimeType"]` | | `["sourceFile", "size"]` | | `["sourceFile", "source"]` | | `["sourceFile", "datasetId"]` | | `["sourceFile", "metadata", *]` | #### Example ```json { "sort":[ { "property":[ "createdTime" ], "order":"asc", } ] } ```