Create a ranking rule

​

Before you start

• Ranking rules only affect text search results.
• New rules are created as Draft by default. Draft rules are saved but do not affect live searches until you publish them.
• You can create multiple rules and they all evaluate independently. If multiple rules match the same query, Layers applies all of their actions.

​

Save and publish workflow

When you are building or editing a rule, you have two separate primary actions:

• Save Changes — Saves the rule’s current configuration in place. If the rule is not yet published, it stays in Draft status and is not applied to live searches.
• Publish — Saves the rule and marks it as Published, so Layers applies it to live searches.

On the edit page for an existing rule, the Publish button toggles to Unpublish while the rule is live. Click Unpublish to take the rule offline without deleting it. Layers preserves your saved configuration so you can republish the rule later. To stage changes without affecting live results, keep the rule unpublished while you edit. Use the manual rule preview to inspect unsaved changes before saving or publishing them.

​

Select a rule type

1. Go to Relevancy → Ranking Rules.
2. Click Create Rule.
3. Select a rule type:
   • Visual Editor — Pin products to specific positions using a drag-and-drop grid. Best for curating results for high-value queries.
   • Manual Rules — Promote or demote products based on attribute conditions and magnitude. Best for broad adjustments across many products.

​

Create a visual rule

1. Click the rule name in the page header and type a name for the rule.
2. Type the search query the rule targets. Products matching that query load into a grid.
3. Drag products into the positions you want them to appear. Layers locks pinned products to their assigned positions.
4. To add a product not in the current results, use the search field within the grid to find and add it.
5. Click Save Changes to save the rule as a draft, or click Publish to save and immediately apply the rule to live searches.

Visual rules use semantic targeting by default, so the rule also activates for queries that are semantically similar to the one you entered.

​

Set a default variant for pinned products

After pinning a product in the visual editor, you can choose which variant to feature in search results:

1. Click the variant button on the pinned product card.
2. Select the option values you want to display (for example, “Color: Blue, Size: Large”).
3. Preview the matching variant’s price and image in the modal.
4. Click Save to apply.

A default variant is optional. If no default variant is set, the standard variant selection priority determines which variant appears.

​

Create a manual rule

1. Click the rule name in the page header and type a name for the rule.
2. Select a scope:
   • All searches: The rule applies to every text search.
   • Matching searches: The rule applies when its conditions match the query, shopper or traffic context, applied filters, or active sort.
3. If you chose Matching searches, build the targeting conditions:
   • Combine conditions with nested AND and OR groups.
   • For a query condition, select Exact match, Contains, or Semantic match, enter the query value, and, for semantic matching, adjust the similarity threshold slider (50–100%).
   • Add conditions for shopper or traffic context, applied filters, or the active sort when needed.
4. Add one or more actions:
   • Select Promote Products, Demote Products, Sort Expression, Filter Results, Signal Weights, or Spread Results.
   • For Promote Products or Demote Products: select a supported product or variant attribute in the Attribute picker, then select an operator and value. Product examples include vendor, product type, and tags; variant examples include price and availability. Set the strength using the slider (1–50%, labeled Subtle to Strong). If the attribute has facet value groups, the value picker lists each group first with a Group badge, followed by ungrouped raw values. Selecting a group matches every raw member.
   • For Sort Expression: add up to three sorting expressions. Each expression requires a metric attribute, a direction (ascending or descending), and a weight (5–100%) that controls how strongly the metric influences the ranking. See sort action details.
   • For Filter Results: build the nested filter conditions that determine which products remain eligible. The hidden filter is combined with system filters using AND and does not appear as a shopper-selected facet. See add a Filter Results action.
   • For Signal Weights: adjust the five-group weight distribution that should apply for matched requests. Every possible matching path must include a query condition. See add a Signal Weights action.
   • For Spread Results: cap how many products from the same product family or attribute can appear near the top of results. See add a Spread Results action.
   • For Default Selected Options, see Set default selected options to choose preferred option values for matching searches.
5. To add more actions, click Add action. You can combine Promote Products, Demote Products, and Sort Expression actions in a single rule. A rule can carry at most one Signal Weights action.
6. Click Save Changes to save the rule as a draft, or click Publish to save and immediately apply it to live searches.

