Ranking rules

Boost, pin and hide products based on business rules.

Ranking rules let you override the engine's relevance ordering with rules that encode business logic — pin best-sellers, hide out-of-stock, boost by margin. All rules are applied on top of the text-match score, after filtering.

# Rule kinds

Kind Effect
boost Multiply the score of matching documents.
pin Force-rank matching documents to the top, in the order given.
hide Remove matching documents from results entirely.
bury Force-rank matching documents to the bottom.

# Endpoints

# List rules

GET /v1/indexes/{name}/ranking-rules

# Create a rule

POST /v1/indexes/{name}/ranking-rules

{
  "name": "Promote in-stock",
  "type": "boost",
  "conditions": { "query_contains": [] },
  "effect": { "filter_by": "in_stock:true", "weight": 5 },
  "priority": 100,
  "enabled": true
}

Fields:

  • conditions.query_contains — list of query tokens that must be present for the rule to fire. Empty array = always fires.
  • effect.filter_by — same expression language as the query filter_by.
  • effect.weight — positive integer added to the text-match score on match (typical values: 3–10).
  • priority — rules with higher priority win on conflict.

# Update / delete

PATCH /v1/indexes/{name}/ranking-rules/{id}
DELETE /v1/indexes/{name}/ranking-rules/{id}

# Example: pin two SKUs to the top of "650" searches

{
  "name": "UTB 650 — pin OEM parts",
  "type": "pin",
  "conditions": { "query_contains": ["650"] },
  "effect": { "documents": ["UTB-650-OEM-12", "UTB-650-OEM-13"] },
  "priority": 200,
  "enabled": true
}

# Order of operations

  1. Filter (filter_by)
  2. Engine retrieval + text-match score
  3. Skryx relevance bonuses (prefix, SKU, brand)
  4. Ranking rules (this page)
  5. Sort by final score, then by default_sorting_field
esc