Overview
Type definitions for the legacy filter tree data model, defining all filter operators, per-table column-to-operator mappings, and the recursive FilterNode type used throughout Helicone's query system.
Description
This file is the type foundation for Helicone's entire filter system. It defines operator types for different column types (text, number, boolean, timestamp), then creates per-table type mappings that specify which columns can be filtered on each database table and which operators are valid for each column. The file covers both PostgreSQL tables (request, response, feedback, properties, prompts, experiments) and ClickHouse tables (request_response_rmt, sessions, users_view, properties_v3, cache_metrics, rate_limit_log, organization_properties). All these table-specific types are unified into the TablesAndViews type, and the recursive FilterNode type (leaf, branch, or "all") enables building arbitrarily complex filter trees with AND/OR combinators.
Usage
Import these types when building filter expressions for database queries. The FilterNode type is the primary interface passed to filter building functions in filters.ts. The per-table FilterLeaf types ensure type safety when constructing filters for specific tables.
Code Reference
Source Location
Signature
// Operator types
export type AllOperators = "equals" | "like" | "ilike" | "gte" | "lte" | "lt" | "gt"
| "not-equals" | "contains" | "not-contains" | "gin-contains" | "vector-contains" | "has";
export type TextOperators = Record<"not-equals" | "equals" | "like" | "ilike" | "contains" | "not-contains", string>;
export type NumberOperators = Record<"not-equals" | "equals" | "gte" | "lte" | "lt" | "gt", number>;
export type BooleanOperators = Record<"equals", boolean>;
export type TimestampOperators = Record<"equals" | "gte" | "lte" | "lt" | "gt", string>;
export type TimestampOperatorsTyped = Record<"equals" | "gte" | "lte" | "lt" | "gt", Date>;
// Filter tree types
export type FilterLeaf = SingleKey<TablesAndViews>;
export type FilterNode = FilterLeaf | FilterBranch | "all" | {};
export interface FilterBranch {
left: FilterNode;
operator: "or" | "and";
right: FilterNode;
}
// Time filter types
export interface TimeFilter { start: Date; end: Date; }
export interface TimeFilterMs { startTimeUnixMs: number; endTimeUnixMs: number; }
Import
import {
FilterNode,
FilterLeaf,
FilterBranch,
TablesAndViews,
AllOperators,
TextOperators,
NumberOperators,
TimeFilter,
} from "@helicone-package/filters/filterDefs";
Operator Types
| Operator Type |
Operators |
Value Type |
Usage
|
TextOperators |
equals, not-equals, like, ilike, contains, not-contains |
string |
String column filtering
|
NumberOperators |
equals, not-equals, gte, lte, lt, gt |
number |
Numeric comparisons
|
BooleanOperators |
equals |
boolean |
Boolean column filtering
|
TimestampOperators |
equals, gte, lte, lt, gt |
string |
Timestamp as ISO string
|
TimestampOperatorsTyped |
equals, gte, lte, lt, gt |
Date |
Timestamp as Date object
|
VectorOperators |
contains |
string |
Full-text search
|
Table Mappings
PostgreSQL Tables
| Table |
FilterLeaf Type |
Key Columns
|
request |
FilterLeafRequest |
prompt, created_at, user_id, auth_hash, org_id, id, model, path, country_code, prompt_id
|
response |
FilterLeafResponse |
body_tokens, body_model, body_completion, status, model
|
feedback |
FilterLeafFeedback |
id, created_at, rating, response_id
|
properties_table |
FilterLeafPropertiesTable |
auth_hash, key, value
|
user_metrics |
FilterLeafUserMetrics |
user_id, last_active, total_requests, active_for, cost
|
user_api_keys |
FilterLeafUserApiKeys |
api_key_hash, api_key_name
|
prompt_v2 |
FilterLeafPrompt |
id, user_defined_id
|
prompts_versions |
FilterLeafPromptVersions |
minor_version, major_version, id, prompt_v2
|
experiment |
FilterLeafExperiment |
id, prompt_v2
|
score_value |
FilterLeafScoreValue |
request_id
|
ClickHouse Tables
| Table |
FilterLeaf Type |
Key Columns
|
request_response_rmt |
FilterLeafRequestResponseRMT |
latency, status, cost, model, user_id, request_created_at, properties (map), scores (map), request_body, response_body, cached, prompt_id, and more
|
sessions_request_response_rmt |
FilterLeafSessionsRequestResponseRMT |
session_session_id, session_total_cost, session_total_tokens, session_created_at, session_tag
|
users_view |
FilterLeafUserView |
user_user_id, user_active_for, user_total_requests, user_cost
|
request_response_log |
FilterLeafRequestResponseLog |
latency, status, model, user_id, organization_id, threat
|
properties_v3 |
FilterLeafPropertiesV3 |
key, value, organization_id
|
cache_metrics |
FilterLeafCacheMetrics |
organization_id, model, cache_hit_count, saved_latency_ms, saved_completion_tokens
|
rate_limit_log |
FilterLeafRateLimitLog |
organization_id, created_at
|
organization_properties |
FilterLeafOrganizationProperties |
organization_id, property_key
|
Dynamic Filter Types
| Key |
Type |
Description
|
properties |
{ [key: string]: SingleKey<TextOperators> } |
Dynamic property key-value filtering
|
values |
{ [key: string]: SingleKey<TextOperators> } |
Dynamic value filtering
|
Filter Tree Structure
The FilterNode type enables recursive filter tree construction:
// Leaf node - filters on a single table column
const leaf: FilterLeaf = {
request_response_rmt: {
status: { equals: 200 }
}
};
// Branch node - combines two subtrees
const branch: FilterBranch = {
left: { request_response_rmt: { status: { equals: 200 } } },
operator: "and",
right: { request_response_rmt: { model: { like: "gpt-4" } } }
};
// "all" - matches everything
const matchAll: FilterNode = "all";
I/O Contract
Inputs
| Name |
Type |
Required |
Description
|
| Table name |
keyof TablesAndViews |
Yes |
The database table to filter on
|
| Column name |
varies per table |
Yes |
The column within the table
|
| Operator |
AllOperators subset |
Yes |
Comparison operator appropriate for the column type
|
| Value |
string, number, boolean, or Date |
Yes |
The value to compare against
|
Outputs
| Name |
Type |
Description
|
| FilterNode |
union type |
A filter tree node (leaf, branch, or "all") ready for SQL compilation
|
Related Pages
