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, and you can't get over it even with the from and size pagination options.

Once a SearchResult has been retrieved, navigation through pages can be done with the SearchResult.next method.

When processing a large number of documents (i.e. more than 1000), it is advised to paginate the results using SearchResult.next rather than increasing the size parameter.

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

Available since 7.4.8

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.

search(index, collection, [query], [options]);

Argument	Type	Description
`index`	string	Index name
`collection`	string	Collection name
`query`	object	Search query
`options`	object	Query options

Options #

Additional query options

Options	Type (default)	Description
`queuable`	boolean (`true`)	If `true`, queues the request during downtime, until connected to Kuzzle again
`from`	number (`0`)	Offset of the first document to fetch
`size`	number (`10`)	Maximum number of documents to retrieve per page
`scroll`	string (`""`)	When set, gets a forward-only cursor having its ttl set to the given value (ie `30s`; cf elasticsearch time limits)
`lang`	string	Specify the query language to use. By default, it's `elasticsearch` but `koncorde` can also be used. Available since 7.4.8
`verb`	string	(HTTP only) Forces the verb of the route
`timeout`	number (`-1`)	Time (in ms) during which a request will still be waited to be resolved. Set it `-1` if you want to wait indefinitely
`triggerEvents`	boolean (`false`)	If set to `true`, will trigger events even if using Embeded SDK. You should always ensure that your events/pipes does not create an infinite loop. Available since Kuzzle 2.31.0

verb #

When instantiated with a HTTP protocol object, the SDK uses the POST API by default for this API route. You can set the verb option to GET to force the SDK to use the GET API instead.

Body properties #

Optional: #

query: the search query itself, using the ElasticSearch Query DSL or the Koncorde Filters DSL syntax.
aggregations: control how the search results should be aggregated
sort: contains a list of fields, used to sort search results, in order of importance.

An empty body matches all documents in the queried collection.

Resolves #

Resolves to a SearchResult object.

Usage #

With the ElasticSearch Query DSL syntax.

Show snippet

const suv = { category: 'suv' };
const limousine = { category: 'limousine' };
try {
  const requests = [];
  for (let i = 0; i < 5; i++) {
    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv));
  }
  for (let i = 0; i < 10; i++) {
    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', limousine));
  }
  await Promise.all(requests);
  await kuzzle.collection.refresh('nyc-open-data', 'yellow-taxi');
  const results = await kuzzle.document.search(
    'nyc-open-data',
    'yellow-taxi',
    {
      query: {
        match: {
          category: 'suv'
        }
      }
    }
  );
  console.log(results);
  /*
    {
      "aggregations": undefined,
      "hits": [
        {
          "_id": "AWgi6A1POQUM6ucJ3q06",
          "_score": 0.046520017,
          "_source": {
            "category": "suv",
            "_kuzzle_info": {
              "author": "-1",
              "createdAt": 1546773859655,
              "updatedAt": null,
              "updater": null
            }
          }
        },
        ...
      ]
    },
    "total": 5,
    "fetched": 5,
    "scroll_id": undefined
  */
  console.log(`Successfully retrieved ${results.total} documents`);
} catch (error) {
  console.error(error.message);
}

With the Koncorde Filters DSL syntax.

Show snippet

const suv = { category: 'suv' };
const limousine = { category: 'limousine' };
try {
  const requests = [];
  for (let i = 0; i < 5; i++) {
    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', suv));
  }
  for (let i = 0; i < 10; i++) {
    requests.push(kuzzle.document.create('nyc-open-data', 'yellow-taxi', limousine));
  }
  await Promise.all(requests);
  await kuzzle.collection.refresh('nyc-open-data', 'yellow-taxi');
  const options = { lang: 'koncorde' };
  const results = await kuzzle.document.search(
    'nyc-open-data',
    'yellow-taxi',
    {
      query: {
        equals: {
          category: 'suv'
        }
      }
    },
    options
  );
  console.log(results);
  /*
    {
      "aggregations": undefined,
      "hits": [
        {
          "_id": "AWgi6A1POQUM6ucJ3q06",
          "_score": 0.046520017,
          "_source": {
            "category": "suv",
            "_kuzzle_info": {
              "author": "-1",
              "createdAt": 1546773859655,
              "updatedAt": null,
              "updater": null
            }
          }
        },
        ...
      ]
    },
    "total": 5,
    "fetched": 5,
    "scroll_id": undefined
  */
  console.log(`Successfully retrieved ${results.total} documents`);
} catch (error) {
  console.error(error.message);
}

Pagination with SearchResult.next

Show snippet

let result = await sdk.document.search('nyc-open-data', 'yellow-taxi', {}, { scroll: '2s' });

while (result) {
  // process result.hits here

  result = await result.next();
}

Edit this page on Github