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 |
Date Filtering
Filter by date fields using human-readable date strings. The following input formats are accepted:
| Format | Example |
|---|---|
YYYY-MM-DD | 2024-01-15 |
YYYY-MM-DD HH:MM:SS | 2024-03-20 14:30:00 |
YYYY-MM-DDTHH:MM:SS.000Z | 2024-06-15T12:00:00.000Z |
YYYY-MM-DD HH:MM:SS.000Z | 2024-06-15 12:00:00.000Z |
| Unix timestamp (milliseconds) | 1734220800000 |
All filter operators work on date fields, including equality, comparison, and inclusive ranges:
| Syntax | Description |
|---|---|
extensions.products(metadata).created_date:=2024-01-15 | Created exactly on this date |
extensions.products(metadata).created_date:2024-01-15 | Same as := — for dates, : matches exactly |
updated_at:>=2024-06-01 | Updated on or after this date |
updated_at:<2024-06-01 | Updated before this date |
created_at:=[2024-01-01..2024-07-01] | Created between two dates (inclusive) |
extensions.products(inventory).last_updated:>2024-06-15T12:00:00.000Z | Date extension field after a timestamp |
- A date-only value such as
2024-01-15resolves to the start of that day (00:00:00UTC). To match a specific moment, include a time component. - Because date-only values resolve to midnight, an inclusive range such as
created_at:=[2024-01-01..2024-06-30]covers2024-01-01 00:00:00up to2024-06-30 00:00:00— it does not include products created later on2024-06-30. To include the whole of the final day, set the upper bound to the start of the next day (created_at:=[2024-01-01..2024-07-01]) or use an explicit end-of-day time (2024-06-30 23:59:59). The same applies to comparison operators:created_at:<2024-06-30excludes the whole of2024-06-30, whilecreated_at:<=2024-06-30matches only the midnight boundary. - Unlike text fields, the contains operator (
:) behaves the same as exact match (:=) on date fields. - An invalid date value returns a
400validation error.
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 |
Profile filters and segmentation
Search profile default filters use the same filter_by syntax as request filters. When a catalog rule sets search_profile_slug, those profile filters apply to every shopper search for that segment — a common way to limit assortment (for example to a hierarchy node) without a second catalog.
Example profile filter (products under a Clothing node):
meta.search.nodes.name:=Clothing
Profile filters are combined with OR across the profile’s filter list, then ANDed with any filters on the search request. See How a search profile is chosen for how the profile is selected, and Price Segmentation for a walkthrough that attaches a filtered profile to a catalog rule.
If products are cross-listed under multiple hierarchy nodes, other nodes may still appear in navigation; they only include products that also match the profile filter.