Core
API v2.x
2

search #

Searches documents.

There is a limit to how many documents can be returned by a single search query. That limit is by default set at 10000 documents (see limits.documentsFetchCount), and you can't get over it even with the from and size pagination options.

To handle larger result sets, you have to either create a cursor by providing a value to the scroll option or, if you sort the results, by using the Elasticsearch search_after command.

When using a cursor with the scroll option, Elasticsearch has to duplicate the transaction log to keep the same result during the entire scroll session. It can lead to memory leaks if a scroll duration too large is provided, or if too many scroll sessions are open simultaneously.

Available since 2.2.0

You can restrict the scroll session maximum duration under the services.storage.maxScrollDuration configuration key.

Available since 2.8.0

This method also supports the Koncorde Filters DSL to match documents by passing the lang argument with the value koncorde. Koncorde filters will be translated into an Elasticsearch query.

Koncorde bool operator and regexp clause are not supported for search queries.

Available since 2.17.0

This method also support searching accross multiple indexes and collections using the targets parameter instead of index, collection parameters. See Target Format.

Multi Search is only supported in WebSocket and MQTT protocols.


Query Syntax #

HTTP #

Copied to clipboard!
URL: http://kuzzle:7512/<index>/<collection>/_search[?from=<int>][&size=<int>][&scroll=<time to live>][&lang=<query language>]
Method: POST
Body:
Copied to clipboard!
{
  "query": {
    // ...
  },
  "aggregations": {
    // ...
  },
  "sort": [
    // ...
  ]
}

You can also access this route with the GET verb:

Copied to clipboard!
URL: http://kuzzle:7512/<index>/<collection>/_search[?searchBody=<string>][?from=<int>][&size=<int>][&scroll=<time to live>]
Method: GET

Other protocols #

Search using index & collection parameters

Copied to clipboard!
{
  "index": "<index>",
  "collection": "<collection>",
  "controller": "document",
  "action": "search",
  "body": {
    "query": {
      // ...
    },
    "aggregations": {
      // ...
    },
    "sort": [
      // ...
    ]
  },

  // optional:
  "from": <starting offset>,
  "size": <page size>,
  "scroll": "<scroll duration>",
  "lang": "<query language>"
}

Search using targets parameter

Available since 2.17.0

Copied to clipboard!
{
  "targets": [
    {
      "index": "<index>"
      "collections": ["<collection>", "<anotherCollection>"]
    },
    // ...
  ],
  "controller": "document",
  "action": "search",
  "body": {
    "query": {
      // ...
    },
    "aggregations": {
      // ...
    },
    "sort": [
      // ...
    ]
  },

  // optional:
  "from": <starting offset>,
  "size": <page size>,
  "scroll": "<scroll duration>",
  "lang": "<query language>"
}

Kourou #

Copied to clipboard!
kourou document:search <index> <collection> <query>
kourou document:search <index> <collection> <query> --sort <sort> --size <size>

Arguments #

  • collection: collection name
  • index: index name

or

Optional: #

  • from: paginates search results by defining the offset from the first result you want to fetch. Usually used with the size argument
  • scroll: creates a forward-only result cursor. This option must be set with a time duration, at the end of which the cursor is destroyed. If set, a cursor identifier named scrollId is returned in the results. This cursor can then be moved forward using the scroll API action
  • size: set the maximum number of documents returned per result page
  • lang: specify the query language to use. By default, it's elasticsearch but koncorde can also be used.
    Available since 2.8.0

Body properties #

Optional: #

An empty body matches all documents in the queried collection.

Only the following fields are available in the top level of the search body: aggregations, aggs, collapse, explain, fields, from, highlight, query, search_timeout, size, sort, _name, _source, _source_excludes, _source_includes


Response #

Returns a paginated search result set, with the following properties:

  • aggregations: provides aggregation information. Present only if an aggregations object has been provided in the search body
  • hits: array of found documents. Each document has the following properties:
    • _id: document unique identifier
    • index: index name
      Available since 2.17.0
    • collection: collection name
      Available since 2.17.0
    • _score: relevance score
    • _source: new document content
    • highlight: optional result from highlight API
    • inner_hits: optional result from inner_hits API
      Available since 2.14.1
  • remaining: remaining documents that can be fetched. Present only if the scroll argument has been supplied
    Available since 2.4.0
  • scrollId: identifier to the next page of result. Present only if the scroll argument has been supplied
  • total: total number of found documents. Can be greater than the number of documents in a result page, meaning that other matches than the one retrieved are available
Copied to clipboard!
{
  "status": 200,
  "error": null,
  "index": "<index>",
  "collection": "<collection>",
  "action": "search",
  "controller": "document",
  "requestId": "<unique request identifier>",
  "result": {
    "scrollId": "<scroll id>",
    "hits": [
      {
        "_id": "<document unique identifier>",
        "_score": 1,
        "_source": {
          // document content
        }
      },
      {
        "_id": "<another document unique identifier>",
        "_score": 1,
        "_source": {
          // document content
        }
      }
    ],
    // Present only if aggregation parameters have been set
    "aggregations": {
      "aggs_name": {

      }
    },
    "total": 42
  }
}

Target Format #

Copied to clipboard!
{
  "index": "<index>"
  "collections": ["<collection>", "<anotherCollection>"]
}