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
  • 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 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
  • 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 Work​

  1. Create indexable fields: Define custom fields to index and configure collection-level or per-field tokenization settings
  2. 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 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
localeLanguage code for text tokenization, defaults to en for English
stemWhen true, enables word stemming using the Snowball stemmer — see Stemming below
token_separatorsPer-field characters to use as token separators, overriding the collection-level setting
symbols_to_indexPer-field special characters to preserve as part of tokens, overriding the collection-level setting

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 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:

{
  "core_field_overrides": [
    { "name": "description", "stem": true },
    { "name": "name", "token_separators": ["-"], "sortable": 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.

  • Enable per field using stem: true on any entry in fields or core_field_overrides
  • Uses the Snowball stemmer
  • Only valid for string-typed fields
  • Defaults to false

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

Collection-Level vs Field-Level​

Both 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 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