Skip to main content

​
Steps

  1. Go to Settings → Search Behavior.
  2. Select language, out-of-stock product visibility, and image search preferences.
  3. Configure combined listing display, excluded tags, and other options as needed.
  4. Save changes and, if prompted, run a quick sync.

​
Search strategy

The Search Strategy setting controls how broadly Layers looks through your catalog before ranking results. Each preset is a trade-off between latency and recall — a wider search finds more candidates but takes longer to return. Available strategies:
  • Fast — returns results as quickly as possible. Best when shoppers usually search for exact products or SKUs, and for smaller catalogs where a narrow candidate pool is enough.
  • Balanced (default, recommended) — a strong default for most stores. Looks broadly enough to find good matches while keeping search fast.
  • Deep — looks through more products before choosing results. Useful when shoppers use broad or vague terms, and for larger catalogs with varied assortments.
  • Exhaustive — uses the widest search. Choose this when finding the best possible match matters more than speed, typically on very large catalogs.
Moving from Fast toward Exhaustive increases the number of candidates considered at each stage of ranking, which usually improves relevancy for hard queries at the cost of higher search latency. Most stores should stay on Balanced and only switch after evaluating results on their own catalog. To change the strategy:
  1. Go to Settings → Search Behavior.
  2. Find the Search Strategy card.
  3. Select Fast, Balanced, Deep, or Exhaustive.
  4. Save your changes.
Changing the strategy invalidates cached search and facet results for the store, so the first few searches after saving may be slightly slower while caches warm back up. Before saving a change store-wide, preview any strategy on representative queries with the session-only override in the Search Workbench.

​
Out-of-stock product visibility

Control how out-of-stock products or variants appear in search results. Select one of the following options:
  • Not at all — hides out-of-stock products entirely from search results.
  • At the end — shows out-of-stock products, but demotes them to the bottom of results.
  • Mixed with all other results — shows out-of-stock products alongside in-stock products with no rank penalty.
These settings apply to search results only. Browse (collection page) results are not affected by store-level out-of-stock visibility — the Shopify collection itself controls which products appear. To hide out-of-stock products on a per-request basis for browse, use the forceHideOutOfStock parameter in the Browse API. For blocks, use the Hide Out of Stock safeguard in the block configuration.

​
Location-based stock check

When you select Not at all or At the end, a location picker appears below the stock display options. This lets you evaluate stock availability at specific Shopify locations rather than using global availability. The example below shows how to open Search Behavior and pick the inventory locations used for search stock checks. Animated example of choosing inventory locations for search behavior By default, Layers checks global availability across all locations. If you select one or more locations, the stock check only considers inventory at those locations:
  • With Not at all, products that have zero inventory at every selected location are hidden from results — even if they are technically available at other locations.
  • With At the end, products with no inventory at the selected locations are pushed to the bottom of results.
A product is considered in stock if it has inventory at any one of the selected locations. You do not need to have stock at all selected locations. To configure location-based stock checking:
  1. Go to Settings → Search Behavior.
  2. Under Stock Display, select Not at all or At the end.
  3. Click the location picker that appears below the stock options.
  4. Search for locations by name, city, country, or ID and select the ones you want to check against.
  5. Save your changes.
To revert to global availability, clear all selected locations. The picker shows All locations (default) when no locations are selected.
Only active Shopify locations appear in the picker. If you don’t see a location, verify that it is active in your Shopify admin.

​
Combined listings display

If your store uses Shopify combined listings, you can control how parent and child products appear in search results:
  • Only show parent products — returns only the parent listing in results.
  • Only show child products — returns only the child products.
  • Show both (default) — returns both parent and child products.

​
Image search configuration

The image embedding configuration controls which product images Layers uses to generate embeddings for visual search. By default, new stores use both the product featured image and variant featured images. You can change this in the image search preferences section of the search behavior settings. Available options:
  • Both (default) — uses the product featured image and all variant featured images for visual search matching.
  • Product featured image — uses only the main product image.
  • Variant featured images — uses only variant-specific images.
  • All — uses every image associated with the product and its variants.
You can also set a minimum image size (width x height in pixels) to exclude small or low-quality images from embedding generation.

​
Disable variant-level embeddings

By default, Layers generates a separate text embedding for each product variant in addition to the product-level embedding. Per-variant vectors improve recall when a variant option carries real meaning like gemstone, color, or material. For example, a search for ruby matches the ruby variant. For catalogs whose variant options are pure SKU dimensions like size, frame, or length, the per-variant vectors are near-duplicates of the product-level vector. They add noise to candidate retrieval and can dilute relevancy without improving it. The Disable variant-level embeddings toggle in Search Behavior → Images to Search By turns off per-variant text embeddings for the whole store:
  • When on, Layers skips per-variant text embeddings and only generates the product-level text embedding. Existing per-variant text vectors are removed from the search index in the background.
  • When off (the default), Layers generates one text embedding per variant alongside the product-level embedding, and regenerates any vectors that were previously stripped.
The toggle does not affect variant image embeddings — the image embedding configuration above still controls those. To change the setting:
  1. Go to Settings → Search Behavior.
  2. Scroll to the Images to Search By card.
  3. Toggle Disable variant-level embeddings on or off.
  4. Save your changes.
