Documentation

Filters

Filter syntax for widget queries

Basic filter object

Attach filter to a widget to narrow matching events.

widget.metric({
  id: 'pricing_visitors',
  label: 'Pricing Visitors',
  event: '$pageview',
  aggregation: 'unique_users',
  filter: {
    $pathname: '/pricing',
  },
})

Supported operators

Pattern	Meaning	Example
Primitive value	Equals	`{ plan: 'pro' }`
`$in`	In list	`{ plan: { $in: ['pro', 'enterprise'] } }`
`$gte`	Greater than / equal	`{ amount: { $gte: 100 } }`
`$lte`	Less than / equal	`{ amount: { $lte: 500 } }`

Examples

// Campaign traffic only
filter: { $utm_source: 'google' }

// Multi-country
filter: { $geo_country: { $in: ['US', 'CA', 'GB'] } }

// Revenue threshold
filter: { amount: { $gte: 100 } }

Funnel step filters

widget.funnel({
  id: 'pricing_to_signup',
  title: 'Pricing to Signup',
  steps: [
    {
      event: '$pageview',
      label: 'Pricing Page',
      filter: { $pathname: '/pricing' },
    },
    {
      event: 'signup_completed',
      label: 'Signup Complete',
      filter: { plan: 'pro' },
    },
  ],
})

Current query translation limits

Each query supports one filter condition (exploration filters are combined into it, see above)
FilterGroup and nested AND/OR trees are rejected by the query layer
Operators outside eq/in/gte/lte are rejected

Exploration filters in the dashboard

Viewers can add one exploration filter from the dashboard header or by clicking a category in a breakdown, bar or pie chart. It is applied on top of each widget's code-defined filter and never replaces it. Because each query accepts one condition, the two filters are combined into a single condition when possible:

Code filter	Exploration filter	Result
`{ country: { $in: ['GB', 'FR'] } }`	`country = GB`	Queried as `country = GB`
`{ country: { $in: ['GB', 'FR'] } }`	`country = US`	"No matching events" (nothing is queried)
`{ plan: { $in: ['pro', 'team'] } }`	`plan is one of team, free`	Queried as `plan is one of team`
`{ amount: { $gte: 10 } }`	`amount = 25`	Queried as `amount = 25` (`amount = 5` would be no match)
`{ plan: 'pro' }`	`country = US`	"Filters can't be combined" notice: different properties need two conditions (nothing is queried)