Skip to main content

​
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:
FeatureHard DemotionSoft Demotion
BehaviorBinary - all matching products pushed to bottomThreshold-based - items above threshold are immune, items below receive proportional demotion
Search contextWorks in both search and browseOnly works in search (falls back to hard in browse)
Use caseCompletely hide unwanted productsReduce visibility while preserving relevance for best matches
ConfigurationDefault behaviorEnable 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
  • contains / does not contain - Partial text matching
  • begins with / does not begin with - Prefix matching
  • ends with / does not end with - Suffix matching
  • 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)
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)
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.

​
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