sitemap.xml llms.txt
Skip to main content

Query Filters

These utilities are used by the adapters to enhance querying for objects.

Learn more

To learn how to structure your query filters, read Filter and sort syntax.

FilterInput​

The FilterInput type defines the accepted formats for specifying filters in query functions of the adapters.

Possible types​

  • string[]: An array of filter strings.
  • string: A single filter string.
  • FilterGroup: Used for boolean searches. Contains filter strings and a logical operator to apply to the filter conditions.

FilterGroup​

The FilterGroup interface defines a flexible structure for constructing filters for boolean and taxonomy searches. It supports combining filters using logical operators and allows recursive nesting for complex filtering logic.

Properties​

  • type ('and' | 'or' | 'taxonomy'): Specifies how the contained filters are combined - either with logical AND, logical OR, or as a taxonomy filter.
  • filters ((string | FilterGroup)[]): An array of filter conditions, which can include raw string filters or nested FilterGroup objects for deeper logical groupings.

parseFilterInput() function​

Parses a FilterInput value into the filter string format expected by the Epicenter APIs. Adapter methods that accept a filter option call this internally, so you don't need to call it yourself unless you're making a request directly through the Router.

Function signature
function parseFilterInput(filterInput: FilterInput | undefined): string | undefined

Function description​

Behavior depends on the shape of filterInput:

  • string[]: Joined into a single string with ; (e.g. ['name=Mike', 'count<=3'] becomes 'name=Mike;count<=3'). An empty array returns undefined.
  • string: Passed through as-is, allowing advanced users to write boolean filter syntax directly. An empty string returns undefined.
  • FilterGroup: Recursively parsed into boolean filter syntax. Filter conditions are joined with ;, then wrapped in () for 'and', [] for 'or', or {} for 'taxonomy'. A single filter within a group is not wrapped. Throws an Error if type is missing or invalid.
  • undefined, or an empty FilterGroup: Returns undefined.

Parameters​

  • filterInput (FilterInput | undefined): The filter value to parse.

Return value​

The platform-compatible filter string, or undefined if there is nothing to filter by.