> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/indexing.md). # Indexing Tutorial The Indexing service is designed to manage indexing configuration. Currently supported index providers: * [Algolia](https://www.algolia.com) * [Battery Included](https://www.batteryincluded.io) Proper indexing allows you to enhance your search mechanism within the Emporix system. By connecting an index provider to Commerce Engine, you get improved search functionality. {% hint style="info" %} To learn more about the Indexing Service, see the [Indexing Service](/api-references/api-guides/configuration/indexing-service.md). {% endhint %} #### Provider mutual exclusivity Only one provider can be active at a time per tenant. This constraint is enforced by the configuration service. #### Battery Included limitations {% hint style="danger" %} This functionality is in preview mode - some of the features may not be fully operational yet. The payload sent to Battery Included is subject to change. {% endhint %} Battery Included only supports the `MERGE` site-aware fields strategy. Tenants configured with the `SPLIT` strategy will have Battery Included indexing silently skipped. #### Algolia limitations By default, Algolia indexes provided by Emporix support records up to 10kB in size. In order to support larger records, you must provide your own Algolia service. For more information, please refer to documents provided by Algolia: * [Algolia documentation](https://www.algolia.com/doc/guides/scaling/algolia-service-limits#application-record-and-index-limits) * [Algolia FAQ](https://support.algolia.com/hc/en-us/articles/4406981897617-Is-there-a-size-limit-for-my-index-records) For every tenant, new Algolia credentials are created and kept as `AlgoliaClient`. The Indexing service uses separate API keys for every tenant, so that you get more flexibility in configuration. ## How to configure search indexing To create indexing configuration, send a request to the [Creating new configuration](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/api-reference/configuration#post-indexing-tenant-configurations) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/qs6vxjPYmZdpyL8p7YeH" %} [API Reference](/api-references/api-guides/configuration/indexing-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --request POST --url 'https://api.emporix.io/indexing/{tenant}/configurations' --header 'Content-Type: application/json' --data '{ "active": true, "searchKey": "84dc4886f81f805c42bdd89d64de751a", "applicationId": "8AP2HABA2I", "indexName": "exampleTenant", "writeKey": "51ebe89215dddcf85e5dacd5643d17e7", "provider": "ALGOLIA" }' ``` For the `BATTERY_INCLUDED` provider, the same configuration endpoints also support mixin filtering options: * `excludedMixinKeys` - optional list of top-level mixin keys to exclude * `includedMixinPaths` - optional list of glob patterns that allowlist mixin paths The `includedMixinPaths` option is matched against full dot-notation mixin paths rooted at the mixin key, for example `class_EA673_toolsClassification.sk.OnlineIsService_P`. Supported glob syntax: * `*` matches any characters within a single path segment * `**` matches across one or more path segments * `.` separates path segments Matching is case sensitive and uses full-path matching. If a matched path points to an object, the whole subtree under that object is included. Behavior: * if `includedMixinPaths` is absent or an empty list (`[]`), allowlist filtering is inactive * if `includedMixinPaths` is non-empty, only matching mixin paths are sent to Battery Included * `includedMixinPaths` and `excludedMixinKeys` must not both be non-empty in the same request * malformed glob patterns are rejected with a `400` validation error on configuration writes Example of the Battery Included configuration: ```bash curl -L \ --request POST \ --url 'https://api.emporix.io/indexing/{tenant}/configurations' \ --header 'Content-Type: application/json' \ --data '{ "active": true, "indexName": "exampleTenant", "writeKey": "51ebe89215dddcf85e5dacd5643d17e7", "provider": "BATTERY_INCLUDED", "includedMixinPaths": [ "*_siteAware.*.OnlineIsService_P", "*_siteAware.**" ] }' ``` ## How to update the index configuration To update the index configuration you need to retrieve the `writeKey` first. Send the request to the [Get configuration by provider name](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/api-reference/configuration#get-indexing-tenant-configurations-provider) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/qs6vxjPYmZdpyL8p7YeH" %} [API Reference](/api-references/api-guides/configuration/indexing-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --url 'https://api.emporix.io/indexing/{tenant}/configurations' --header 'Accept: */*' ``` To change configuration, make a call to the [Update configuration by provider name](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/api-reference/configuration#put-indexing-tenant-configurations-provider) endpoint, providing the `writeKey` from the previous step. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/qs6vxjPYmZdpyL8p7YeH" %} [API Reference](/api-references/api-guides/configuration/indexing-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --request PUT --url 'https://api.emporix.io/indexing/{tenant}/configurations/{provider}' --header 'Content-Type: application/json' --data '{ "active": true, "searchKey": "84dc4886f81f805c42bdd89d64de751a", "applicationId": "8AP2HABA2I", "indexName": "exampleTenant", "writeKey": "51ebe89215dddcf85e5dacd5643d17e7", "provider": "ALGOLIA" }' ``` For `BATTERY_INCLUDED`, `includedMixinPaths` filtering is applied to the raw source mixin tree before the localized and non-localized mixin split. The retained data is then written to the existing Battery Included mixin fields, such as `_product.mixins` and `_product_i18n..mixins`. To apply your configuration changes to existing data, run the reindexing process. See the [How to reindex existing products](#how_to_reindex_existing_products) section. ## How to reindex existing products Usually, reindexing runs upon the update of a product or its dependant entity, such as category, price, or media. The scheduler job discovers what has been changed and pushes the changes to index frequently. But, if you change your index configuration, you need to trigger the reindexing process to apply your configuration changes. You can run the reindex without the need to update all your resource data by sending the request to the [Reindex](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/api-reference/reindex) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/qs6vxjPYmZdpyL8p7YeH" %} [API Reference](/api-references/api-guides/configuration/indexing-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --request POST --url 'https://api.emporix.io/indexing/{tenant}/reindex' --header 'Content-Type: application/json' --data '{ "mode": "FULL" }' ``` This operation starts the full reindexing mode. ## How to retrieve public search configuration How to retrieve public search configuration If you want to get your storefront index configuration without the need to update, you can call the public endpoint to get the `searchKey`. Send the request to the [Get all public configurations](https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/api-reference/public-configuration#get-indexing-tenant-public-configurations) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/qs6vxjPYmZdpyL8p7YeH" %} [API Reference](/api-references/api-guides/configuration/indexing-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --url 'https://api.emporix.io/indexing/{tenant}/public/configurations' --header 'Accept: */*' ``` ## How to choose indexing strategy You can choose between two indexing strategies for your search index configuration: `MERGE` and `SPLIT`. `MERGE` strategy creates a single index for all sites declared in the system, while `SPLIT` creates a separate index for each site. To choose the right mode for your index, send the request to the [Updating a configuration](https://developer.emporix.io/api-references/api-guides/configuration/configuration-service/api-reference/tenant-configurations#put-configuration-tenant-configurations-propertykey) endpoint. {% hint style="success" %} To test the endpoint, open the API reference or check the example of a curl request. {% endhint %} {% content-ref url="/pages/tdSQ3AsLz7TjdDcECwNM" %} [API Reference](/api-references/api-guides/configuration/configuration-service/api-reference.md) {% endcontent-ref %} ```bash curl -L --request PUT --url 'https://api.emporix.io/configuration/{tenant}/configurations/{propertyKey}' --header 'Content-Type: application/json' --data '{ "key": "indexing_siteAwareFieldsStrategy", "secured": false, "value": { "strategy": "SPLIT" }, "version": 1 } ``` In the request parameters, for the `propertyKey` choose `indexing_siteAwareFieldsStrategy`. In the request body, pass the chosen strategy value.Please remain patient as propagating changes to the index strategy may take up to 1 hour, so you might not be able to see the changes instantly. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/api-references/api-guides/configuration/indexing-service/indexing.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.