Filtering (OData)

The filter query parameter every list endpoint accepts, and the one rule that trips people up.

Table of contents

  1. The one rule: every column is qualified
  2. Operators
  3. Combining with other query parameters
  4. Row policies ride along in the same filter
  5. Where else filtering shows up
  6. Common mistake

The one rule: every column is qualified

?filter=widgets.status eq 'active'

Always table.column, never column alone. This is deliberate, not an oversight: filter is also where a row policy gets merged in server-side, and join can bring columns from more than one table into scope at once — qualifying every column keeps “which table does status belong to” unambiguous in every case, not just the simple ones. An unqualified column name is refused with a 400 rather than guessed at.

# Right
?filter=widgets.status eq 'active'

# Refused
?filter=status eq 'active'

Operators

Operator Meaning Example
eq equals widgets.status eq 'active'
ne not equals widgets.status ne 'archived'
gt / ge greater than / or equal widgets.price gt 100
lt / le less than / or equal widgets.price le 50
contains substring match contains(widgets.name,'bolt')
startswith prefix match startswith(widgets.sku,'A-')

Combine conditions with and / or, and group with parentheses:

?filter=(widgets.status eq 'active' or widgets.status eq 'pending') and widgets.price gt 10

String values are single-quoted; numbers and booleans are bare.

Combining with other query parameters

filter composes with join, display, limit, orderBy, and groupBy in the same request — see CRUD endpoints for the full parameter table. When join brings in a related table, that table’s columns become filterable the same qualified way (customers.region eq 'APAC'), since the join target is just another table.column the filter can now see.

Row policies ride along in the same filter

If the caller’s role carries a row policy, its condition is combined with whatever filter you send — you never need to (and can’t) manually add your own role’s restriction; it’s already there before your request reaches the database. See Features → Row policies for how that restriction is actually defined and enforced.

Where else filtering shows up

  • Bulk → filter source (Bulk endpoints) uses the exact same filter syntax to select which rows of a source table get copied.
  • A built-in or custom role’s row policy (Features → Row policies) is authored using this same condition language.

Common mistake

400  server_error  — "status" is not a recognized column

This is almost always a missing table. prefix. Re-check that every column reference in your filter string — including inside contains(...)/startswith(...) — is qualified.


Copyright © CrudApi. Distributed under an open license.

This site uses Just the Docs, a documentation theme for Jekyll.