Skip to main content
LightShip trace filters are structured JSON sent in the request body of POST /traces/query. A filter contains an ANDed list of conditions. Bound columns appear alongside other table columns in Setup → Fields; enable Searchable on any field callers should be able to filter. GET /filter/schema reports the enabled fields and their compatible operators. This page covers the JSON wire format, the operator matrix by logical type, and the relationship between structured filters and the typed expressions used by role policies.

​
Filter body format

A filter object contains a top-level filter key with a conditions array. Every condition includes name and op. Include map for map keys and omit it for table columns. The operator determines whether the condition accepts value, values, or neither.
​
string
Map column containing the field, for example SpanAttributes. Omit for a table column.
​
string
required
The key name inside the map, for example user.id or gen_ai.agent.name.
​
string
required
The operator. Must be an operator compatible with the field’s logical type.
​
string | number | boolean
One comparison value. Used by eq, ne, prefix, has, gt, gte, lt, and lte.
​
array
Multiple values. Used by in, not_in, has_any, has_all, and between. For between, pass exactly two numbers.
exists and not_exists accept neither value nor values.

​
Operator matrix

The backend implements typed expressions for every logical type. The structured operators in the table below are the JSON wire form of the same typed expressions role policies use, so their spelling remains stable for API and cursor compatibility.
GET /filter/schema reports the exact set of operators available for each marked field.

​
String operators

  • eq and ne match exact string values.
  • in and not_in accept a list of string values.
  • prefix matches the beginning of a string value.
  • exists and not_exists test whether the key is present regardless of value.

​
String array operators

  • has checks for a single exact element.
  • has_any checks that at least one of the provided values is present.
  • has_all checks that all provided values are present.

​
Boolean operators

  • eq and ne compare against true or false.

​
Number operators

  • eq, ne, gt, gte, lt, lte compare numeric values.
  • between accepts a two-element range array [min, max].
Number fields are filter-only; role policies deliberately reject them. This design choice keeps policy expressions simple and auditable.