Filtering

Build filters using the type-safe filter DSL:

import { filter, and, or, eq, gte, lte, inValues } from '@commerce-blocks/sdk'

const collection = sdk.collection({ collectionHandle: 'shirts' })
await collection.get({
  filterGroup: filter(and(
    eq('your-attribute', 'your-value'),
    eq('your-second-attribute', 'your-second-value'),
  )),
})

// Numeric range
await collection.get({
  filterGroup: filter(and(
    gte('your-numeric-attribute', 50),
    lte('your-numeric-attribute', 200),
  )),
})

// Multiple values on the same attribute
await collection.get({
  filterGroup: filter(inValues('your-attribute', ['your-value', 'your-second-value'])),
})

Filter operators

Operator	Description
`eq(property, value)`	Equals
`neq(property, value)`	Not equals
`inValues(property, values[])`	In list
`notIn(property, values[])`	Not in list
`gt(property, number)`	Greater than
`gte(property, number)`	Greater than or equal
`lt(property, number)`	Less than
`lte(property, number)`	Less than or equal
`between(property, min, max)`	Within a numeric range
`notBetween(property, min, max)`	Outside a numeric range
`contains(property, string)`	Contains substring
`doesNotContain(property, string)`	Does not contain substring
`beginsWith(property, string)`	Starts with substring
`endsWith(property, string)`	Ends with substring
`isNull(property)`	Property is null
`notNull(property)`	Property is not null

Date, geo, and other operators without helpers

The DSL has no helper functions for the date operators (after, before, inLast), the geo operators (geoRadius, geoBoundingBox, geoPolygon), or doesNotBeginWith and doesNotEndWith. The Layers API still supports them. To use one, pass a plain filter group object as filterGroup. The SDK sends it to the API unchanged:

// Products published in the last 30 days
const { data, error } = await collection.get({
  filterGroup: {
    conditional: 'AND',
    expressions: [
      { property: 'published_at', operator: 'inLast', values: [30] },
    ],
  },
})

if (error) {
  console.error('Browse failed:', error.message)
}

See Filtering for each operator’s values, and Geospatial filtering for the geo operators.

Filter types

The DSL produces FilterGroup and FilterExpression objects. You typically do not construct these manually, but the types are exported if you need to build filters programmatically:

import type { FilterGroup, FilterExpression } from '@commerce-blocks/sdk'

interface FilterExpression {
  property: string
  operator: FilterOperator
  values: (string | number | boolean)[]
}

interface FilterGroup {
  conditional: 'AND' | 'OR'
  expressions: (FilterExpression | FilterGroup)[]
}

The filter() function wraps a single expression in a FilterGroup automatically, so you can pass either an expression or a group:

// Single expression (wrapped in AND group automatically)
filter(eq('your-attribute', 'your-value'))

// Explicit group
filter(and(
  eq('your-attribute', 'your-value'),
  gte('your-numeric-attribute', 50),
))

// Nested groups
filter(and(
  eq('your-attribute', 'your-value'),
  or(
    eq('your-second-attribute', 'your-second-value'),
    eq('your-second-attribute', 'your-third-value'),
  ),
))

In v3, available facets and their counts are fetched at runtime using sdk.facets(). sdk.facets() replaces the facets array that was passed to createClient() in v2.

const facetController = sdk.facets({ collectionHandle: 'shirts' })

facetController.subscribe(({ data, error }) => {
  if (error) {
    console.error('Facet fetch failed:', error.message)
    return
  }
  if (data) {
    console.log(data.facets)
    console.log(data.facetRanges)
  }
})

await facetController.get()

You can also request filtered facet counts by passing the same filterGroup the shopper has selected:

await facetController.get({
  filterGroup: filter(eq('your-attribute', 'your-value')),
})

Filter shorthand

If a single expression is all you need, pass it directly to filter(). It is equivalent to and(...) for one expression.

await collection.get({ filterGroup: filter(eq('your-attribute', 'your-value')) })

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Filter operators

Date, geo, and other operators without helpers

Filter types

Runtime facet discovery

Filter shorthand

Next steps

​Filter operators

​Date, geo, and other operators without helpers

​Filter types

​Runtime facet discovery

​Filter shorthand

​Next steps

Filter operators

Date, geo, and other operators without helpers

Filter types

Runtime facet discovery

Filter shorthand

Next steps