Trace Filter DSL#

Phoenix's Trace Filter DSL lets callers pass a Python-like filter string (e.g., "status_code == 'ERROR' and latency_ms > 1000") that is compiled into a SQLAlchemy WHERE clause at runtime. The entire implementation lives in src/phoenix/trace/dsl/filter.py.

Entry Point: SpanFilter#

SpanFilter is a frozen dataclass that drives the full compilation pipeline.

Construction (__post_init__):

1. Parses the raw condition string with ast.parse(source, mode="eval") 1.
2. Calls _validate_expression for structural and light semantic checks 2.
3. Rewrites eval references (e.g., evals["Q&A"].score) into unique column aliases via _apply_eval_aliasing 3.
4. Re-parses the rewritten source and runs it through _FilterTranslator, an ast.NodeTransformer, to produce a new AST 4.
5. Calls ast.fix_missing_locations and compile(…, mode="eval") to produce an executable code object 5.

Application (__call__):
Calls eval(self.compiled, namespace) where the namespace contains the SQLAlchemy column expressions (_NAMES) and SQLAlchemy helpers (not_, and_, or_, cast, TextContains, etc.) 6. The result is passed directly to .where(…) on a SQLAlchemy Select.

AST Transformation Pipeline#

The transformation is performed by two ast.NodeTransformer subclasses 7:

• _ProjectionTranslator — base class; handles Name, Attribute, and Subscript nodes, converting bare names and dotted paths into attributes[["key"]] subscript calls. It also applies backward-compatibility renames (e.g., context.span_id → span_id) via _BACKWARD_COMPATIBILITY_REPLACEMENTS 8.
• _FilterTranslator — extends _ProjectionTranslator with comparison-aware transforms:
  • visit_Compare — resolves type mismatches between sides of a comparison by injecting cast(…, Float) or cast(…, String) calls. For In/NotIn against a column it emits TextContains; against a list it emits .in_() / .not_in() 9.
  • visit_BoolOp — rewrites and / or into and_(…) / or_(…) SQLAlchemy calls 10.
  • visit_UnaryOp — rewrites not into not_(…) 11.
  • visit_BinOp — propagates float/string types across arithmetic operators 12.
  • visit_Call — allows only str(), float(), and int() type-cast calls 13.

Type inference is done by a family of _is_float / _is_string helpers that inspect the AST node 14. attributes["key"] subscripts default to String unless one side of the comparison is already known to be a float, at which point they are wrapped with .as_float() / .as_string() 15. A special _FLOAT_ATTRIBUTES set marks llm.token_count.* fields as floats to avoid an extra cast on PostgreSQL 16.

The Projector class exposes the same pipeline for single-expression projection (e.g., building an ORDER BY column) without the comparison logic 17.

Attribute Name Mapping#

The DSL recognises a fixed set of top-level names and maps them directly to SQLAlchemy column expressions 18:

Any name not in _NAMES is treated as an attribute key path. Dotted access (attributes.llm.model_name) and bracket notation (attributes["llm.model_name"]) are both supported and normalised to a subscript list 19. metadata["key"] access is also supported with the "metadata" prefix prepended to the key list 20.

Eval / Annotation Filters#

Expressions like evals["Hallucination"].score > 0.5 or annotations["Q&A"].label == "correct" are handled by a pre-processing step before the main AST transformation 21.

_apply_eval_aliasing 21 scans the raw filter string using two regex patterns:

• EVAL_EXPRESSION_PATTERN — matches (annotations|evals)[<name>].(label|score) 22.
• EVAL_NAME_PATTERN — matches bare evals[<name>] references (existence check) 23.

Each unique eval name gets an AliasedAnnotationRelation, which aliases the span_annotations SQL table under a deterministic name like span_annotation_0. The label, score, and existence columns each get a UUID-suffixed alias. The filter string is rewritten so evals["Hallucination"].score becomes a bare Python identifier like span_annotation_0_score_<uuid>.

After compilation, SpanFilter.__call__ adds an OUTER JOIN to the statement for every aliased annotation relation 24.

Status Code & Enum Handling#

In the DSL: status_code is treated as a plain string column 25. Filter expressions must use uppercase values — status_code == 'ERROR', status_code == 'OK', status_code == 'UNSET' — because the database stores the column in uppercase and enforces this via a CHECK constraint 26.

At the schema level: SpanStatusCode implements _missing_ so that SpanStatusCode("ok") resolves to SpanStatusCode.OK. The same pattern is used by SpanKind. This case-insensitivity only applies when constructing the Python enum, not inside filter strings evaluated against the DB.

At ingestion: Inbound status_code strings are explicitly .upper()-ed before enum construction to handle lowercase API input, providing a normalisation layer upstream of the filter.

Implication for filter authors: Write filter conditions with uppercase enum strings ('ERROR', 'OK', 'UNSET'). There is no implicit case folding in the DSL itself.

Validation & Error Reporting#

_validate_expression walks every AST node in the parsed expression and raises SyntaxError for:

• Node types outside an allowlist (BoolOp, Compare, BinOp, Constant, Name, Attribute, Subscript, UnaryOp, List, Tuple, limited Calls) 27.
• Unknown eval names — if valid_eval_names is provided, the validator suggests the closest match using SequenceMatcher (ratio threshold 0.75) 28.
• Invalid eval attributes (e.g., .label vs .scor) with a similar fuzzy-match suggestion 29.

The valid_eval_names sequence is optional; if omitted, any eval name is accepted.