Elastic Path Indexable Fields API

Indexable Fields allow you to extend and fine-tune the search schema. By default, the search index includes all the core product fields like name, description, SKU, slug etc. Indexable Fields let you:- **Add custom fields** to the index from product extension templates or custom (shopper and admin) attributes- **Configure core field behavior** such as stemming and tokenization on built-in fields like `name` and `description`- **Control tokenization** at the collection or per-field level using token separators and symbols to index### When to Use Indexable FieldsUse Indexable Fields when you want to:- **Search custom attributes**: Enable full-text search on custom product fields like brand, material, or specifications- **Filter by custom attributes**: Allow shoppers to filter products by custom fields like color, size, or rating- **Facet on custom attributes**: Display aggregated counts for custom field values in your navigation- **Sort by custom attributes**: Order search results by custom numeric fields like rating or popularity- **Enable stemming**: Match different word forms (e.g., "running" also matches "run", "runs") on both custom or core fields- **Customize tokenization**: Control how hyphenated, compound, or symbol-containing text is split and indexed### How Indexable Fields Work1. **Create indexable fields**: Define custom fields to index and configure collection-level or per-field tokenization settings2. **Override core field behavior**: Use `core_field_overrides` to configure stemming, token separators, or symbols to index on built-in fields like `name` and `description`3. **Reindex catalogs**: After creating or modifying indexable fields, reindex your catalog releases to apply the changes4. **Use in searches**: Once reindexed, custom fields are available in search queries for filtering, faceting, and sorting### Field ConfigurationEach entry in the custom fields (`fields` array) supports the following options:| Option | Description ||--------------------|-----------------------------------------------------------------------------------------------------------|| `name` | The field path — see **Field Types** below for supported formats || `facetable` | When `true`, the field can be used for faceting to show aggregated value counts || `sortable` | When `true`, the field can be used for sorting results || `locale` | Language code for text tokenization, defaults to `en` for English || `stem` | When `true`, enables word stemming using the Snowball stemmer — see **Stemming** below || `token_separators` | Per-field characters to use as token separators, overriding the collection-level setting || `symbols_to_index` | Per-field special characters to preserve as part of tokens, overriding the collection-level setting |### Field TypesTwo categories of fields can be indexed:#### Extension FieldsFields from your product extension templates, following the pattern `extensions.products().`:- `` is the slug of your product extension template- `` is the name of the field within that template- The field must exist and be enabled in the flows service- Only enumerated string fields, numeric fields, and boolean fields can be faceted**Example**: For a product extension template with slug `Details` containing a field `brand`, the indexable field name would be `extensions.products(Details).brand`.#### Custom Attribute FieldsMerchant-defined key/value attributes stored directly on products:- `shopper_attributes.` — visible in shopper and admin catalog API responses and available for filtering, sorting, and faceting in both shopper and admin search- `admin_attributes.` — available for filtering and sorting in both shopper and admin search; not returned in search response payloads- `` must be no longer than **64 characters** and can only contain alphanumeric characters, underscores (`_`), and hyphens (`-`).- Attribute fields are always typed as `string`- Faceting and sorting can be enabled**Examples**: `shopper_attributes.fabric`, `admin_attributes.internal_grade`### Core Field OverridesIn addition to configuring custom fields, Indexable Fields can influence the behavior of built-in product fields such as `name`, `description`, and `sku`. Use the `core_field_overrides` to apply per-field settings.Each entry in `core_field_overrides` supports `stem`, `token_separators`, `symbols_to_index`, and `sortable`. This is useful when you want to enable stemming on the product description, apply custom tokenization to a specific core field, or enable sorting on fields like `name` and `sku`.**Example**: Enable stemming on `description` and treat hyphens as token separators only on `name`:```json{ "core_field_overrides": [ { "name": "description", "stem": true }, { "name": "name", "token_separators": ["-"], "sortable": true } ]}```### StemmingStemming reduces words to their root form at both index and query time, so a search for "running" also matches products containing "run", "runs", or "runner". This improves search recall for descriptive text fields where shoppers may use different word forms than those found in product data.- Enable per field using `stem: true` on any entry in `fields` or `core_field_overrides`- Uses the [Snowball stemmer](https://snowballstem.org/)- Only valid for string-typed fields- Defaults to `false`### Token Separators and Symbols to IndexThese settings control how text is split into tokens during indexing and searching.#### Token Separators`token_separators` specifies characters that split text into separate tokens, in addition to the default whitespace splitting. This is useful for hyphenated text, part numbers, or other compound formats.For example, with `token_separators: ["-"]`, the text `non-tech` is tokenized to `non` and `tech`, so searches for both `non-tech` and `non tech` will match.#### Symbols to Index`symbols_to_index` specifies special characters that should be preserved within tokens rather than stripped during indexing. Useful when products contain meaningful symbols like `+`, `#`, or `@`.#### Collection-Level vs Field-LevelBoth settings can be configured at two scopes:- **Collection-level**: Set `token_separators` or `symbols_to_index` at the top level of the indexable fields resource to apply the setting across all indexed fields.- **Field-level**: Set the same properties on an individual entry in `fields` or `core_field_overrides` to apply only to that field, overriding the collection-level setting.An empty array at the field level defers to the collection-level setting.### Reindexing RequirementAny change to indexable fields requires reindexing your catalog releases to take effect. The system detects when indexes are out of sync. Use the [reindex endpoint](/docs/api/pxm/catalog-search/reindex-tenant-releases) to apply changes. See [Jobs](/docs/api/pxm/catalog-search/jobs) for more details on reindexing operations.