Filtering Search Results
Use the filter_by parameter to apply conditions to narrow down search results based on specific field values. Filters run before faceting and sorting to refine the product set.
Exact vs Non-Exact Filtering
Exact match (:=) - Matches the complete field value verbatim:
meta.search.nodes.name:=Shoe
Matches only products with a node named exactly "Shoe", not "Shoe Rack".
Non-exact match (:) - Performs word-level partial matching (faster, ignores token position):
meta.search.nodes.name:Shoe
Matches "Shoe", "Shoe Rack", "Outdoor Shoe", and so on.
For fields without spaces in their values (for example, SKUs and IDs), use : instead of := to avoid unnecessary token position checks.
Multiple Values and Special Characters
Filter by multiple values using array syntax:
meta.search.nodes.name:=[`Running Shoes, Men`, `Sneaker (Men)`, Boots]
Use backticks (`) to escape special characters like commas and parentheses in field values.
Negation
Exact negation (:!=) - Exclude exact matches:
id:!=[id1, id2]
Partial negation (:!) - Exclude if a field contains the word:
name:!Jackson
Excludes all products whose name contains "Jackson".
Numeric Filtering
Use comparison operators (>, >=, <, <=, =) or range notation [min..max]:
| Syntax | Description |
|---|---|
price.amount:<4000 | Products under 4000 |
price.float_price:[10..100] | Products priced between 10 and 100 |
price.float_price:[<10, >100] | Products under 10 OR over 100 |
price.float_price:[10..100, 140] | Between 10–100 OR exactly 140 |
price.float_price:!=[10, 100, 140] | Exclude products with these exact values |
Tax-Aware vs Tax-Agnostic Price Filtering
Tax-agnostic (recommended for most use cases):
price.amountorprice.float_price— includes all products regardless of tax settings
Tax-aware (filters based on tax inclusion):
meta.display_price.with_tax.(amount|float_price)— only products with a tax-inclusive pricemeta.display_price.without_tax.(amount|float_price)— only products with a tax-exclusive price
Sales prices are not supported. Only base prices are used for filtering. Products can have multiple prices across price books; the system uses the contextually appropriate price based on catalog rules.
Combining Multiple Conditions
Use && (AND) and || (OR) operators with parentheses for complex logic:
| Example | Description |
|---|---|
meta.search.nodes.name:=Shoes && meta.search.nodes.name:=Outdoor | Products in both categories |
meta.search.nodes.name:=Shoes || meta.search.nodes.name:=Outdoor | Products in either category |
(meta.search.nodes.name:=Shoes || meta.search.nodes.name:=Outdoor) && extensions.products(Details).rating:>3.0 | High-rated products in either category |
Prefix Filtering
Use the * wildcard to match fields starting with a specific prefix.
Word-level prefix matching (:):
name:St*
Matches any word in the name starting with "St", such as "Steve Jobs" or "Adam Stator".
Field-level prefix matching (:=):
name:=St*
The field value must start with "St". Matches "Steve Jobs" but not "Adam Stator".
Product Variations
Filter parent and child products by their variation options (for example, color and size) using these fields:
| Field | Description |
|---|---|
meta.search.variation_options.variation_id | The variation's ID |
meta.search.variation_options.variation_name | Variation name (for example, "color", "size") |
meta.search.variation_options.id | Specific variation option ID |
meta.search.variation_options.name | Option name (for example, "red", "small") |
meta.search.variation_options.description | Option description (for example, "Red", "Small") |
Examples:
| Filter | Description |
|---|---|
meta.search.variation_options.name:=red | All products (parent and child) with "red" variation option in any variation |
meta.search.variation_options.name:=red && product_types:=parent | Only parent products with "red" variation option |
meta.search.variation_options.name:=red && product_types:=child | Only child products with "red" variation option |
meta.search.variation_options.description:=Red && meta.search.variation_options.description:=Small | Products with both "Red" AND "Small" variation options |
Product Bundles
Filter bundle products by their component products using these fields:
| Field | Description |
|---|---|
meta.search.component_options.id | Product ID within a bundle component |
meta.search.component_options.component_name | Component display name |
meta.search.component_options.component_key | Unique component identifier |
Examples:
// Bundles containing a specific product in any component
meta.search.component_options.id:=5ba48544-55c3-4f31-a29e-d4365d74b53c
// Bundles containing a specific product in a specific component
meta.search.component_options.{id:=5ba48544-55c3-4f31-a29e-d4365d74b53c && component_key:=component-1}
Operator Reference
| Operator | Description | Example |
|---|---|---|
:= | Exact match | status:=live |
: | Contains (word match) | name:laptop |
:!= | Not equal (exact) | status:!=draft |
:! | Does not contain | name:!refurbished |
:> | Greater than | price.amount:>1000 |
:>= | Greater than or equal | price.amount:>=1000 |
:< | Less than | price.amount:<500 |
:<= | Less than or equal | price.amount:<=500 |