Skip to main content

Indexable Fields

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
  • Control tokenization for the whole index using stem, token_separators, and symbols_to_index
  • Enable sorting and faceting on built-in fields like name, sku, created_at, and updated_at

When to Use Indexable Fields​

Use 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
  • Tune stemming: Stemming is on for text fields by default, matching different word forms (e.g., "running" also matches "run", "runs"). Turn it off for the whole index if your catalog needs exact word matching
  • Customize tokenization: Control how hyphenated, compound, or symbol-containing text is split and indexed

How Indexable Fields Work​

  1. Create indexable fields: Define the custom fields to index, and set the index-wide stem, token_separators, and symbols_to_index values that apply to every text field
  2. Enable sorting or faceting on core fields: Use core_field_overrides to make built-in fields such as name, sku, created_at, or updated_at sortable or facetable
  3. Reindex catalogs: After creating or modifying indexable fields, reindex your catalog releases to apply the changes
  4. Use in searches: Once reindexed, custom fields are available in search queries for filtering, faceting, and sorting

Field Configuration​

Each entry in the custom fields (fields array) supports the following options:

OptionDescription
nameThe field path — see Field Types below for supported formats
facetableWhen true, the field can be used for faceting to show aggregated value counts
sortableWhen true, the field can be used for sorting results
localeISO 639-1 language code for text tokenization — defaults to en; omitting it is identical to en
stemDeprecated. Per-field stemming, overriding the index-wide stem. See Index-wide tokenization settings
token_separatorsDeprecated. Per-field token separators, overriding the index-wide token_separators
symbols_to_indexDeprecated. Per-field symbols to index, overriding the index-wide symbols_to_index

Field Types​

Two categories of fields can be indexed:

Extension Fields​

Fields from your product extension templates, following the pattern extensions.products(<template_slug>).<field_name>:

  • <template_slug> is the slug of your product extension template
  • <field_name> 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 Fields​

Merchant-defined key/value attributes stored directly on products:

  • shopper_attributes.<attribute_name> — visible in shopper and admin catalog API responses and available for filtering, sorting, and faceting in both shopper and admin search
  • admin_attributes.<attribute_name> — available for filtering and sorting in both shopper and admin search; not returned in search response payloads
  • <attribute_name> 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 Overrides​

In addition to configuring custom fields, Indexable Fields can influence the behavior of built-in product fields such as name, description, and sku. Use core_field_overrides to apply per-field settings.

Each entry supports sortable and facetable, plus the deprecated stem, token_separators, and symbols_to_index. The recommended use of core_field_overrides is enabling sorting or faceting on a core field.

Example: Make name sortable and allow faceting on created_at:

{
  "core_field_overrides": [
    { "name": "name", "sortable": true },
    { "name": "created_at", "facetable": true }
  ]
}

Stemming​

Stemming 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.

Stemming is on by default for every text field in the index — custom fields and built-in fields alike, including identifier-style fields such as sku, upc_ean, and manufacturer_part_num.

  • Set stem: false at the top level of the indexable fields resource to turn stemming off across the whole index
  • Uses the Snowball stemmer, which supports many languages; a text field is stemmed for the language given by its locale
  • Applies to text fields only — numeric, boolean, and date fields are never stemmed

Because identifier fields are stemmed too, closely related codes can match one another (for example AB-1000S and AB-1000). Nothing becomes harder to find — stored values and queries are stemmed the same way — but if a field needs exact word matching, opt that single field out:

{
  "stem": true,
  "core_field_overrides": [
    { "name": "sku", "stem": false }
  ]
}

Per-field stem is deprecated; read Index-wide tokenization settings below before relying on it.

Token Separators and Symbols to Index​

These 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 @.

Index-wide tokenization settings​

stem, token_separators, and symbols_to_index can all be set once at the top level of the indexable fields resource, where they apply to every text field in the index. This is the recommended way to configure tokenization.

{
  "stem": true,
  "token_separators": ["-"],
  "symbols_to_index": ["+"]
}

All three are also available on individual entries in fields and core_field_overrides, where they override the index-wide value for that one field. All three per-field forms are deprecated. They keep working, and a per-field value still takes precedence, but they should be avoided except in the specific cases described below. An empty array at the field level defers to the index-wide setting.

Why per-field tokenization settings are discouraged​

When a search targets several query fields, the query text is tokenized once per request — not once per field. The settings used are those of whichever query field carries the highest weight for that request, and the resulting tokens are then matched against every other field.

So when the fields in a search profile carry different tokenization settings, only the highest-weighted field's settings shape how the query is split up. Every other field is matched using tokens that its own settings did not produce. Two examples of what that looks like in practice:

  • name stems and sku does not. A shopper searches for shoes. Because name carries the higher weight, the query is reduced to shoe, and that is what is matched against sku — so a product whose SKU contains shoes is not found.
  • name splits on - and sku does not. A shopper searches for AB-1000. The query is split into AB and 1000 before it reaches sku, whose contents were indexed as a single token.

Setting all three at the index level avoids this entirely, because every field is then tokenized the same way as the query.

When a per-field setting is still legitimate: a field that genuinely needs different treatment and is not queried alongside fields with different settings — for example opting one identifier field out of stemming, as shown under Stemming above. Whenever you do this, check the weights of the query fields on every search profile that includes the field, and expect the highest-weighted field's settings to govern the query.

Reindexing Requirement​

Any 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 to apply changes. See Jobs for more details on reindexing operations.

Ask External AI