Search for documents

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.

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

Leaf filter
Supported fields
Description
equals Non-array type fields Only includes results that are equal to the specified value.
{
    "equals":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}
in Non-array type fields Only includes results that are equal to one of the specified values.
{
    "in":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}
containsAll Array type fields Only includes results which contain all of the specified values.
{
    "containsAll":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}
containsAny Array type fields Only includes results which contain all of the specified values.
{
    "containsAny":{
        "property":[
            "property"
        ],
        "values":[
            1,
            2,
            3
        ]
    }
}
exists All fields Only includes results where the specified property exists (has value).
{
    "exists":{
        "property":[
            "property"
        ]
    }
}
prefix String type fields Only includes results which start with the specified value.
{
    "prefix":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}
range Non-array type fields Only includes results that fall within the specified range.

Supported operators: gt, lt, gte, lte

{
    "range":{
        "property":[
            "property"
        ],
        "gt":1,
        "lte":5
    }
}
geojsonIntersects geoLocation Only includes results where the geoshape intersects with the specified geometry.
{
    "geojsonIntersects":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}
geojsonDisjoint geoLocation Only includes results where the geoshape has nothing in common with the specified geometry.
{
    "geojsonDisjoint":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}
geojsonWithin geoLocation Only includes results where the geoshape falls within the specified geometry.
{
    "geojsonWithin":{
        "property":[
            "sourceFile",
            "geoLocation"
        ],
        "geometry":{
            "type":"Polygon",
            "coordinates": [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]],
        }
    }
}
inAssetSubtree assetIds, assetExternalIds Only includes results with a related asset in a subtree rooted at any specified IDs.
{
    "filter":{
        "inAssetSubtree":{
            "property":[
                "sourceFile",
                "assetIds"
            ],
            "values":[
                1,
                2,
                3
            ]
        }
    }
}
search name, content
{
    "search":{
        "property":[
            "property"
        ],
        "value":"example"
    }
}

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

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

{
    "sort":[
        {
            "property":[
                "createdTime"
            ],
            "order":"asc",
            
        }
    ]
}
Securityoidc-token or oauth2-client-credentials or oauth2-open-industrial-data or oauth2-auth-code
Request
path Parameters
project
required
string

The project name.

Example: publicdata
Request Body schema: application/json
required

Fields to be set for the search request.

object
(bool filters (and (object) or or (object) or not (object))) or (leaf filters (equals (object) or in (object) or containsAny (object) or containsAll (object) or range (object) or prefix (object) or search (object) or exists (object) or geojsonIntersects (object) or geojsonDisjoint (object) or geojsonWithin (object) or inAssetSubtree (object))) (DocumentFilter)

A JSON based filtering language. See detailed documentation above.

Array of objects (DocumentSearchCountAggregate) [ 1 .. 5 ] items
Deprecated
Array of objects (DocumentSortItem) = 1 items

List of properties to sort by. Currently only supports 1 property.

limit
integer <int32> [ 0 .. 1000 ]
Default: 100

Maximum number of items. When using highlights the maximum value is reduced to 20.

cursor
string

Cursor for paging through results.

highlight
boolean

Whether or not matches in search results should be highlighted.

Responses
200

The results of a search.

400

The response for a failed request.

post/documents/search
Request samples
application/json
{
  • "search": {
    • "query": "cognite \"lorem ipsum\"",
    • "highlight": false
    },
  • "filter": {
    • "and": [
      ]
    },
  • "aggregates": [
    • {
      }
    ],
  • "sort": [
    • {
      }
    ],
  • "limit": 100,
  • "cursor": "string",
  • "highlight": true
}
Response samples
application/json
{
  • "items": [
    • {
      }
    ],
  • "aggregates": [
    • {
      }
    ],
  • "nextCursor": "string"
}