Suggestion indices

Overview

Suggestion index is a special type of Search Index that is used to store and query textual autocomplete suggestions that are generated from the selected fields in your related document index.

Suggestion indices are used for autocomplete queries. For example, user input tele could result in the following suggestions:

  • television;
  • telephone;
  • mobile telephone;
  • apple telephone.

Suggestion index is always related to one Document index, from which the suggestions are generated.

Document index can have multiple child suggestion indices.

Create suggestion index

API Reference: Create a new Index - choose "Suggestion search index example"

To create suggestion search index, in addition to the usual name and language parameters, add type and sourceIndexId properties:

{
  "language": "en-us",
  "name": "new-suggestion-index-name",
  "type": "SUGGESTION",
  "sourceIndexId": "2d84d7fe-808c-4392-944e-5436bbc34520"
}

  • type - the type of a new Search Index, in this case - SUGGESTION;

  • sourceIndexId - id of the parent document type (DOC) index, from which the suggestions will be generated.

The response will contain the same data as the document index.

Suggestion index does not support direct import of documents via /documents API. If you need to import additional suggestions use Custom Suggestion functionality.

Important: to use autocomplete suggestions, you need to:

  1. Generate suggestions using Suggestion Generation action;

  2. Create suggestion index Query. Suggestion index queries has different format.

Suggestion index mapping

Suggestions are generated from data stored in document type index. As data types are already defined in document type index, you only need to provide data fields that should be included into suggestion generate operation and set other configuration parameters which can make initially generated suggestions to be more accurate.

Parameters

  • fields (array) - Fields defined in document index mapping to be included in suggestion generation.
  • minLength (integer) - Minimum length of generated suggestion phrase
  • excludeNumeric (boolean) - Whether to exclude suggestions with numeric values
  • boost (object) - Map of key-relevance for data fields. Suggestions that are generated from documents that gave higher values of the given properties will be displayed higher;
  • boostAttributeMatch (object) - Boost an importance of a specific field from fields array.
  • statisticalBoost (object) - Boost relevance of specific items during suggestion generation, by using statistics, collected using an Events API.
  • sourceFilters (object) - For suggestion generation only include documents that match given filters. If no sourceFilters are defined, all of the documents will be included. Property schema matches one in Query Configuration.
  • wordSpecialChars - use this field if you need to keep special non alphanumeric characters in your generated suggestions (e.g. hyphen joins two or more words together (up-to-date, one-third), dot keeps the version together (usb 3.0) and so on). Available separators: dot (.), comma (,) apostrophe (').

Example:

{
  "fields": ["title", "description", "brand", "categories"],
  "minLength": 4,
  "excludeNumeric": true,
  "boost": {
    "rating": 3,
    "is_promoted": 2
  },
  "boostAttributeMatch": {
    "categories": 10
  },
  "statisticalBoost": {
    "suggestionClick": 5,
    "addToCart": 2,
    "itemClick": 1
  },
  "sourceFilters": {
    "tags": ["TV", "Electronics"],
    "price": {
      "gt": 10,
      "lt": 20
    }
  }
}

How to set mapping for new suggestion type search index Docs

POST /v1/indices/{indexId}/mapping
{
  "fields": ["title", "description", "brand"],
  "minLength": 4,
  "excludeNumeric": true,
  "boost": {
    "rating": 3,
    "is_promoted": 2
  }
}

How to update mapping for existing suggestion type search index Docs

PUT /v1/indices/{indexId}/mapping
{
  "fields": ["title", "description", "brand"],
  "minLength": 4,
  "excludeNumeric": true,
  "boost": {
    "rating": 3,
    "is_promoted": 2
  }
}