Skip to main content

​
Overview

Query understanding is how Layers interprets what customers are searching for. When a shopper types a query, Layers looks at the meaning, intent, and context behind it as well as the keywords. Results can be relevant even when the exact words don’t appear in product titles or descriptions. Query understanding combines several capabilities. Query expansion broadens searches with synonyms and related terms. Intent modifiers detect signals like price sensitivity or sale interest. Contextual awareness uses information about the shopper’s cart, purchase history, and location to personalize results. Together, they help customers find products when a query is brief, ambiguous, or uses different terminology than your catalog.

​
Query expansion

Query expansion enriches search queries by adding synonyms, related terms, and alternative phrasings that help match products the customer is looking for. Query expansion matters most when customers use different words than those in your product catalog, or when a short query could benefit from additional context.

​
How query expansion works

When a customer searches, Layers analyzes the query and generates related terms that capture the same or similar intent. These expansions are weighted based on how closely they relate to the original query, with direct synonyms receiving higher weight than more loosely related terms. For example, a search for “sneakers” might be expanded to include “athletic shoes” and “trainers”, while a search for “couch” might include “sofa” and “loveseat”. The original query always carries the most weight; expansions widen the set of potentially relevant products.

​
Abbreviations and common aliases

Query expansion recognizes common shopping abbreviations and normalizes them to their full forms. A search for “lbd” is understood as “little black dress”, “pjs” becomes “pajamas”, and “tee” is recognized as “tee shirt”. Well-known acronyms are expanded during the typo correction step, before query expansion runs, so the expanded form is available for further synonym enrichment during query expansion.

​
Query replacement

In some cases, Layers determines that a query should be replaced rather than expanded. This happens when the original search term is an abbreviation, slang, or ambiguous term that the expansions resolve to a clearer intent. For example, if a customer searches for “lbd”, Layers may replace the query entirely with “little black dress” instead of searching for both terms. Replacing works better here because the original term often has no direct matches in product data. Layers uses AI to decide whether a query expansion should replace or supplement the original query. Replacement is used conservatively, only when the original term is unclear and the expansions represent what the customer actually meant.

​
Catalog-aware expansion

Query expansion is informed by your actual product catalog. Layers knows what product types you sell and avoids suggesting expansions for products you don’t carry. If you sell shoes but not clothing, a search for “running gear” will focus expansions on footwear rather than apparel.

​
Intent modifiers

Intent modifiers detect signals in search queries that indicate specific shopping goals, then adjust search behavior accordingly. Unlike query expansion, which broadens what products are considered, intent modifiers influence how results are ranked or filtered based on detected intent.

​
Types of intent detection

Intent modifiers recognize several categories of intent signals in search queries. Price sensitivity: Queries containing phrases like “cheap”, “affordable”, “under $50”, or “budget” indicate price-conscious shopping. Intent modifiers can boost lower-priced products or apply price filters based on explicit constraints mentioned in the query. Sale and discount interest: Searches including “on sale”, “clearance”, “discount”, or “deal” signal interest in discounted products. Intent modifiers can prioritize products with active markdowns or compare-at prices. Feature preferences: When queries mention specific attributes like “wireless”, “organic”, “waterproof”, or “plus size”, intent modifiers treat these as feature preferences and adjusts ranking to favor products with those characteristics. Recency and freshness: Queries mentioning time windows like “new arrivals”, “recent”, “just released”, “this week”, or “last 30 days” signal interest in newly added or recently published products. Explicit windows narrow results to products published or created within that range. Vague signals like “new” or “latest” sort results so the freshest products appear first, without excluding older inventory. Recency windows are always relative to the time of the search, so a query for “new this week” returns the appropriate products whenever it runs.

​
How intent modifiers work

Intent modifiers translate detected signals into search adjustments through three mechanisms. Promotion boosts products matching the detected intent higher in results. Demotion lowers products that conflict with the detected intent. Filtering restricts results to only products matching explicit constraints, used sparingly and only when the query clearly requests restriction. Intent modifiers are conservative about applying filters, preferring to boost relevant products rather than exclude potentially relevant ones. Explicit price constraints like “under $100” may trigger filters, while softer signals like “affordable” influence ranking without restricting results.

​
Merchant instructions and explicit shopper intent

Your search instructions act as default ranking preferences. They shape results when the shopper hasn’t asked for something specific, but they never override intent the shopper states explicitly in the query. If a shopper searches for sale, clearance, or discounted items, the sale filter is applied even when your instructions say not to promote sale items. The same applies to explicit price constraints: a query like “sale dresses under $50” still gets both the sale filter and the price filter. And when a query rules out sale items (“not on sale”), no sale filter is applied regardless of your instructions.

​
Intent-favored variant

When a promote action targets a variant-level attribute, the matching variant is also favored as the one displayed on each result tile. This covers options (such as options.color) and variant metafields (such as variant_metafields.material). A query like “red dress” then surfaces both red-available dresses and the Red variant of each one, so the right image, price, and options appear without an extra click. This applies only to promote actions. Demote and hard-demote actions are negative signals and never select a variant. The preference is a soft ordering hint, not a hard filter. If no variant matches, the product still appears with its default variant. For where this fits relative to other selection signals, see variant selection priority.

