Skip to main content

​
Filtering

Filters narrow down the rows that go into each aggregation and group. They are AND-combined; there is no OR-group support. The server enforces a per-field operator allow-list, so the exact subset of operators you can use depends on the field.

​
Filter object structure

For standard datasource fields, use fieldName:
{
    "fieldName": "cacheType",
    "operator": "IN",
    "value": ["semantic"]
}

​
Filterable fields

Cache metrics share the underlying table with model metrics, so all model filter fields are also reachable here. The cache-specific fields are cacheType, cacheNamespace, cacheLookupStatus, and the cache token columns. cacheType is narrow (IN/NOT_IN only); the others accept the full string or numeric operator set as documented below.
FieldTypeAllowed operators
cacheTypestringIN, NOT_IN
cacheNamespacestringIN, NOT_IN, STRING_CONTAINS, STRING_STARTS_WITH, STRING_ENDS_WITH
cacheLookupStatusstringfull string operator set
modelNamestringfull string operator set
requestTypestringfull string operator set
virtualModelNamestringfull string operator set, including IS_NULL
httpStatusCodenumberfull numeric operator set
errorCodestringfull string operator set
isFailurebooleanEQUAL, IS_NULL
providerAccountTypestringfull string operator set
providerModelNamestringfull string operator set
costInUSDnumbernumeric range operators
inputTokensnumbernumeric range operators
outputTokensnumbernumeric range operators
cacheCreationInputTokensnumbernumeric range operators
cacheReadInputTokensnumbernumeric range operators
userEmailstringfull string operator set
virtualAccountstringfull string operator set
teamarrayARRAY_HAS_ANY, ARRAY_HAS_NONE
latencyMsnumbernumeric range operators
conversationIDstringfull string operator set
traceIdstringEQUAL
metadataKey / metadata.<key>stringfull string operator set
For non-cache-specific model fields (e.g. costInUSD aggregations or errorCode filters), see also the Model Metrics filtering page.

​
Filter operators

​
String field operators

OperatorDescriptionExample value
EQUALExact match"hit"
NOT_EQUALNot equal to value"miss"
INMatch any value in the list["semantic", "simple"]
NOT_INExclude values in the list["deprecated"]
STRING_CONTAINSContains substring"prod"
STRING_NOT_CONTAINSDoes not contain substring"staging"
STRING_STARTS_WITHStarts with prefix"prod-"
STRING_NOT_STARTS_WITHDoes not start with prefix"internal-"
STRING_ENDS_WITHEnds with suffix"-v1"
STRING_NOT_ENDS_WITHDoes not end with suffix"-deprecated"
IS_NULLtrue matches rows where the field is unset; false matches rows where it is settrue

​
Numeric field operators

OperatorDescriptionExample value
EQUALExact match1000
NOT_EQUALNot equal to value0
INMatch any value in the list[200, 404, 500]
NOT_INExclude values in the list[0]
GREATER_THANStrictly greater than1000
LESS_THANStrictly less than5000
GREATER_THAN_EQUALGreater than or equal to100
LESS_THAN_EQUALLess than or equal to1000
BETWEENBetween two values (inclusive)[500, 5000]
IS_NULLtrue matches rows where the field is unset; false matches rows where it is settrue

​
Boolean field operators

OperatorDescriptionExample value
EQUALExact matchtrue
IS_NULLtrue matches rows where the field is unset; false matches rows where it is setfalse

​
Array field operators (used by team)

OperatorDescriptionExample value
ARRAY_HAS_ANYMatch if the array contains any of the values["team-alpha", "team-beta"]
ARRAY_HAS_NONEMatch if the array contains none of the values["excluded-team"]

​
Custom metadata filtering and grouping

Every datasource supports filtering and grouping by custom request-metadata keys:
  • Filter: { "metadataKey": "environment", "operator": "EQUAL", "value": "prod" }
  • Group: include "metadata.environment" in the groupBy array.
Metadata fields are treated as strings; use the String field operators table.

​
Implicit team unnesting

When team is in groupBy (or used as the column of an aggregation), the server transparently UNNESTs the Teams array CTE before applying RBAC. Callers don’t need to do anything extra. Rows whose Teams array is NULL or empty drop out naturally.

​
Combining multiple filters

Filters are AND-combined: 
{
    "startTs": "2026-04-21T00:00:00.000Z",
    "endTs": "2026-04-22T00:00:00.000Z",
    "datasource": "cacheMetrics",
    "type": "distribution",
    "filters": [
        {"fieldName": "virtualModelName", "operator": "IS_NULL", "value": true},
        {"fieldName": "cacheType", "operator": "IN", "value": ["semantic"]},
        {"fieldName": "cacheNamespace", "operator": "STRING_STARTS_WITH", "value": "prod-"},
        {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
    ],
    "groupBy": ["cacheNamespace"]
}