Suggestion Queries

Create suggestion query

API Reference: Create Suggestion Query. Select "Suggestion search query" example.

To create a simplest suggestion query, issue a POST request for the chosen SUGGESTION index:

{
  "description": "Suggestion search query description",
  "configuration": {
    "limit": 10
  },
  "debugMode": true
}

Suggestion public query

Suggestion public query always accepts only two parameters: searchText and limit:

{
  "searchText": "tele",
  "limit": 5
}

Suggestion public query response

Simple suggestion query response will include an array of suggestions that match the searchText query:

[
  {
    "suggestion": "telephone"
  },
   {
    "suggestion": "telemarketing"
  }
  {
    "suggestion": "mobile telephone"
  },
  {
    "suggestion": "mobile telephone android"
  },
  {
    "suggestion": "mobile telephone apple"
  },
]

Updating, deleting suggestion query

Suggestion query can be updated or deleted in the same way as the regular query. See here.

Suggestion query configuration

Limit

Control the initial suggestion limit. Must be between 1 and 100.

{
  "configuration": {
    "limit": 10
  }
}

Can be overridden with a public query.

Fuzziness

Control the typo tolerance for the query:

{
  "configuration": {
    "fuzzy": {
      "prefixLength": 3,
      "fuzziness": 2,
      "transpositions": false
    }
  }
}

• prefixLength - controls the number characters at the beginning of the query that the fuzziness is not applied to;

• fuzziness - the strength of the fuzziness. Controls the maximum number of changes (different character, skipped letter) that need to be made to the original phrase for suggestion to match;

• transpositions - if set to true, allows letter transpositions in suggestion matches. For example query teleivsio would match suggestion television.

Facets

Facets allow extending autocomplete suggestions with predefined filters.

For example, if facets are enabled, user query electron could yield suggestions like:

• electronics;
• electronics In Category: Mobile Phones;
• electronics In Category: Tv Sets;
• electronics With Tag: For Home;
• electronic toys;

To enable facets in suggestion queries, use facets parameter in configuration schema:

{
  "configuration": {
    "facets": {
      "documentQueryKey": "nvk9ejt682d8",
      "facets": [
        {
          "key": "category",
          "label": "In Category",
          "limit": 3
        },
        {
          "key": "tag",
          "label": "With Tag",
          "limit": 2
        }
      ]
    }
  }
}

• documentQueryKey - query key of the document query to retrieve facets from. Must be from the same Project.

• facet.key - key of the facet in the chosen document query;

• facet.label - human-readable label for the facet grouping;

• facet.limit - maximum number of items to return for this facet.

It is possible to add multiple suggestion groupings, as different array elements.

Suggestion public query response with facets

Suggestion query with facets response will include filter groupings for the first suggestion:

[
  {
    "suggestion": "electron",
    "facets": {
      "category": [
        {
          "title": "Mobile Phones",
          "count": 163
        },
        {
          "title": "Tv Sets",
          "count": 111
        },
        {
          "title": "Household Appliances",
          "count": 107
        }
      ],
      "tag": [
        {
          "title": "For Home",
          "count": 135
        },
        {
          "title": "Discount",
          "count": 79
        }
      ]
    },
    "facetLabels": {
      "category": "In Category",
      "tag": "With Tag"
    }
  },
  {
    "suggestion": "electronic toys"
  },
  {
    "suggestion": "electronic music"
  }
]

Dynamic facets

Dynamic facets allow you to control which facet values will be displayed with the first suggestion.

The default mode for facets is allItems. This means that the most frequent facet values (for example, categories with the most products) will be displayed first.

{
  "configuration": {
    "dynamicFacets": {
      "type": "allItems"
    }
  }
}

Another available type is topItems. This might be a good option if your main categories (or other selected facet field) are not the ones with the most products.

With this mode, top facet values will be collected from the first topItemsCount of the original search query results.

{
  "configuration": {
    "dynamicFacets": {
      "type": "topItems",
      "topItemsCount": 48
    }
  }
}

• type - dynamic facet type;
• topItemsCount - number of top items to collect for dynamic facets.