> ## 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.

# Priority rules

> Use priority rules in Layers sort orders to force products to the top or bottom of results with hard override behavior based on conditions and tags.

## Priority rules: hard override behavior

Priority rules use conditional logic to force matching products to the top or bottom of results. They are always evaluated first as **hard overrides**, regardless of where they appear in the sort group. The behavior is determined by the rule's **direction** setting:

* **Descending direction (Promote)**: Forces matching products to the top of results
* **Ascending direction (Demote)**: Forces matching products to the bottom of results

Priority rules take precedence over all other sort expressions. The remaining expressions — soft boosts, metrics, and product attributes — determine the ordering **within** the groups created by priority rules. This means:

* Promoted products always appear at the top, regardless of their metric values or boost scores
* Demoted products always appear at the bottom, regardless of their metric values or boost scores
* Within promoted, regular, and demoted groups, the other sort expressions (metrics, soft boosts, attributes) determine the ordering

This hard override behavior ensures that promotions and demotions work as expected. Promoted products always appear at the top, demoted products always appear at the bottom, and the remaining sort expressions handle fine-grained ordering within each group.

### Soft demotion for priority rules

When demoting products in a search context, you can enable **soft demotion** to apply relevance-damped demotion instead of hard binary demotion. This allows highly relevant products to resist demotion while weaker matches receive proportional demotion.

**How it works:**

Soft demotion uses a configurable relevance threshold to determine which products are affected by demotion:

* **Items with relevance score >= threshold** → immune to demotion
* **Items with relevance score \< threshold** → proportional demotion based on distance below threshold

**Relevance threshold:**

The threshold parameter (default: 0.5, range: 0-1) controls which products are protected from demotion:

* **Higher threshold (e.g., 0.7)**: Only highly relevant items are immune; more products receive demotion
* **Lower threshold (e.g., 0.3)**: More items are protected; only weak matches receive demotion
* **Default (0.5)**: Balanced protection for moderately relevant items

**When it applies:**

Soft demotion only activates when all three conditions are met:

1. **Soft field is enabled** (`soft: true`)
2. **Search context** (vector search is active, not browse)
3. **Demotion direction** (direction = 'asc')

In browse context or for promotions (direction = 'desc'), soft demotion automatically falls back to hard demotion.

**UI control:**

When creating a priority rule on a relevance sort order with demotion direction, a **Soft Demotion** toggle appears in the UI. Enable this toggle to reveal a **Relevance Threshold** slider (0-100, representing 0.0-1.0) that controls which products are immune to demotion.

**Hard demotion vs. soft demotion:**

| Feature            | Hard Demotion                                   | Soft Demotion                                                                                 |
| ------------------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **Behavior**       | Binary - all matching products pushed to bottom | Threshold-based - items above threshold are immune, items below receive proportional demotion |
| **Search context** | Works in both search and browse                 | Only works in search (falls back to hard in browse)                                           |
| **Use case**       | Completely hide unwanted products               | Reduce visibility while preserving relevance for best matches                                 |
| **Configuration**  | Default behavior                                | Enable `soft: true` toggle and set relevance threshold (default: 0.5)                         |

## Available operators

When building priority rules, you can use various operators depending on the attribute type:

**Text operators:**

* `equals` / `does not equal` - Exact match comparison (case-insensitive)
* `contains` / `does not contain` - Partial text matching (case-insensitive)
* `begins with` / `does not begin with` - Prefix matching (case-insensitive)
* `ends with` / `does not end with` - Suffix matching (case-insensitive)
* `in` / `not in` - Match any value in a list (case-insensitive; multi-select enabled in UI)
* `is null` / `is not null` - Check if attribute has a value (no value field shown in UI)

<Note>
  String comparisons in priority rules are case-insensitive across every operator, so a rule matching `"sale"` also matches `"Sale"` and `"SALE"`. Numeric and boolean equality stays exact.
</Note>

**Numeric operators:**

* `equals` / `does not equal` - Exact numeric match
* `greater than` / `greater than or equal` - Value comparisons
* `less than` / `less than or equal` - Value comparisons
* `between` / `not between` - Range matching (requires two values)
* `in` / `not in` - Match any value in a list (multi-select enabled in UI)
* `is null` / `is not null` - Check if attribute has a value (no value field shown in UI)

**Date operators:**

* `equals` / `does not equal` - Exact date match
* `after` / `before` - Date comparisons
* `between` / `not between` - Date range matching (requires two values)
* `is null` / `is not null` - Check if attribute has a value (no value field shown in UI)

**Tag operators:**

* `contains` / `does not contain` - Check if tag exists
* `in` / `not in` - Match any tag in a list (multi-select enabled in UI)

<Note>
  When you select `is null` or `is not null` operators, the value field is automatically hidden in the UI since these operators check for the presence or absence of data without requiring a comparison value.
</Note>

### When to use null operators

The `is null` and `is not null` operators are useful for filtering products based on whether an attribute has been set:

**Example use cases:**

* `inventory_quantity is null` - Demote products with no inventory tracking
* `compare_at_price is not null` - Promote products on sale (have a compare-at price)
* `vendor is null` - Demote products missing vendor information
* `metafield.custom.priority is not null` - Promote products with a custom priority field set

## See also

* [Sort Orders Overview](/platform/sorting)
* [Priority Rule Examples](/platform/sorting/priority-rule-examples)
* [Soft Boost](/platform/sorting/soft-boost)