​
Multiple intent modifiers

When a query triggers more than one intent modifier, promotions and demotions are applied differently. Promotions use AND logic. All promote conditions must match for a product to receive a ranking boost. For example, if a query triggers both a product type promotion and a material promotion, only products that match both the product type and the material are boosted. This prevents unrelated products from surfacing just because they match a single condition. Demotions remain independent. Each demotion is applied on its own. A product is penalized if it matches any individual demotion condition, regardless of other demotions.

​
Facet value groups in intent modifiers

When an attribute has facet value groups, intent modifiers use the group name as the value. Layers counts a raw value’s dominance toward every group it belongs to and emits the shopper-facing group name. A query like “purple dress” that maps to the Purple group then promotes every product whose color sits in that group, including raw values like Valerian or Lilac. Explanations shown in search debug tools render the group label for raw members. Stored modifiers keep working when they reference either a group name or a raw member of a group. Layers expands the group name to its members at match time, and raw values continue to match exactly.

​
Balancing discovery and intent

Intent modifiers favor discovery over narrow results. For generic queries like “dress” or “shoes”, Layers typically applies no modifications, so customers can browse the full range of options. Modifications apply only when there’s a clear intent signal in the query, and even then they move the most relevant products up instead of hiding alternatives.

​
Contextual awareness

Query understanding incorporates information about the shopper’s current session and history to personalize how queries are interpreted. Contextual awareness helps resolve ambiguity and surface more relevant results.

​
Cart context

Products currently in the shopper’s cart provide signals about their shopping mission. If a customer has toddler clothing in their cart and searches for “shoes”, Layers infers they’re likely looking for toddler shoes rather than adult footwear. Cart context helps disambiguate generic queries without requiring customers to be more specific.

​
Purchase history

Past purchases inform understanding of customer preferences. A customer who has previously purchased plus-size clothing may see plus-size options prioritized when searching for apparel. Similarly, brand preferences established through purchase history can influence which products surface first for ambiguous queries.

​
Geographic location

Location affects how queries are interpreted in several ways. Regional spelling variations are handled appropriately, so a UK customer searching for “trainers” sees athletic shoes while the same search from a US customer might be expanded to include “sneakers”. Location can also influence which products are most relevant based on climate, local trends, or regional availability.

​
Prior searches

Recent search behavior within a session provides context for subsequent queries. If a customer searched for “running shoes” and clicked on several results, a follow-up search for “socks” might prioritize athletic or running socks over dress socks. For complete details on contextual information and how to pass it via the API, see Contextual Information.

​
The query understanding pipeline

When Layers processes a search query, the query passes through the following stages in order.

​
Query preprocessing

The query is first cleaned and normalized. This includes standardizing case, handling special characters, and preparing the text for analysis.

​
Query interpretation

Query interpretation is one stage of the query understanding pipeline, not the whole pipeline. In this stage, Layers corrects any typos and decides how the query should be routed: as a regular product search, a redirect candidate, or a SKU lookup. (Shopping intent such as price sensitivity is detected later, in intent detection.) A search for “snekaers” is corrected to “sneakers”. A query like “how do I return my order” is identified as a redirect candidate and matched against your semantic redirects. A query like “WKR04” is recognized as a SKU lookup. For details on this stage, see Query interpretation.

​
Query expansion

The normalized query is analyzed to generate relevant expansions including synonyms, related terms, and alternative phrasings. Each expansion is weighted based on relevance to the original query.

​
Intent detection

The query is analyzed for intent signals like price sensitivity, sale interest, or feature preferences. Detected intents are translated into ranking adjustments or filters.

​
Contextual personalization

Available context about the shopper (cart contents, location, history) is incorporated to personalize how the query is understood and which products are most relevant.

​
Search execution

The processed query, expansions, intent modifiers, and context are combined to execute the search and rank results. The final results reflect all of these factors.

​
Transparency and debugging

The search response includes metadata about how the query was understood and processed. Use this metadata to display messages to customers (like “Showing results for ‘espresso machine’” when they searched for “espreso machine”) or for debugging search behavior. When testing searches in the Layers dashboard, the Query Understanding panel appears for every search, even when no explicit query rewrites or filters were applied. The panel shows each step of the query understanding pipeline, including what expansions were generated, what intent was detected, and how context influenced the results. When no pipeline steps are active, the panel confirms that AI semantic retrieval and ranking still interpreted the query and scored the results. The Explain button is always available in the panel. Explain generates an AI summary that references the top results and their ranking scores, so you can see how the pipeline affected result ordering. You can click it repeatedly after changing queries, demo profiles, or workbench settings to generate fresh explanations. For testing and review tools, see Test Text Search and Insights.

​
Configuration options

Several aspects of query understanding can be configured to match your catalog and customer base.

​
Search behavior settings

The dashboard has controls for expansion strength and search behavior under Settings in the Search Behavior tab.
Intent modifier generation can be limited to stored modifiers only. See Real-time intent modifiers for when to use this setting.

​
Search language

Configure whether your search operates in English only or multilingual mode based on your catalog and customer base. Multilingual mode handles queries and products in multiple languages. For configuration details, see Search Behavior Settings.

​
See also