​

Target what a query asks for

Query dimensions turn a search into labels drawn from a product attribute. For example, a Color dimension can label “blue summer dress” as blue, so a ranking rule can promote products in the color the shopper requested without a separate rule for every color.

​

Create and check a query dimension

You need permission to edit ranking rules to manage dimensions. The default Values selection includes every value. Keep all values selected to include them all, or narrow the selection to at most 150 values. If the attribute has more than 150 distinct values, narrow the Values selection before creating the dimension. Values added to the attribute later are not included automatically when you narrow the selection.

1. Open Query Dimensions and click Create Dimension.
2. Enter a Name and Code, choose the Attribute whose values you want to recognize, and keep all Values selected or narrow the selection to at most 150 values. If the attribute has more than 150 distinct values, you must narrow the Values selection. The code cannot change after creation.
3. Write Instructions explaining when each value applies, when it does not, and when the query has no relevant signal. Include ambiguous examples, not only obvious matches.
4. Click Create dimension. Layers generates keyword rules and checks them in the background. The page shows the progress.
5. Review the generated rules and the Preview table. Add Corrections for exact search words that need a different label or no signal. Review the Corrections list and remove a correction when you no longer need it.

Layers checks keyword rules first. A rule can assign one or more labels, explicitly assign no label, or use Ask the LLM when the meaning depends on context. LLM means the AI language model used to interpret the query. Queries deferred to it are labeled asynchronously; a dimension-dependent rule may not apply to the first search while a label is unresolved. Corrections take priority over generated rules for the exact search words you enter. They are saved as guidance for future generation and remain in place when you edit instructions or regenerate rules.

​

Refine the rules

In Rules, use Test a search to check how the current rules classify a query. Add a Phrase for whole-word matching, or a Word pattern when you need to recognize variations of a single word. Matching ignores case, apostrophes, and plural endings. Choose Labels, leave them empty for a known no-signal phrase, or enable Ask the LLM for context-dependent matches. Click Save rules to apply your changes to subsequent searches and start another comparison with AI labels. Review any warning about rules that were not saved; unsupported patterns or labels outside the selected attribute’s values need correcting.

​

Review the preview

The dimension’s Preview uses top searches from the last 30 days and displays up to 100 searches in a searchable table. Use All, Needs review, No label, and Corrected to filter the table, then search to narrow the displayed rows. The dimension Preview is a classification preview, not a product-results preview. When a search needs a different label, click Fix label, select one or more labels in the popover, and click Save. For a known no-signal search, choose No label instead. The Corrections section lists saved corrections and lets you remove one when you no longer need it. Contact Customer Care if a check continues failing after Recheck.

​

Use labels in ranking rules

• For Matching searches, choose Query asks for: {dimension name} and select the label condition you need. The condition targets what the query requests, not the shopper’s audience membership.
• For Promote Products or Demote Products, use Value: from query and select a dimension. Layers matches products against the values recognized in that query, using the dimension’s product attribute.

If the label is unresolved, a rule targeting that dimension does not match. If a query-derived promote or demote action has no labels, Layers skips that action instead of applying it to all products; other actions in the rule can still run. To delete a dimension, first remove its references from ranking rules, including unpublished rules. Layers blocks deletion while a rule still depends on it.

​

Preview a manual rule before saving

The Preview panel on manual rule create and edit pages compares the current search results with your unsaved rule changes.

1. Enter a search query with at least two characters.
2. Select Before to see results without this rule. Other published rules still apply.
3. Select After to see results with your current edits. The preview assumes this rule’s targeting conditions match, even if it is a draft.
4. Adjust the actions and compare again. Nothing is saved or published by previewing.

The panel shows the top 10 products and the total result count. In After, arrows show movement relative to Before. New means a product was not in the previous top 10, not that it was recently added to your catalog. When an action narrows eligibility, the footer shows how many fewer results remain. If the query redirects to a collection or URL, the panel shows This search redirects and the destination instead of products. Ranking rules do not run for that query, so try another search. If you see Finish configuring your rule, complete the missing or invalid action settings. For Preview unavailable, use Try again. Your saved rule is unchanged; contact Customer Care if the preview keeps failing.

