Queries

By using Queries, you can create rules that define how search is performed within your Index: which fields are included in user query, what kind of properties are returned with the results, and so on.

This quick-start page describes the most basic search Queries. For more advanced query configuration, please refer to Queries - Advanced, or view our Examples.

One Index can have an unlimited amount of search queries.

Create Query API - Request

To create a new query, issue a new POST request, using indexId created in the previous steps:

/v1/indices/{indexId}/queries

The request body consist of general settings and Query configuration, which describes how data in the Index should be queried:

{
  "description": "Custom search query description",
  "debugMode": false,
  "configuration": {
    "queryFields": {
      "name": 1,
    },
    "selectFields": [
      "id",
      "name",
      "category",
      "rating"
    ],
    "match": "all"
  }
}

Query settings

  • description (optional) - any custom string to describe the purpose of the Query;

  • debugMode - if set to false, all errors that occur while executing Public Query will be hidden from the end user;

Query configuration

  • queryFields - a configuration map, that describes which document fields should be included in the user search. Property values can be used to boost the importance of each field. For example, configuration {"name": 5, "description": 2} will give more importance to the matches in document name, and such documents will appear higher in the product list; All properties must be defined in Index Mapping.

  • selectFields - a list of document properties to return with the results. All properties must be defined in Index Mapping.

  • match - defines the process of query terms matching. all will only return documents that match ALL terms (words) in the search query; any will return return documents that match ANY of the terms in the search query, while keeping most relevant results at the top.

Create Query API - Response

If the Query creation is successful, created search query will be returned with the response:

{
  "id": "1b785fc1-7740-4f6a-b350-cb3906cd3eb0",
  "description": "Custom search query description",
  "createdBy": "de4e47ca-d76e-4d8a-a7f2-dea5f3787059",
  "createdAt": "2021-11-08T12:10:33.000Z",
  "updatedAt": "2021-11-08T12:10:33.000Z",
  "queryKey": "kef5fy0nlhll",
  "debugMode": 1,
  "configuration": {
    "queryFields": {
      "name": 1,
    },
    "selectFields": [
      "id",
      "name",
      "category",
      "rating"
    ],
    "match": "all"
  }
}

There are a couple of new fields in the response that need to be noted:

  • id - unique Query identifier. Used in Query Update and Delete endpoints;

  • queryKey - query key that is used to reference this new Query configuration in Public Query endpoints. Save this key for the next step.

Next steps

After query is configured, we can now use the queryKey to execute searches with Public Queries:

Continue

See also: