Filters - Grain Analytics

A filter is one condition that an event must meet. POST /{tenantAlias} and POST /count/{tenantAlias} take a filterSet array of filters. Every filter in the array must match. There is no OR.

Filter object

{
  "property": "properties.price",
  "comparison": "GREATER_THAN",
  "value": 100
}

Field	Type	Rule
`property`	string	Required. The property path.
`comparison`	string	Required. One operator from the table on this page.
`value`	any	Required. The value to compare with. Its type must match the property.

Operators

Operator	Matches when	Type of `value`
`EQUALS`	The property equals `value`.	string, number, boolean, or `null`
`NOT_EQUALS`	The property does not equal `value`.	string, number, boolean, or `null`
`GREATER_THAN`	The property is greater than `value`.	number, or an ISO 8601 string for `eventTs`
`LESS_THAN`	The property is less than `value`.	number, or an ISO 8601 string for `eventTs`
`GREATER_THAN_OR_EQUALS`	The property is greater than or equal to `value`.	number
`LESS_THAN_OR_EQUALS`	The property is less than or equal to `value`.	number
`CONTAINS`	The string property holds `value` as a substring.	string
`NOT_CONTAINS`	The string property does not hold `value` as a substring.	string
`IN`	The property equals one element of `value`.	array
`NOT_IN`	The property equals no element of `value`.	array

Property paths

Path	Holds	Example `value`
`properties.<name>`	A property that `track` sent.	`properties.price`, `100`
`properties.<name>.<name>`	A field of a nested object in the properties.	`properties.user.plan`, `"premium"`
`eventName`	The event name. The `event` field of the body does the same.	`"purchase_completed"`
`userId`	The user identifier.	`"user_123"`
`eventTs`	The event time, ISO 8601. The `after` and `before` fields cover whole days.	`"2024-01-01T00:00:00Z"`

Write the full path. plan does not match properties.user.plan.

Types of value

The JSON type of value must match the type of the property.

Type	Example
string	`{ "property": "properties.email", "comparison": "CONTAINS", "value": "@gmail.com" }`
number	`{ "property": "properties.price", "comparison": "GREATER_THAN", "value": 99.99 }`
boolean	`{ "property": "properties.is_premium", "comparison": "EQUALS", "value": true }`
array	`{ "property": "properties.tags", "comparison": "IN", "value": ["featured", "sale"] }`
null	`{ "property": "properties.optional_field", "comparison": "EQUALS", "value": null }`

A string value on a number property returns a type mismatch error. Read the error table on this page.

Examples

Three filters, all of which must match:

curl -X POST https://queryapis.grainql.com/v1/api/query/count/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{
    "event": "purchase_completed",
    "after": "2024-01-01",
    "before": "2024-01-31",
    "filterSet": [
      { "property": "properties.price", "comparison": "GREATER_THAN", "value": 100 },
      { "property": "properties.category", "comparison": "EQUALS", "value": "electronics" },
      { "property": "properties.device", "comparison": "EQUALS", "value": "mobile" }
    ]
  }'

{ "count": 318 }

Several users, with IN:

curl -X POST https://queryapis.grainql.com/v1/api/query/your-tenant-id \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $GRAIN_API_KEY" \
  -d '{
    "after": "2024-01-01",
    "before": "2024-01-31",
    "filterSet": [
      { "property": "userId", "comparison": "IN", "value": ["user_123", "user_456"] },
      { "property": "properties.device", "comparison": "EQUALS", "value": "mobile" }
    ],
    "pagination": { "offset": 0, "size": 100 }
  }'

[
  {
    "eventName": "page_viewed",
    "userId": "user_456",
    "eventTs": "2024-01-15T10:30:00Z",
    "properties": {
      "page": "/home",
      "device": "mobile"
    },
    "eventDate": "2024-01-15",
    "insertId": "unique-event-id"
  }
]

Filter bodies for other tasks:

Task	`filterSet`
Users on a plan who signed up this year	`properties.user.plan` `EQUALS` `"premium"`, and `properties.user.signup_date` `GREATER_THAN` `"2024-01-01"`
One country, three states	`properties.country` `EQUALS` `"US"`, and `properties.state` `IN` `["CA", "NY", "TX"]`
A time range inside a day	`eventTs` `GREATER_THAN` `"2024-01-01T00:00:00Z"`, and `eventTs` `LESS_THAN` `"2024-01-31T23:59:59Z"`
One variant of an experiment	`properties.experiment` `EQUALS` `"homepage_hero"`, and `properties.variant` `EQUALS` `"A"`
Errors outside the admin pages	`properties.severity` `IN` `["high", "critical"]`, and `properties.page` `NOT_CONTAINS` `"/admin"`
Referrals that are not spam	`properties.referrer` `NOT_CONTAINS` `"spam-site.com"`

Errors

A bad filter returns an error body with one error string.

Value of `error`	Cause	What to do
`Invalid property path: 'invalid.property'`	The path is not a property path from the table on this page.	Write the full path, for example `properties.plan`.
`Invalid comparison operator: 'INVALID_OP'`	`comparison` is not one of the ten operators.	Use an operator from the table on this page.
`Type mismatch: expected number, got string for property 'price'`	The JSON type of `value` does not match the property.	Send a number for a number property, and a string for a string property.

Read Query API for the status codes.

Rules for the client

Write the full property path. Use properties.user.plan, not plan.
Send after and before with every filterSet. A date range limits the data that the server scans.
Put the most selective filter first.
Use one IN filter for several values of one property. Filters combine with AND, so two EQUALS filters on the same property match nothing.
To test a filter, count with the filter and count without it, then compare the two numbers. Read Count events.
Make sure that comparison is one of the ten operators before you send the request.

​Filter object

​Operators

​Property paths

​Types of value

​Examples

​Errors

​Rules for the client