Search

Configuration

Tweaks and settings for matching Search to your business.
Search configuration

Search comes with several settings that allow you to adjust its behavior.

When you change a setting, it triggers an analysis of your data that must complete before changes take effect.

This process can take up to 15 minutes but may be faster depending on the size of your catalogue. You can monitor the status in Data > Configuration.

The settings require Search 3.0 to be enabled. Afterwards, you can access them in Search > Configuration.

Attribute Search Relevance #

This section allows you to personalise your search based on your needs. Here you have two options: Searchable Attribute Ranking and Non-Searchable Attributes.

Searchable Attribute Ranking #

The Searchable attributes grouped by ranking order setting allows you to create groups of attributes with different levels of importance for search results. Attributes in higher-ranking groups have greater influence on the results displayed.

E.g. if group 1 contains "brand" and _category_name, while group 2 contains name and color, a search for “blue Nike boots” will prioritize products with the brand “Nike” in the “Boots” category over items with those words in their name attribute.

This prioritization helps emphasize significant data such as genres, specifications, or other key attributes.

For example, in bookstores, it is often more relevant to prioritize the author of a book. A search for “Stephen” should prioritize books by Stephen King over books that include “Stephen” in their titles.

Notice: Be cautious when modifying these groups. Adding too many attributes may cause Clerk.io to deprioritize product popularity, focusing only on text-relevance.

Non-searchable attributes #

This section lets you exclude attributes from the search index, meaning their text will not be searchable. This is useful for things like internal IDs, margin values, or any data you want to use for display or filtering, but don’t want customers to search through.

By default, the price and stock attributes are in the list to prevent searches containing numbers from being skewed by these attributes. You can customize this list as needed.

You can add non-searchable attributes in two ways:

  • Manually from the list of available attributes.
  • Using rules if you have a pattern of attributes with similar names.

Rules are especially helpful if you want to exclude multiple attributes at once. Just use the (*) wildcard:

  • *_url will match all attributes that end with _url
  • child_* will match all attributes that start with child_

Filterable attributes #

Attributes in this list become available as filters/facets across Search, Omnisearch and Merchandising. If a product attribute doesn’t appear when you configure facets or create a Merchandising rule, add it here and wait for the configuration analysis to finish.

  • Add attributes from the list of available product attributes.
  • Changes can take up to 15 minutes to apply depending on catalogue size.

Exact Match Behaviour #

By default, Clerk.io returns all relevant results for searches on your site. However, in specific cases — like searching for an SKU or EAN number — you may expect only a single match.

Search v3 required: This feature is only available for Stores using Search v3. You can check this in Settings > Features > Early access features.

By including attributes in this list, you configure Clerk.io to return a single result when the query matches a value in those attributes. This also disables auto-correction to ensure only the exact match is displayed.

The most common ones are sku and ean, but any synced attributes can be used.

When adding an attribute you have two options:

  • Return single exact match, best used for unique identifiers like SKUs or product IDs where you want to return a specific product.
  • Return multiple exact match, ideal for attributes like category IDs, where many products share the same value.

Facet Price Buckets #

Here you can define the price range which will be used in the Search filters. If left blank, Clerk.io will calculate them dynamically based on your product data price range.

In the text field you can enter a comma separated list of price values, e.g.: 0,50,100,150,200,…

Custom dictionary #

The custom dictionary allows you to define search terms that would typically be treated as separate words instead of a single concept.

For example, if your catalog includes products from the sneaker brand D.A.T.E., you might want to add “D.A.T.E.” and “D. A. T. E.” to the custom dictionary.

Criteria #

Clerk.io detects a query as a unique identifier when:

  • It’s alphanumeric and includes at least one of the following characters: “-+/&_.0123456789”.
  • It has at least 4 characters.
  • It does not contain spaces or quotes.

If Clerk.io finds a single exact match in any of the unique identifier attributes, that product is returned immediately, overriding any customized search or merchandising rules. Otherwise, the query is treated as a regular search.

Settings override #

Settings override lets you adjust advanced Search index settings by adding a JSON object in Search > Configuration.

These settings control how Clerk.io reads, ranks, filters, sorts and returns search results. They are advanced settings and should normally only be changed when you know exactly which Search behavior you want to adjust.

Changing them can affect all Search results for the Store. A small typo in JSON can also prevent the override from being saved.

Advanced setting: Use Settings override carefully. If you are unsure whether an override is needed, contact Clerk.io support before changing it.

Store-specific attributes #

Attributes such as brand, color, size, sku, price, or custom category fields depend on the data synced to each Store.

This means displayedAttributes, filterableAttributes, searchableAttributes and sortableAttributes can look different from Store to Store.

