> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a ranking rule

> Create a ranking rule in Layers to promote, demote, pin, or sort products in search results based on query patterns, filters, and shopper conditions.

## 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. Your saved configuration is preserved and can be republished later.

This two-step workflow lets you stage changes to an existing rule without affecting live results. Edit the rule, click **Save Changes**, and preview the rule's behavior before clicking **Publish**.

## Select a rule type

1. Go to **Ranking Relevancy** and click the **Rules** tab.
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 rule** — 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 a search query — this is the 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.

This is optional — if no default variant is set, the standard [variant selection priority](/platform/ranking-relevancy#keyword-matched-variant-selection) 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**:
   * **Global** — The rule applies to every text search.
   * **Query-specific** — The rule only applies when the search query matches a condition you define.
3. If you chose query-specific, configure the targeting condition:
   * Select a match type: **Exact match**, **Contains**, or **Semantic match**.
   * Enter the query value to match against.
   * For semantic match, adjust the **similarity threshold** slider (50–100%) to control how closely a query must relate to trigger the rule.
4. Add one or more **actions**:
   * Select **Promote**, **Demote**, or **Sort**.
   * For **Promote** or **Demote**: select the product attribute to match (e.g., vendor, product type, tags), then select an operator and value. Set the **strength** using the slider (1–50%, labeled Subtle to Strong).
   * For **Sort**: 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](#add-a-sort-action) below.
5. To add additional actions, click **Add Action**. You can combine promote, demote, and sort actions in a single rule.
6. Click **Save Changes** to save the rule as a draft, or click **Publish** to save and immediately apply it to live searches.

## 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**.
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** — Choose **Descending** to show the highest values first, or **Ascending** 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. This means precise queries still return the most relevant products, while broader queries benefit from metric-driven ranking.

**Example:** Create a query-specific rule targeting "best sellers" with a sort action that uses your 7-day sales metric, descending direction, and a weight of 40%. When a customer searches for "best sellers," results are reordered to favor high-selling products while still accounting for relevance.

## Manage existing rules

From the **Rules** tab, 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 to create a copy with the same configuration.
* **Delete** a rule permanently.

## 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, sorting 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 search preview on the signal weights page with ranking rules toggled on to verify rule behavior before going live.
* 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](/platform/ranking-relevancy) — How signal groups and ranking rules work
* [Tune signal weights](/help/ranking-relevancy/tune-signal-weights)
* [Test text search](/help/evaluate/test-text-search)