Principle:Helicone Helicone Query Filtering

Knowledge Sources	Helicone
Domains	Query Construction, Data Filtering, Type Safety
Last Updated	2026-02-14 06:32 GMT

Overview

Query Filtering is a type-safe system for constructing, composing, and compiling user-defined filter expressions into SQL WHERE clauses through a structured filter tree abstraction.

Description

Observability platforms must allow users to slice data across many dimensions -- time ranges, models, providers, status codes, custom properties, scores, and more. Rather than building ad-hoc SQL string concatenation for each filter combination, the system defines a filter tree data structure: a recursive tree of AND/OR nodes whose leaves are individual filter conditions (column, operator, value). Each filterable table column is described by a filter definition that declares its name, SQL column mapping, supported operators, and value type.

The frontend constructs filter trees from UI controls, the backend validates them against filter definitions, and a compiler walks the tree to emit parameterized SQL WHERE clauses. This separation ensures that the UI, validation, and SQL generation layers remain decoupled and independently testable.

Usage

Use this pattern when:

• Building user-facing filter UIs that must map to database queries.
• Supporting complex boolean logic (AND/OR/NOT) over heterogeneous column types.
• Needing to validate filter inputs against a schema before query execution.
• Generating parameterized SQL to prevent injection attacks.

Theoretical Basis

The filter tree is an abstract syntax tree (AST) for a restricted query language. Each leaf node represents a predicate (column op value), and interior nodes represent boolean connectives (AND, OR). Compilation traverses the AST via a recursive descent strategy, emitting SQL fragments at each node and combining them with the appropriate connective. The use of discriminated union types for filter operators ensures exhaustive handling at compile time, making it impossible to forget a case.

This is an instance of the Interpreter pattern, where the filter tree grammar is defined by types, parsed from user input, and interpreted (compiled) into the target language (SQL).

Related Pages

Implemented By

• Implementation:Helicone_Helicone_FilterDefs
• Implementation:Helicone_Helicone_FilterExpressions
• Implementation:Helicone_Helicone_Filters
• Implementation:Helicone_Helicone_FrontendFilterDefs
• Implementation:Helicone_Helicone_ToFilterNode
• Implementation:Helicone_Helicone_Filter_Helpers
• Implementation:Helicone_Helicone_Filter_Types
• Implementation:Helicone_Helicone_Alert_Types