​

Add a sort action

A sort action overrides the default relevance-based ordering for searches matching the rule’s targeting conditions. Use it when specific queries should rank results by a metric, like sales or conversion rate, instead of pure relevance.

1. In the actions section of a manual rule, click Add action and select Sort Expression.
2. Add a sorting expression:
   • Attribute — Select the metric to sort by (for example, a 7-day sales metric or a conversion rate metric).
   • Direction — Select Highest to Lowest to show the highest values first, or Lowest to Highest for the lowest values first.
   • Weight — Set how strongly the metric influences results (5–100%). Lower weights treat the metric as a tie-breaker among products with similar relevance. Higher weights give the metric more control over ranking.
3. To add more expressions, click Add expression. You can include up to three sorting expressions per sort action.
4. Continue adding other actions (promote or demote) if needed, then click Save Changes to save as a draft or Publish to apply the rule to live searches.

The sort blends the selected metrics with relevance scores rather than replacing relevance entirely. Products that closely match the search query keep their position. Products with weaker relevance are reordered more aggressively based on the metric values. As a result, precise queries still return the most relevant products, while broader queries benefit from metric-driven ranking. Example: Create a Matching searches rule with a query condition for “best sellers” and a sort action that uses your 7-day sales metric, descending direction, and a weight of 40%. When a customer searches for “best sellers,” Layers reorders results to favor high-selling products while still accounting for relevance.

​

Add a Filter Results action

A Filter Results action adds a hidden eligibility filter to the requests that match the rule. The filter is combined with system filters using AND, so only eligible products remain. It does not appear as a shopper-selected facet.

1. In the actions section of a manual rule, click Add action and select Filter Results.
2. Build the filter with the nested AND/OR filter builder.
3. Save the rule as a draft and preview it before publishing.

​

Add a Signal Weights action

A Signal Weights action replaces your store’s global signal weight distribution for the queries this rule matches. Use it when a specific query pattern needs a different balance than the rest of your catalog. For example, you can boost inventory weight for "in stock" queries, or push image similarity higher for visually-driven queries like "blue floral dress". Signal Weights actions are available for manual rules using Matching searches when every possible matching path includes a query condition. Choose Matching searches rather than All searches to use this action.

1. In the actions section of a manual rule using Matching searches, click Add action and select Signal Weights. The editor seeds the action with your store’s current pie so you can adjust from there.
2. Adjust each signal group’s contribution by dragging its slider or typing an exact percentage between 1 and 80. The other groups rebalance automatically so the total stays at 100%. See Tune signal weights for what each signal group measures.
3. To fine-tune sub-signals, click the chevron next to a group to expand it. When you leave a group’s sub-signals untouched, it inherits your store’s current sub-signal ratios.
4. Save the rule as a draft and preview it in the search preview before publishing. A Signal Weights action swaps the entire scoring model for matched queries, so result membership and facet counts can shift, not just the ordering.

Only one Signal Weights action is allowed per rule. If multiple published rules match the same request, the first matching rule’s pie wins. Layers skips later rules’ Signal Weights actions, but their Promote Products, Demote Products, pin, and Sort Expression actions still apply. See how rules are evaluated. The rules list shows a badge on rules with a Signal Weights action, naming the two groups that moved the most versus your store’s pie (for example, Engagement 20% → 5%).

​

Add a Spread Results action

A Spread Results action caps how many products from the same group can appear near the top of results for the queries this rule matches. Use it when a query returns page after page of near-identical products, for example one shoe style in eight colors crowding out every other style.

1. In the actions section of a manual rule, click Add action and select Spread Results.
2. Under Group by, choose what counts as a group:
   • Product family — Spread results across your product families. Requires at least one active product family; without families, the cap has no effect.
   • Attribute — Spread results across the values of a categorical attribute you pick, such as product type or vendor.
3. Configure the limits:
   • Window size — How many top positions the cap applies to (default 20). Beyond that window, natural ordering resumes and repeats are allowed.
   • Max per group — The maximum number of products from one group allowed inside the window (default 2).
   • Group coverage — A coverage floor. If fewer than this many distinct groups appear in the window, Layers promotes top-scoring products from missing groups to fill the gap (default 0, off).