Leave the toggle off if any variant option carries search intent. Turn it on if your variant options are purely structural and you see duplicate-looking products crowding results.

​
App sales channel

If your store has a mobile app (such as Tapcart, Fuego, or Canvas), you can specify which Shopify sales channel represents your app storefront. When configured, Layers uses this channel to determine which products are visible to app users — only products published to the selected channel appear in app search, browse, and block results. To configure the app sales channel:
  1. Go to Settings → Search Behavior.
  2. Scroll to the App Sales Channel card.
  3. Select your app’s sales channel from the dropdown. Layers loads all available channels from your Shopify store automatically.
  4. Save your changes.
To remove the configuration, select Not configured from the dropdown and save.
If no app sales channel is configured, app requests fall back to default channel filtering behavior. For more details on how channel visibility works, see Sales channel visibility.

​
Search excluded tags

You can configure custom product tags that exclude products from the searchable database entirely. Products with any of these tags will not appear in search results. To add custom excluded tags:
  1. In the Search Excluded Tags section, enter a tag name in the input field.
  2. Click Add or press Enter to add the tag to the list.
  3. To remove a tag, click the X button next to it.
  4. Save your changes.
Note: Custom excluded tags are in addition to the default excluded tags (hide, layers-ignore). Tag matching is case-sensitive. Products with newly excluded tags won’t be removed from search until they’re re-indexed via webhook or bulk operation.

​
Real-time query expansion (deprecated)

Real-time query expansion is deprecated and disabled by default for all stores. It will be removed in a future release. All stores should use pre-computed query expansions instead.
The search behavior settings include a Real-Time Query Expansion toggle. When enabled, the search engine generates query expansions on the fly using an LLM for each search request. When disabled (the default), Layers uses only pre-computed query expansions. Pre-computed expansions offer faster response times and more predictable behavior. If your store currently has real-time query expansion enabled, you should switch to pre-computed expansions by disabling this setting. To disable real-time query expansion:
  1. Go to Settings → Search Behavior.
  2. Find the Real-Time Query Expansion card.
  3. Click Disable to switch to pre-computed expansions only.
  4. Save your changes.
For more about how query expansion works, see Query Understanding.

​
Real-time intent modifiers

The search behavior settings include a Real-Time Intent Modifiers toggle. When enabled (the default), Layers can generate intent modifiers at search time using an LLM if no stored modifier matches the query. When disabled, the search engine only uses previously saved intent modifiers and skips real-time generation entirely. Use this setting to limit a store to pre-computed intent modifiers when you want predictable, lower-latency search behavior or when you want to fully control which queries trigger promotions, demotions, or filters. When real-time intent modifiers are off:
  • Stored intent modifiers continue to apply when their associated query matches.
  • Queries without a stored match return no intent modifier actions.
  • Search latency drops because the engine skips the LLM call that generates new modifiers.
To turn real-time intent modifiers off:
  1. Go to Settings → Search Behavior.
  2. Find the Real-Time Intent Modifiers card.
  3. Select Disable to limit the store to stored intent modifiers only.
  4. Save your changes.
To turn the setting back on, select Enable in the same card and save. For more about how intent modifiers work, see Query Understanding.

​
Seeded search data

Sample data lets you show realistic search results while your catalog is still empty or syncing. Upload a JSONL file of historical search terms and Layers uses it to seed query clusters, autocomplete suggestions, and baseline ranking signals. Most stores don’t need to do this manually — Layers imports the last 30 days of Shopify search history automatically during onboarding. Use the upload only when the automatic import returned few terms, when you want to seed a longer window of history, or when you’re bringing search data over from another platform.

​
JSONL format

Each line of the file must be a JSON object with these three fields:
FieldTypeDescription
search_querystringThe search term a shopper entered.
searchesintegerNumber of times the term was searched.
daystringThe date the searches occurred, in YYYY-MM-DD format.
Example: 
{"search_query": "linen midi dress", "searches": 42, "day": "2026-05-14"}
{"search_query": "wide leg jeans", "searches": 17, "day": "2026-05-14"}
{"search_query": "black boots", "searches": 8, "day": "2026-05-15"}
Rows with missing fields, wrong types, or malformed dates are rejected. Layers validates the first 100 lines in the browser as soon as you pick the file and shows up to five errors with line numbers; the Upload button stays disabled until the file is valid. Extra fields on a line are ignored, so you can keep additional columns from your export without stripping them out first.

​
Upload a file

  1. Go to Settings → Sample Data → Upload Sample Data.
  2. Click Choose File and select your .jsonl export.
  3. Wait for the File format validated successfully confirmation.
  4. Click Upload. Layers processes the file in the background and shows progress on the Sample Data page.
Each upload in the history shows two counts once processing finishes:
  • Rows read — total lines Layers read from your file.
  • Imported — how many unique query rows landed in the seeded dataset after deduping near-duplicates and dropping terms searched fewer than three times across the whole file.
It’s normal for Imported to be much smaller than Rows read. Layers groups identical and near-identical terms together and skips very rare queries so the seed reflects real demand. If processing fails after upload, the task row on the Sample Data page shows the error and your existing seeded data is left in place. This can happen when a line past the first 100 is malformed, or when no rows meet the minimum frequency threshold. Fix the file and upload it again. For instructions on exporting historical searches from Shopify Analytics as JSONL, see Exporting search data.

​
Tip