Filters let you isolate and analyze subsets of your data. You can use filters on any query type, including the Funnel Report, Cohort Report, People Search, and A/B Test Report.

They can be used to isolate data by specific events or properties. Furthermore, you can use filters to isolate data where a person did a certain event with a specific property or just property. Filters become even more powerful when you nest or chain them together using logical operators.

Filter object properties

Property Name

Required?

Description

type

Yes

Filter type:

  • event
  • property

negate

No

Set to true when you want to filter data by "has not done event" or "does not have property", instead of the default positive "has done" or "has property".

with_property

No

Set to true when you want to filter by events which have a specific property attached to it.

while_property

No

Set to true when you want to filter by events where the person has a specific property.

event

Yes, if the type is event.

The index of the event.

property

Yes, if one of the following:

  • type is event
  • with_property is true
  • while_property is true

The index of the property.

first_ever

Optional if the filter type is event

Set to true when you want to filter data where the person did the the event for the first time.

frequency_occurrence

Optional if the filter type is event.

Set to at_least, at_most, or exactly if you want to filter by the number of times an event was done.

frequency_value

Yes, if both of following are true:

  • type is event
  • frequency_occurrence is set

The value used to calculate the frequency occurrence. For example, at least 1 or exactly 6.

comparison_mode

Optional if one of the following:

  • type is property
  • with_property is true
  • while_property is true

The comparison mode to use when filtering by properties, or events with properties. Use comparison modes to filter for specific property values. See Property Filter Comparison Modes.

comparison_string

Required if comparison_mode is not in_range, any_value, or empty.

The string to use when comparing property values.

comparison_range_min

Required when the comparison_mode is in_range.

The minimum value when comparing a property that should be within a range.

comparison_range_max

Required when the comparison_mode is in_range.

The maximum value when comparing a property that should be within a range.

date_range

No

A Date Range object.

Property Filter Comparison Modes

Property Value TypeAcceptable Comparison Modes
Text values"contains", "begins_with", "ends_with"
Numeric values"greater_than", "less_than", "greater_than_or_equal_to", "less_than_or_equal_to", "in_range"
Any values"any_value", "empty", "equals"

Logical Operators

More complex queries will require that multiple filters be chained together as is the case for constructing:

  • All who did/have any of these events/properties (type: "or")
  • All who did/have all of these events/properties (type: "and")
  • All who did/have all of these events/properties in order (type: "then")

Here's how the filter object looks when using logical operators:

Property Name

Required?

Description

type

Yes

One of the following:

  • or
  • and
  • then

operands

Yes

An array of Filters. This can also include nested logical operators, see Nesting Filters .

date_range

No

A Date Range object.

Nesting Logical Operators

Filters can be nested to abitrary depths by placing Logical Operators within Logical Operators. To visualize, imagine a tree, where Logical Operators can be either AND/OR/THEN and filters can be Event, Property, or EventWithProperty:

// Expression Tree
             AND
          /     \
        OR       OR
       /  \      /  \
  Event  Event  AND  Property
               /  \
        Property   EventWithProperty