Filtering

Filter format

This format applies to lookup-table rows. Duplicate-set filters and scan selections have their own schemas; see Duplicate Detection.

Send a filter in the JSON body of Query rows. GET row requests do not accept filter parameters.

Operator	Matches
eq	A value equal to the supplied value after normalization.
in	Any value in a nonempty list.
and	Every condition in a group.
or	Any condition in a group.
eq: null	An empty cell.

For example, match an account domain:

{ "filter": { "field": "account_domain", "eq": "acme.example.com" } }

Use the field's key, not its display label, and send the correct JSON type. Text equality ignores case; it does not match partial text. See Value formats for numbers, booleans, dates, and other types.

Choose a field

You can filter any readable field marked filterable: true. Lookup key does not need to be enabled. While a table is being prepared, fields can report filterable: false; wait and fetch the schema again.

Filtering and uniqueness are separate. A field with unique: false can match several rows. A nonempty value on a field with unique: true matches at most one row. No matches returns 200 and data: [].

For example, a non-unique region field can match several account-owner rows:

{ "filter": { "field": "region", "eq": "EMEA" } }

The key must be allowed to read every field used in a filter. A filtered field does not have to appear in the response's fields selection; that list only controls what is returned.

Match several values

Use in for any value in a nonempty list:

{
  "filter": {
    "field": "account_domain",
    "in": ["acme.example.com", "blue-lake.example.com"]
  },
  "fields": ["account_domain", "owner_email"]
}

Results use row-ID order, not the order of values in the list. Follow next_cursor for more results.

Combine conditions

Use and when all conditions must match, or or when any can match. Each group must be nonempty. Each condition contains field and either eq or in, never both.

This query combines account-domain matches with an owner-email condition. Both fields must be readable and filterable:

{
  "filter": {
    "and": [
      {
        "or": [
          { "field": "account_domain", "eq": "acme.example.com" },
          { "field": "account_domain", "eq": "blue-lake.example.com" }
        ]
      },
      { "field": "owner_email", "eq": "dana.whitfield@example.com" }
    ]
  }
}

Use flat groups, an and of or groups, or an or of and groups. If a filter is too complex, simplify the nesting or split the query.

Empty cells

Use eq: null to find empty cells:

{ "filter": { "field": "account_domain", "eq": null } }

This can match several rows even on a unique field. It does not match 0, false, or an empty string. Empty-string filters are rejected, and null cannot appear in an in list.

Pagination

Keep the same filter structure, condition order, in value order, and segment settings when using a cursor. Continue until next_cursor is null, even after an empty page. Omitting filter reads all rows the key may read, with pagination.

See Pagination for cursor recovery and Errors for invalid filters and values.

Unsupported filters

Lookup-row queries do not support range comparisons, contains, prefix, or suffix searches, regular expressions, fuzzy matching, NOT or not-equal conditions, or comparing one field with another. Read the relevant values and apply those comparisons in your application.

Rows are always returned in ascending ID order. Read all pages before applying a different sort in your application.

Try a filter

The API Playground supports equality conditions combined with AND. To use in, OR, empty-cell filters, or pagination options, copy a sample and edit it in your application or API client.