Rules Engine

The Rules Engine applies your business logic to scored candidates before the response is returned. Contexts decide how candidates are found and ranked; rules decide what must, must not, or should preferably appear, and where. Open Relevance → Rules Engine. Use rules when you need to:

• promote or demote matching items
• suppress repeats or cap over-represented content
• pin items to exact positions
• override sort order or inject controlled randomness
• return grouped results instead of a flat list
• weight results using user topic affinity

---

​

Creating a rule

Each rule also has a History tab listing every change made to it. Pin, cap and diversity rules need the Pro plan or above.

---

​

Where rules fit

Rules are where all item eligibility lives, including “only in-stock items” or “only this category” for one placement: create a filter rule scoped to that context.

---

​

Rule type reference

---

​

Choosing the right rule

Think about rules in four buckets:

• Score modifiers: boost, bury, weighted_topic
• Hard constraints: filter, cap, diversity, dedupe
• Ordering controls: pin, randomize, reorder, ensure_top
• Response shaping: group_by

This makes rule design simpler:

• Use boost or bury when you want relevance to matter, but not be absolute.
• Use filter when an item must never appear.
• Use cap or diversity when too much of one class of content is crowding the list.
• Use pin when a specific item must occupy a specific slot.
• Use reorder when relevance should be secondary to a known business sort such as recency.
• Use group_by when the consuming surface is meant to show grouped entities rather than a flat list.

---

​

Conditions

Conditions decide which items a rule applies to. All conditions must match (AND). A rule with no conditions applies to every item in scope. A condition’s field can be:

• an item metadata key, such as category, brand, price or availability;
• segment_id, to apply the rule only when the requesting user belongs to a segment;
• the ranker’s predicted score;
• user.topic_affinity.<field>, the user’s learned affinity for the item’s value of that field.

Operators: equals, not equals, contains, does not contain, greater than, less than, in, not in, exists and does not exist.

​

Item metadata conditions

Match against fields in the item’s metadata:

​

Segment conditions

Target a rule to users in a specific segment: This is how you build targeted campaigns, such as boosting a new series only for users who have not yet watched it.

---

​

Notes for each rule type

​

boost

Use boost when you want a soft promotion rather than a hard override. Higher weights push matching items upward while still allowing genuinely stronger results to compete.

​

bury

Use bury for items that should remain eligible but less prominent, such as low-margin products, stale inventory, or low-quality content.

​

filter

Use filter for non-negotiable constraints such as compliance, availability, or market restrictions. Once filtered out, an item is gone for that request.

​

pin

Use pin when a specific item must land in a precise slot. Pinning happens after ranking, so it is best for high-confidence placements like launch heroes or mandated disclosures.

​

cap

Use cap when matching items are allowed, but only up to a share of the list. This is especially useful for sponsored, house-brand, or single-vendor content.

​

diversity

Use diversity when a single attribute dominates the list. Common fields are brand, category, series_id, or author.

​

dedupe

Use dedupe when repeated entities hurt trust or usefulness. Typical examples are not showing the same SKU twice in a carousel or the same article again in the next few positions.

​

randomize

Use randomize on exploratory or serendipity-focused surfaces where exact ranking is less important than freshness and variety.

​

reorder

Use reorder when business logic should temporarily outweigh relevance, such as sorting by published_at desc for a latest-news rail or by price asc for a clearance shelf.

​

ensure_top

Use ensure_top to protect the top band from becoming entirely campaign-driven. It works well alongside boosts and pins when you still want the first few results to remain relevance-led.

​

group_by

Use group_by when the consuming UI is designed around grouped entities, such as categories, brands, or collections instead of single items.

​

weighted_topic

Use weighted_topic when users engage with recognisable topics and you want ranking to follow, or deliberately cut across, that affinity. Its settings:

---

​

Scheduling

Rules support time-based activation via start and end dates.

​

Setting a schedule

Schedules are evaluated on NSL’s servers at request time, so they behave the same wherever the request comes from.

---

​

Priority and execution order

Rules execute in descending priority order (highest first). When multiple rules affect the same item:

• A pin at priority 100 can still place an item ahead of a boost at priority 50.
• A filter removes the item entirely, so later rules never see it.
• A cap or diversity rule can trim over-represented content even after score adjustments.

Use priority deliberately:

• 100+ for hard business constraints and compliance-sensitive rules
• 50-99 for campaigns, featured placements, and seasonal pushes
• 1-49 for softer merchandising preferences

---

​

How rules interact with experiments

Each experiment variant can choose which rules apply to its users, so you can test a rule or set of rules against a control group before rolling it out.