Filters

Narrow any analytics query to the events you care about.

Filters restrict a query to matching events. The same filters work in the SDK, the API, and the dashboard, so the expression you write in code is exactly what the server evaluates.

How filters work

Build a filter with the filter(field, operator, value) helper and pass it to any analytics method:

typescript

const proCheckouts = await vanta.count({
  filters: filter('data.plan', 'equals', 'pro'),
  time: timeRange('2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'),
})

Operators

Operator	Description
`equals`	Exact match
`not_equals`	Not equal
`contains`	Contains the value
`not_contains`	Does not contain the value
`starts_with`	Starts with the value
`ends_with`	Ends with the value
`in`	Value is in an array
`not_in`	Value is not in an array
`gt`	Greater than
`gte`	Greater than or equal
`lt`	Less than
`lte`	Less than or equal
`exists`	Field is not null
`not_exists`	Field is null

The exists and not_exists operators take no value:

typescript

const withRefund = await vanta.count({
  filters: filter('data.refunded', 'exists'),
  time: timeRange('2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'),
})

Field names

Filter fields resolve to the columns behind your events. Aliases map to their stored columns, and data.* and context.* paths target nested properties:

Field	Resolves to
`event`	`type`
`userId`	`user_id`
`groupId`	`group_id`
`sourceId`	`source_id`
`projectId`	`project_id`
`createdAt`	`created_at`
`data.plan`	nested event data
`context.country`	nested event context

Combining filters

Combine conditions with and() and or():

typescript

const conversions = await vanta.count({
  filters: and(
    filter('type', 'equals', 'checkout.completed'),
    or(
      filter('data.plan', 'equals', 'pro'),
      filter('data.plan', 'equals', 'team'),
    ),
  ),
  time: timeRange('2024-01-01T00:00:00Z', '2024-12-31T23:59:59Z'),
})

Groups can nest: an or() inside an and(), and so on. Nesting depth is capped at 5 levels.

Nesting depth

Keep filter trees shallow. Overly deep nesting is rejected, so design queries as a few clear groups rather than a long chain.

Try it

Build a filter below and see the SDK helper and the JSON sent to the API update live:

Build a filterField

Operator

Value

SDK helper

JSON sent to the API