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

# Custom and Saved Filters for GenAI Charts

> Filter GenAI charts with custom FQL expressions, save them to the filter library, and reuse them across charts and projects.

> [!NOTE]
>
> This capability is currently in [public preview](https://docs.fiddler.ai/reference/feature-maturity-definitions.md#public-preview). It is available to every customer and Fiddler responds promptly to issues, but it is not yet covered by an SLA and its APIs may still change.

## Overview

GenAI charts come with built-in filters such as **Agent Name**, **Span Type**, **Latency**, **Token Count**, **Attribute**, and **Evaluator**.
When you need a condition those filters can't express,
write a **custom filter**:
a boolean expression in [Fiddler Query Language (FQL)](https://docs.fiddler.ai/observability/platform/fiddler-query-language.md) that each span must match.

A custom filter you don't save is an **inline filter**:
it's stored with the chart and applies only to that chart.
Save a custom filter to the **filter library** to reuse it on other charts.
A chart stores a link to the saved filter rather than a copy,
so every chart that uses it applies the same definition.

Custom filters, inline or saved, apply to GenAI charts only.
They aren't available in [Explorer](https://docs.fiddler.ai/observability/agentic/trace-explorer.md) yet.

## Add a Custom Filter to a Chart

1. Open a GenAI chart and add a filter to a query.
2. Select **Custom Filter**.
   The picker lists the saved filters you can apply to this chart.
3. Do one of the following:
   * Select a saved filter to apply it.
     The editor shows its definition and description.
   * Select **New Custom Filter** and write an FQL expression in the editor.
     Then either:
     * Apply it to this chart only, as an inline filter.
     * [Save it](#save-a-custom-filter) to the filter library to reuse it in your project or organization.
4. Save the chart.

Each query's filters are saved with the chart and restored when it reopens.
A query keeps either its built-in filters or its custom filter,
and a custom filter can be inline (stored only with this chart) or saved in the filter library.

> [!NOTE]
>
> A query uses either any number of built-in filters or a single custom filter, inline or saved, not both.
> Adding a custom filter to a query removes its built-in filters,
> and adding a built-in filter removes its custom filter.
> To combine conditions, write them all in one custom filter.

Editing the definition of a saved filter you applied turns it into an inline filter:
the chart stops following the saved filter.
You can save the edited expression to the library as a new filter, or keep it for this chart only.

## Save a Custom Filter

To save an inline filter to the filter library, select **Save Filter** in the custom filter editor.
In the **Create Saved Filter** dialog:

1. Enter a **Filter Name** and an optional description.
2. Under **Access & Permissions**, choose who can use the filter:
   * **Project Level** (the default) — available only to charts in this chart's project.
   * **Global (Organization)** — available to charts in every project of the organization.
3. Review the **Filter Definition** and select **Create Filter**.

The chart's query now applies the new saved filter.

The custom filter picker on a chart lists the saved filters from the chart's project and the organization-wide saved filters.

## Manage the Filter Library

Select **Saved Filters** in the sidebar,
or **Manage filters** in the custom filter picker,
to open the filter library.
From the library you can:

* **Search** saved filters.
* **Add Saved Filter** — create a filter from scratch, for the organization or a project you choose.
* **Duplicate** — copy an existing filter as a starting point for a new one.
* **Delete** — remove a filter permanently.

Saved filters can't be edited in place.
To change a definition, duplicate the filter, edit the copy, and switch your charts to it.

> [!WARNING]
>
> Deleting a saved filter can't be undone.
> Every chart query that uses the filter is removed,
> a chart left with no queries is deleted from its dashboards,
> and a dashboard left with no charts is deleted.

### Permissions

Saved filters share permissions with agentic custom metrics.
See the **Global Agentic Custom Metrics and Saved Filters** and **Project-Scoped Agentic Custom Metrics and Saved Filters** rows in [Role-Based Access](https://docs.fiddler.ai/reference/access-control/role-based-access.md).

* **Global (Organization)** filters are created with an organization role.
* **Project Level** filters are created with a role on that project;
  an organization role alone isn't enough, except for Org Admins when [Org Admin access to all projects](https://docs.fiddler.ai/reference/access-control/role-based-access.md#org-admin-access-to-all-projects) is turned on.
* You see project filters only for projects where you have a role, with the same Org Admin exception.

## Filter Syntax

A filter is an FQL expression that evaluates to `true` or `false` for each span.
It references span data with four functions:

| Function | References | Example |
| - | - | - |
| `attribute()` | A span or resource attribute, by key or semantic name | `attribute('environment') == 'production'` |
| `span()` | A built-in span field, by `name` | `span(name='span_type') == 'llm'` |
| `evaluator()` | An evaluator output, by evaluator rule `name` and `output` | `evaluator(name='Safety', output='Is Toxic') == true` |
| `annotation()` | An annotation score, by score `name` and `source` (default `human`) | `annotation(name='helpfulness') >= 4` |

`attribute()` takes the same arguments as in [custom metrics](https://docs.fiddler.ai/observability/agentic/custom-metrics.md#the-attribute-function).

`span()` accepts these field names:
`span_id`, `trace_id`, `parent_span_id`, `session_id`, `span_name`, `span_type`, `status_code`, `status_message`, `duration`, `agent_id`, and `agent_name`.
`duration` is in nanoseconds:
`span(name='duration') > 2000000000` matches spans longer than 2 seconds.
To filter on latency alone, the built-in **Latency** filter lets you choose the unit instead.

`annotation()` reads an [annotation](https://docs.fiddler.ai/observability/agentic/annotations.md) score.
`source` is `human` (the default), `llm`, or `code`.
Compare a numeric score with a number, a thumbs-up style score with `true` or `false`,
and a categorical or text score with a string:

```text theme={null}
annotation(name='helpfulness') >= 4
annotation(name='thumbs_up', source='human') == true
annotation(name='topic', source='llm') == 'billing'
```

### Operators and Functions

* Comparisons: `==`, `!=`, `<`, `<=`, `>`, `>=`
* Membership: `in(attribute('model'), 'gpt-4o', 'gpt-4o-mini')`, `not_in(...)`
* Missing values: `is_null(...)`, `is_not_null(...)`
* Logic: `and`, `or`, `not(...)`
* Arithmetic and row functions, such as `+`, `-`, `*`, `/`, `abs()`, `length()`, and `substring()`

Aggregate functions such as `average()` or `count()` are not allowed, because a filter is evaluated on each span.
`if()`, `to_string()`, `greatest()`, and `least()` are also not allowed.

### Combining Conditions

Each condition reads exactly one field:
one attribute, one evaluator output, one annotation score (per `source`),
or the built-in span fields, which all count as one field because they are columns of the same span.

* Conditions on the **same** field can be combined with `and`, `or`, and `not(...)`.
* Conditions on **different** fields can be combined only with a top-level `and`.

```text theme={null}
# Valid: conditions on different fields joined by a top-level `and`
span(name='span_type') == 'llm' and evaluator(name='Safety', output='Is Toxic') == true

# Valid: `or` on the same attribute
attribute('environment') == 'production' or attribute('environment') == 'staging'

# Valid: `or` across built-in span fields, which count as one field
span(name='span_type') == 'llm' or span(name='agent_name') == 'support-agent'

# Valid: arithmetic on a single field
attribute('cost') * 1000 > 5

# Not valid: `or` across different fields
span(name='span_type') == 'llm' or attribute('environment') == 'production'
attribute('cost_usd') > 0 or attribute('gen_ai.usage.total_tokens') > 0
evaluator(name='Safety', output='Is Toxic') == true or annotation(name='helpfulness') <= 1

# Not valid: `not` around conditions on different fields
not(span(name='span_type') == 'llm' and attribute('environment') == 'production')

# Not valid: one condition reading multiple fields
attribute('output_tokens') > attribute('input_tokens')
attribute('input_tokens') + attribute('output_tokens') > 5000
```

### Limitations

* **One field per condition.**
  A condition can't compare two fields or combine them with arithmetic,
  and conditions on different fields combine only with a top-level `and`.
  Only the built-in span fields can be combined with `or` across fields;
  two different attributes, evaluator outputs, or annotation scores can't.
* **Compare every field explicitly.**
  Write `evaluator(name='Safety', output='Is Toxic') == true`, not `evaluator(name='Safety', output='Is Toxic')`.
  Every condition must reference a field, so `... or true` isn't valid.
* **Missing values.**
  `is_null()` and `is_not_null()` don't work on `attribute()`,
  because a span that lacks an attribute has no value to test.
  `is_null()` on `annotation()` is accepted but matches no spans.
  `!=` and `not_in()` on an attribute don't match spans that lack the attribute.
* **No time fields.**
  Span start and end times aren't available in `span()`; use the chart's time range instead.
* **One custom filter per query.**
  A query can have several built-in filters or a single custom filter, but not both,
  and it can't apply two custom filters at once, whether inline or saved.
  To combine conditions, write them all in one expression;
  copying a saved filter's definition into a new expression makes it an inline filter, which no longer follows the saved filter.
* **Saved filters can't be edited.**
  Duplicate the filter, edit the copy, and switch your charts to it.

Fiddler checks the expression's shape when you save it and rejects shapes it can't run.
It checks the attributes, evaluators, and annotation scores you reference only when a chart runs the filter:
a chart whose filter names one that doesn't exist in the application shows an error instead of data.

### Examples

Production LLM spans:

```text theme={null}
span(name='span_type') == 'llm' and attribute('environment') == 'production'
```

Spans flagged as toxic by the `Safety` evaluator:

```text theme={null}
evaluator(name='Safety', output='Is Toxic') == true
```

Spans with a low quality score from a specific agent:

```text theme={null}
evaluator(name='Quality', output='Score') < 0.5 and span(name='agent_name') == 'support-agent'
```

Spans with more than 1,000 input tokens:

```text theme={null}
attribute(semantic_name='input_tokens') > 1000
```

## Manage Saved Filters with the API

The [GenAI Filters REST API](https://docs.fiddler.ai/sdk-api/rest-api/genai-filters) lists, creates, reads, and deletes saved filters.

## Related Resources

* [Fiddler Query Language (FQL)](https://docs.fiddler.ai/observability/platform/fiddler-query-language.md) — operators and functions shared by filters and custom metrics
* [Custom Metrics for Agentic Applications](https://docs.fiddler.ai/observability/agentic/custom-metrics.md) — the `attribute()` function and semantic names
* [Explorer](https://docs.fiddler.ai/observability/agentic/trace-explorer.md) — filter individual traces and spans
* [Agentic Observability](https://docs.fiddler.ai/observability/agentic/index.md) — overview of dashboards, metrics, and integrations
