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.

{
  "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.

{
    "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

{
    "equals":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}

{
    "in":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}

{
    "containsAll":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}

{
    "containsAny":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}

{
    "exists":{
        "property":[
            "property"
        ]
    }
}

{
    "prefix":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}

{
    "range":{
        "property":[
            "property"
        ],
        "gt":1,
        "lte":5
    }
}

{
    "geojsonIntersects":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}

{
    "geojsonDisjoint":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}

{
    "geojsonWithin":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}

{
    "filter":{
        "inAssetSubtree":{
            "property":[
                "sourceFile",
                "assetIds"
            ],
            "values":[
                1,
                2,
                3
            ]
        }
    }
}

{
    "search":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}

Properties

The following overview shows the properties you can filter and which filter applies to which property.

| ["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

This is a special filter field that targets all metadata values.
An alternative to creating a filter for each key in the metadata field. |

Full example

{
   "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.

Example

{
    "sort":[
        {
            "property":[
                "createdTime"
            ],
            "order":"asc",
            
        }
    ]
}