Indices

Overview

Index can be thought of as the location where all your documents (product entries) are stored, it also contains additional configuration (like Language) and is the base for your Search and Suggestion Queries.

Each Project can have multiple Indices that can be used to store and query independent data. Keep in mind that Index can only have one language, so if your data is multilingual, consider creating a separate Index for each language.

Index can have an optional type: DOC or SUGGESTION. DOC index is used to process ordinary documents, and SUGGESTION index is used to store generated autocomplete entries. To learn more about suggestion indices, check Suggestion Documentation.

An overview of Index role in the system

Create a new Index

API Reference: Create a new Index.

A new Index can only be created by Organization or Project administrators.

To create a new Index in a selected project, issue an HTTP POST request with selected language and name.

{
  "language": "lt",
  "name": "new-index-name"
}
  • language - language code for the new index, ISO 639-1 standard. For the list of supported languages, see the here. The Index will be pre-configured with the grammar rules of the selected language;
  • name - a name for the new index. Must be an alphanumeric string, words separated by dashes. Name must be unique in a Project.

Returned index id can then be used to perform any other index configuration operations.

In order to import documents or create Queries, a Mapping configuration should be added to your new Index first. See more: Mapping

Update an Index

API Reference: Update Index.

Index can be updated by Organization or Project administrators.

Only the name of the Index can be changed with this operation.

{
  "name": "updated-index-name"
}
  • name - a new name for the new index. Must be an alphanumeric string, words separated by dashes. Name must be unique in a Project.

Updating a name of the Index will result in no downtime for your users, because underlying Queries will still point to the same data and configuration. However, all the subsequent requests to Mapping, Query and other Index APIs will require you to use an updated name of the Index.

Get Index

API Reference: Get Index.

Index can be accessed by Organization or Project members.

Retrieves an information about a single Index by it's project and unique name. The response includes information about Index status (enabled/disabled) and whether documents in the Index needs to be reindexed (if Mapping or other search settings was changed).

Example of the response:

{
  "id": "de888d4e-da4f-41db-a3b7-43f8857e1ad2",
  "name": "index-name",
  "language": "lt",
  "isEnabled": 1,
  "mapping": {},
  "needsReindex": true,
  "reindexInProgress": false,
  "reindexedAt": "2021-11-05T11:03:52.000Z"
}
  • id - unique Index indentifier, used to perform further configuration actions for Index and Queries.
  • name - name of the Index;
  • language - language of the Index;
  • isEnabled - indicates whether Index is enabled. Check "Enable/Disable Index" section for more details. 1 - Index is enabled; 0 - Index is disabled;
  • mapping - Index Mapping configuration. See more: Mapping;
  • needsReindex - indicates whether Index documents needs to be reindexed to apply any recent configuration changes (like updated mapping or other Index settings);
  • reindexInProgress - indicates whether reindex action is in progress. It is not possible to initiate another reindex action until the current one is finished;
  • reindexedAt - date and time of the last successful reindex action.

For the full list of all available fields in the Index, see the API Reference.

Get Indices in a Project

API Reference: Get Indices in the Project.

Indices can be accessed by Organization or Project members.

Returns a list of the Indices created in the given Project.

For the response format, see the section above.

Enable/Disable Index

API Reference: Enable/Disable Index.

Change the status of the Index. Disabled Index cannot be used to query or store new documents, but it retains existing documents and configuration.

Reindex

API Reference: Reindex the documents in the Index.

Certain configuration actions (like changing Mapping) might require document reindex action to take effect. A Index field needsReindexing indicates whether this action needs to be executed to apply any pending configuration changes.

For example, you can perform multiple Index configuration changes, and apply them all at once with the reindex request. Reindex operation has zero downtime for your end users, because Queries will point to the old configuration until reindex is finished.

Example response:

{
  "success": true,
  "batchKey": "reindex-1627373737"
}

The returned batchKey can be used in the Task API to track progress and check any errors that might occur during the reindex. If there is at least one error, the Queries will continue to point to the old index, and reindex action will have to be repeated, after any underlying problems are fixed.

Delete an Index

API Reference: Delete an Index.

Index can be deleted by Organization or Project administrators.

Deleted Index can no longer be accessed and all of the documents are removed.