nextQL in integration
nextQL filters and boosters shape which items appear and how they rank. Configure them on scenarios and rules, or optionally replace filter/boosters per recommendation request. Full syntax lives in the nextQL reference.
Where nextQL applies
| Setting | Type | Default | Description |
|---|---|---|---|
| scenario.filter | filter | — | Hard exclusion on candidates. |
| scenario.boosters | booster[] | — | Score multipliers on matching items. |
| rules (type=filter|booster) | rule | — | Shared expressions via rulesSlugs. |
| segmentation (auto-nextql) | expression | — | Assign segment names — see Segmentations guide. |
| hybrid search | parsed query | — | Price/category extracted from natural language. |
Prefer scenarios and shared rules for durable placement policy. For one-off tuning or Admin Try it, POST /recommendations (and legacy recommend GETs) also accept request-time overrides for filter, boosters, rulesSlugs, segmentationId, itemsPerSegment, autoRelaxFilters, and relaxEntireFilterOnEmpty — omit keeps the scenario value; send a value to replace that field. Constraints remain scenario-only.
Filters
Syntax: quoted attribute names, comparisons, and / or, in / not_in / contains / not_contains. When scenario autoRelaxFilters is on and the full filter matches nothing, clauses drop right to left — put durable predicates on the left. See Query planning for filter auto-relax.
'stock' > 0
'category' in ['pc', 'console']
'tags' contains 'rpg'
'allowed_countries' not_contains 'CN'
'price' < 40 and 'genre' in ['roguelike', 'rpg']
('platform' = 'vr' or 'featured' = true) and 'stock' > 0In-stock only on all placements
Create a rulein-stock with 'stock' > 0 and add to every scenario's rulesSlugs.
PC-only PDP similar
Scenario filter: 'platform' in ['pc', 'multi'] on pdp-similar-pc.
Boosters
Syntax: boost by <factor> where <filter_expression>
boost by 1.5 where 'featured' = true boost by 1.3 where 'genre' in ['rpg', 'action'] boost by 0.7 where 'stock' < 10
Promote featured without excluding non-featured
Boosters re-rank; they do not guarantee inclusion. Pair with filters only when items must be excluded entirely.
Sale items on homepage
"boosters": [ "boost by 1.4 where 'onSale' = true", "boost by 1.2 where 'discountPercent' > 20" ]
Attribute resolution
Attributes resolve from top-level category, then attributes.*. In expressions use'price', not attributes.price. Use in / not_in when the attribute is a scalar checked against a literal list. Use contains / not_contains only when the item attribute is an array (enum/list); RHS is a scalar. These operators are fail-closed: missing, null, or non-array → false. For denylists, every item must have the array ([] = not blocked). There is no unary !.