Cache Metrics: Filtering

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

Field filters
Metadata filters

For standard datasource fields, use fieldName:

{
    "fieldName": "cacheType",
    "operator": "IN",
    "value": ["semantic"]
}

For custom request-metadata keys, use metadataKey. Works on every datasource:

{
    "metadataKey": "environment",
    "operator": "IN",
    "value": ["production"]
}

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.

Field	Type	Allowed operators
`cacheType`	string	`IN`, `NOT_IN`
`cacheNamespace`	string	`IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`
`cacheLookupStatus`	string	full string operator set
`modelName`	string	full string operator set
`requestType`	string	full string operator set
`virtualModelName`	string	full string operator set, including `IS_NULL`
`httpStatusCode`	number	full numeric operator set
`errorCode`	string	full string operator set
`isFailure`	boolean	`EQUAL`, `IS_NULL`
`providerAccountType`	string	full string operator set
`providerModelName`	string	full string operator set
`costInUSD`	number	numeric range operators
`inputTokens`	number	numeric range operators
`outputTokens`	number	numeric range operators
`cacheCreationInputTokens`	number	numeric range operators
`cacheReadInputTokens`	number	numeric range operators
`userEmail`	string	full string operator set
`virtualAccount`	string	full string operator set
`team`	array	`ARRAY_HAS_ANY`, `ARRAY_HAS_NONE`
`latencyMs`	number	numeric range operators
`conversationID`	string	full string operator set
`traceId`	string	`EQUAL`
`metadataKey` / `metadata.<key>`	string	full 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

Operator	Description	Example value
`EQUAL`	Exact match	`"hit"`
`NOT_EQUAL`	Not equal to value	`"miss"`
`IN`	Match any value in the list	`["semantic", "simple"]`
`NOT_IN`	Exclude values in the list	`["deprecated"]`
`STRING_CONTAINS`	Contains substring	`"prod"`
`STRING_NOT_CONTAINS`	Does not contain substring	`"staging"`
`STRING_STARTS_WITH`	Starts with prefix	`"prod-"`
`STRING_NOT_STARTS_WITH`	Does not start with prefix	`"internal-"`
`STRING_ENDS_WITH`	Ends with suffix	`"-v1"`
`STRING_NOT_ENDS_WITH`	Does not end with suffix	`"-deprecated"`
`IS_NULL`	`true` matches rows where the field is unset; `false` matches rows where it is set	`true`

Numeric field operators

Operator	Description	Example value
`EQUAL`	Exact match	`1000`
`NOT_EQUAL`	Not equal to value	`0`
`IN`	Match any value in the list	`[200, 404, 500]`
`NOT_IN`	Exclude values in the list	`[0]`
`GREATER_THAN`	Strictly greater than	`1000`
`LESS_THAN`	Strictly less than	`5000`
`GREATER_THAN_EQUAL`	Greater than or equal to	`100`
`LESS_THAN_EQUAL`	Less than or equal to	`1000`
`BETWEEN`	Between two values (inclusive)	`[500, 5000]`
`IS_NULL`	`true` matches rows where the field is unset; `false` matches rows where it is set	`true`

Boolean field operators

Operator	Description	Example value
`EQUAL`	Exact match	`true`
`IS_NULL`	`true` matches rows where the field is unset; `false` matches rows where it is set	`false`

Array field operators (used by `team`)

Operator	Description	Example value
`ARRAY_HAS_ANY`	Match if the array contains any of the values	`["team-alpha", "team-beta"]`
`ARRAY_HAS_NONE`	Match 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"]
}

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Models

Filtering

Filter object structure

Filterable fields

Filter operators

String field operators

Numeric field operators

Boolean field operators

Array field operators (used by `team`)

Custom metadata filtering and grouping

Implicit team unnesting

Combining multiple filters

​Filtering

​Filter object structure

​Filterable fields

​Filter operators

​String field operators

​Numeric field operators

​Boolean field operators

​Array field operators (used by team)

​Custom metadata filtering and grouping

​Implicit team unnesting

​Combining multiple filters

Filtering

Filter object structure

Filterable fields

Filter operators

String field operators

Numeric field operators

Boolean field operators

Array field operators (used by `team`)

Custom metadata filtering and grouping

Implicit team unnesting

Combining multiple filters