Implementation:Helicone Helicone Filter Helpers

Knowledge Sources	Helicone
Domains	Filtering, Data Transformation
Last Updated	2026-02-14 06:32 GMT

Overview

Utility functions that convert between the frontend UI filter tree representation and the backend's legacy FilterNode tree structure used for database query compilation.

Description

This module serves as the bridge between the frontend's filter UI state and the backend's SQL filter compilation. It provides a comprehensive set of functions for transforming user-created filter configurations into query-ready filter trees.

Key capabilities include:

• Time filter conversion -- timeFilterToFilterNode converts a TimeFilter (start/end dates) into a FilterNode for a specified table (request_response_rmt, property_with_response_v1, or rate_limit_log), using the appropriate column names for each table.
• Filter list aggregation -- filterListToTree recursively builds a binary filter tree from an array of FilterNode items combined with a logical operator ("and" or "or").
• Type guards -- isFilterRowNode and isUIFilterRow provide runtime discrimination between tree nodes and leaf rows.
• UI-to-leaf conversion -- uiFilterRowToFilterLeaf maps a single UIFilterRow to a FilterLeaf, with special-case handling for custom properties, feedback scores (mapping boolean to "1"/"0"), and AI Gateway flags (mapping boolean to request_referrer values).
• Tree traversal -- filterUITreeToFilterNode recursively converts an entire UIFilterRowTree into a FilterNode, and uiFilterRowTreeToFilterLeafArray flattens a tree into an array of FilterLeaf objects.

The module also exports a Zod schema (TimeFilterSchema) for validating and parsing time filter inputs with automatic datetime string-to-Date transformation.

Usage

Use these helpers whenever filter UI state needs to be converted to backend query filters. The primary entry points are filterUITreeToFilterNode for converting the full UI tree and timeFilterToFilterNode for adding time range constraints. Use getRootFilterNode to initialize an empty filter tree.

Code Reference

Source Location

• Repository: Helicone
• File: packages/filters/helpers.ts

Signature

export const TimeFilterSchema: z.ZodObject<...>;

export function timeFilterToFilterNode(
  filter: TimeFilter,
  table: keyof TablesAndViews
): FilterNode;

export function filterListToTree(
  list: FilterNode[],
  operator: "or" | "and"
): FilterNode;

export function isFilterRowNode(filter: UIFilterRowTree): filter is UIFilterRowNode;
export function isUIFilterRow(filter: UIFilterRowTree): filter is UIFilterRow;
export const getRootFilterNode: () => UIFilterRowNode;

export function uiFilterRowToFilterLeaf(
  filterMap: SingleFilterDef<any>[],
  filter: UIFilterRow
): FilterLeaf;

export function filterUITreeToFilterNode(
  filterMap: SingleFilterDef<any>[],
  uiFilterRowNode: UIFilterRowTree
): FilterNode;

export function filterUIToFilterLeafs(
  filterMap: SingleFilterDef<any>[],
  filters: UIFilterRow[]
): FilterLeaf[];

export function uiFilterRowTreeToFilterLeafArray(
  filterMap: SingleFilterDef<any>[],
  tree: UIFilterRowTree
): FilterLeaf[];

Import

import {
  timeFilterToFilterNode,
  filterListToTree,
  filterUITreeToFilterNode,
  getRootFilterNode,
  uiFilterRowToFilterLeaf,
} from "@helicone/filters/helpers";

I/O Contract

timeFilterToFilterNode

Parameter	Type	Description
filter	TimeFilter	Object with start and end Date properties
table	keyof TablesAndViews	Target table name (request_response_rmt, property_with_response_v1, or rate_limit_log)

Returns	Description
FilterNode	An AND-combined filter node with gte/lte constraints on the date column

filterListToTree

Parameter	Type	Description
list	FilterNode[]	Array of filter nodes to combine
operator	"and"	Logical operator to combine with

Returns	Description
FilterNode	A recursively-built binary tree, or "all" if the list is empty

uiFilterRowToFilterLeaf

Parameter	Type	Description
filterMap	SingleFilterDef<any>[]	Array of filter definitions from the frontend
filter	UIFilterRow	A single UI filter row with indices and value

Returns	Description
FilterLeaf	A filter leaf with special handling for custom properties, feedback scores, and AI Gateway flags

Usage Examples

import {
  timeFilterToFilterNode,
  filterListToTree,
  filterUITreeToFilterNode,
  getRootFilterNode,
} from "@helicone/filters/helpers";

// Build a time-range filter for the main request table
const timeFilter = timeFilterToFilterNode(
  { start: new Date("2025-01-01"), end: new Date("2025-01-31") },
  "request_response_rmt"
);

// Combine multiple filters with AND
const combined = filterListToTree([timeFilter, otherFilter], "and");

// Convert an entire UI filter tree to a FilterNode
const filterNode = filterUITreeToFilterNode(filterMap, uiTree);

// Initialize an empty root filter node
const root = getRootFilterNode();
// root = { operator: "and", rows: [] }

Related Pages

• Principle:Helicone_Helicone_Query_Filtering
• Helicone_Helicone_Filter_Types
• Helicone_Helicone_Alert_Types