4. Click Save Changes to save the rule as a draft, or click Publish to apply it to live searches.

Only one Spread Results action is allowed per rule. The action applies to the default relevance ordering; when a shopper picks an explicit sort such as price or newest, that sort wins. For a store-wide cap that applies to every search without a rule, use the Max per product family setting on the Signal Weights page (see tune signal weights). For caps on collections and merchandised pages, see diversity expressions.

​

Set default selected options

Add the Default Selected Options action to choose the option values Layers prefers when selecting a product’s default variant for searches that match the rule. This action affects search only, not browse requests. For each option, choose Fixed value or Changes by month and set the corresponding value or monthly values. Layers uses the current month in your store’s timezone. If a month’s value is blank, Layers skips that option for that month. If the request already has non-empty default options, the action preserves them unless you enable Override shopper-provided defaults. With the override enabled, the action replaces the complete list of default options rather than merging with it. The Default Selected Options action changes presentation only. It does not filter products or remove variant-breakout tiles. Pinned variants and variants that match the query or keyword signals take priority over these defaults. A configured default takes priority over a clear semantic match to a variant; position is the final fallback.

​

Choose a supported filter property

Promote and demote rules can use supported variant attributes as well as product attributes. A product matches a variant condition when an eligible shopper-visible variant meets it. For example, a negative condition such as price not equal to 20 matches only when none of the shopper-visible variants has a price of 20. Not every variant field is supported; pickup location name fields are not. A variant condition determines which products match the action, not which variant appears on the result tile.

​

Manage existing rules

From Relevancy → Ranking Rules, you can:

• Publish or unpublish a rule from the edit page using the Publish / Unpublish button. Unpublishing takes the rule offline without deleting it so you can republish it later.
• Edit a rule to change its conditions or actions. Rename the rule by clicking its name in the page header.
• Duplicate a rule from its edit page (Duplicate Rule) to create a copy with the same configuration.
• Delete a rule permanently.

​

”No effect” badge

The rules table shows a red No effect badge next to any rule that cannot influence ranking. Hover the badge to see the reason. Layers flags a rule for one of three reasons:

• Unsupported filter property. The rule uses a property that ranking cannot evaluate, such as a pickup location name field. Edit the rule and choose a supported property in the Attribute picker.
• Full-catalog coverage. An All searches rule that promotes or demotes products matching nearly the entire catalog (95% or more) moves every product by the same amount. It cannot reorder results. Narrow the filter to target a specific subset of products, or change the scope to Matching searches.
• Zero catalog coverage. The rule’s filter matches no products in the catalog on the selected property. This usually means the value was mistyped or refers to a raw member that is now inside a facet value group. Pick the group by name instead, or edit the rule and confirm the property and value.

​

Tips

• Use visual rules for your top search queries where precise product placement matters.
• Use manual rules with global scope to apply broad adjustments, like promoting in-stock products or demoting discontinued items across all searches.
• Use sort actions for intent-driven queries where customers expect a specific ordering. For example, sort by sales for “best sellers” or by price for “affordable.”
• Start with a lower sort weight (10–20%) and increase gradually. A lower weight preserves more of the default relevance ranking while still surfacing metric-driven products.
• Combine exact match targeting for high-volume queries with semantic match for long-tail variations.
• Use the manual rule’s Before and After preview to compare unsaved actions. Use Test text search to check published rules in the search workflow.
• Use the draft state to stage and review rule changes before they affect customers. Save changes, verify behavior in the search preview, and publish only when you are confident.

​

Troubleshooting

• My new rule isn’t affecting search results. New rules are created as drafts by default. Open the rule and click Publish to apply it to live searches.
• I clicked Save Changes but the rule still appears inactive on the list. Save Changes only saves the current configuration. It does not change the published state. Click Publish from the edit page to activate the rule.
• I need to temporarily disable a live rule. Open the rule and click Unpublish. The rule keeps its configuration but stops running on live searches until you publish it again.

​

Next steps

• Ranking relevancy — How signal groups and ranking rules work
• Tune signal weights
• Test text search