Attributes that start with an underscore, such as _all_categories, _category_name or _price_range, are generated by Clerk.io and are available for all Stores.

Example #

The example below shows the structure of a Settings override. Your Store will likely use different attributes.

{
  "displayedAttributes": [
    "_all_categories",
    "_category_name",
    "_price_range",
    "brand",
    "categories",
    "description",
    "id",
    "image",
    "name",
    "price",
    "stock",
    "url"
  ],
  "searchableAttributes": [
    "high_relevance",
    "medium_relevance",
    "low_relevance"
  ],
  "filterableAttributes": [
    "_all_categories",
    "_category_name",
    "_price_range",
    "brand",
    "categories",
    "price",
    "stock"
  ],
  "sortableAttributes": [
    "created_at",
    "name",
    "price"
  ],
  "rankingRules": [
    "sort",
    "words",
    "typo",
    "attribute",
    "proximity",
    "clerk.popularity:desc"
  ],
  "stopWords": [],
  "nonSeparatorTokens": [],
  "separatorTokens": [],
  "dictionary": [],
  "synonyms": {},
  "distinctAttribute": null,
  "proximityPrecision": "byAttribute",
  "typoTolerance": {
    "enabled": true,
    "minWordSizeForTypos": {
      "oneTypo": 3,
      "twoTypos": 8
    },
    "disableOnWords": [],
    "disableOnAttributes": [
      "high_relevance.id",
      "high_relevance.sku"
    ],
    "disableOnNumbers": false
  },
  "faceting": {
    "maxValuesPerFacet": 100,
    "sortFacetValuesBy": {
      "*": "alpha"
    }
  },
  "pagination": {
    "maxTotalHits": 1000000
  },
  "embedders": {},
  "searchCutoffMs": null,
  "localizedAttributes": null,
  "facetSearch": true,
  "prefixSearch": "indexingTime"
}

Available settings #

displayedAttributes controls which attributes Clerk.io can return in Search results.

Use it when you want Search results to include only the fields needed by your designs, API responses or frontend logic.

searchableAttributes controls which attributes are searched when a visitor types a query.

The order matters. Attributes earlier in the list are treated as more important for text relevance.

filterableAttributes controls which attributes can be used for filters, facets and rules that narrow results.

Add an attribute here if it should be selectable as a facet or usable in filtering logic. Store-specific product attributes must exist in your synced data before they can be used.

sortableAttributes controls which attributes Search results can be sorted by.

Add fields such as price, created_at or name if you want to use them for sorting.

rankingRules controls the order of relevance rules used to rank matching results.

Rules near the top have the strongest influence. Custom rules like clerk.popularity:desc can be used to push popular products higher after the preceding relevance checks.

stopWords lists words that should be ignored in search queries.

This can be useful for very common words that do not help shoppers find products, such as “the” or “and”.

nonSeparatorTokens lists characters that should not split a word.

For example, adding @ can help Clerk.io treat a term containing that character as one connected value.

separatorTokens lists characters that should split words.

Use this when your product data contains characters that should clearly divide one term from another.

dictionary lists terms that should be treated as a single word or concept.

This is useful for brand names, abbreviations or product terms that are normally split into several parts.

synonyms maps one query term to equivalent words or phrases.

Use synonyms when shoppers often search for different words that mean the same thing in your catalogue.

distinctAttribute groups results by a shared attribute and returns one result per unique value.

This is useful when variants are indexed as separate products, but you only want one result per parent product or group.

proximityPrecision controls how strictly word closeness is evaluated.

byWord compares the exact distance between matching words. byAttribute checks whether matching words appear in the same attribute.

typoTolerance controls how Search handles misspellings.

You can enable or disable typo tolerance, set the minimum word length for one or two typos, and disable typo tolerance for specific words, attributes or numbers.

faceting controls how facet values are returned.

maxValuesPerFacet sets how many values each facet can return. sortFacetValuesBy controls whether facet values are sorted alphabetically or by result count.

pagination controls the maximum number of results Search can return for a query.

maxTotalHits is the upper limit available for paginated results.

embedders is reserved for advanced semantic search setups.

Leave it empty unless Clerk.io support has advised you to configure it.

searchCutoffMs sets a maximum time, in milliseconds, that Search can spend on a query before returning the best results found so far.

Use null to keep the default behavior.

localizedAttributes can define language-specific handling for matching attribute patterns.

Leave it as null unless your Store has a specific multilingual indexing setup.

facetSearch controls whether facet values can be searched.

When enabled, shoppers and integrations can search within facet values, such as finding a specific brand inside a long brand filter.

prefixSearch controls whether partial words can match while a shopper is typing.

indexingTime enables prefix matching for faster search-as-you-type behavior. disabled turns prefix matching off.