> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guardrail Metrics: Filtering

> Filter operators, fields, and patterns for Gateway guardrail metrics API queries

## 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

<Tabs>
  <Tab title="Field filters">
    For standard datasource fields, use `fieldName`:

    ```json theme={"dark"}
    {
        "fieldName": "guardrailName",
        "operator": "IN",
        "value": ["pii-detector", "toxicity-filter"]
    }
    ```
  </Tab>

  <Tab title="Metadata filters">
    For custom request-metadata keys, use `metadataKey`. Works on every datasource:

    ```json theme={"dark"}
    {
        "metadataKey": "environment",
        "operator": "IN",
        "value": ["production"]
    }
    ```
  </Tab>
</Tabs>

### Filterable fields

<Note>
  The guardrail-specific string fields (`guardrailName`, `appliedOnEntityScope`, `guardrailResult`) accept only a narrow set of string operators (`IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`). `EQUAL` and `NOT_EQUAL` are only supported on subject fields and `conversationID`.
</Note>

| Field                            | Type   | Allowed operators                                                               |
| -------------------------------- | ------ | ------------------------------------------------------------------------------- |
| `guardrailName`                  | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
| `appliedOnEntityScope`           | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
| `guardrailResult`                | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
| `userEmail`                      | string | full string operator set (no `IS_NULL`)                                         |
| `virtualAccount`                 | string | full string operator set (no `IS_NULL`)                                         |
| `team`                           | array  | `ARRAY_HAS_ANY`, `ARRAY_HAS_NONE`                                               |
| `latencyMs`                      | number | `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_EQUAL`, `LESS_THAN_EQUAL`, `BETWEEN` |
| `conversationID`                 | string | full string operator set                                                        |
| `metadataKey` / `metadata.<key>` | string | full string operator set                                                        |

### Filter operators

#### String field operators

| Operator                 | Description                                                                        | Example value                         |
| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------- |
| `EQUAL`                  | Exact match                                                                        | `"alice@example.com"`                 |
| `NOT_EQUAL`              | Not equal to value                                                                 | `"bot@example.com"`                   |
| `IN`                     | Match any value in the list                                                        | `["pii-detector", "toxicity-filter"]` |
| `NOT_IN`                 | Exclude values in the list                                                         | `["deprecated-guardrail"]`            |
| `STRING_CONTAINS`        | Contains substring                                                                 | `"pii"`                               |
| `STRING_NOT_CONTAINS`    | Does not contain substring                                                         | `"deprecated"`                        |
| `STRING_STARTS_WITH`     | Starts with prefix                                                                 | `"pii-"`                              |
| `STRING_NOT_STARTS_WITH` | Does not start with prefix                                                         | `"internal-"`                         |
| `STRING_ENDS_WITH`       | Ends with suffix                                                                   | `"-filter"`                           |
| `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                                                        | `[100, 200, 300]` |
| `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`            |

#### 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](#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:

```json theme={"dark"}
{
    "startTs": "2026-04-21T00:00:00.000Z",
    "endTs": "2026-04-22T00:00:00.000Z",
    "datasource": "guardrailMetrics",
    "type": "distribution",
    "filters": [
        {"fieldName": "appliedOnEntityScope", "operator": "IN", "value": ["input"]},
        {"fieldName": "guardrailResult", "operator": "IN", "value": ["fail", "error"]},
        {"fieldName": "latencyMs", "operator": "LESS_THAN", "value": 1000},
        {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
    ],
    "groupBy": ["guardrailName", "guardrailResult"]
}
```