Implementation:Langfuse Langfuse Table Filter Schema Definitions

Knowledge Sources	Langfuse
Domains	Filtering, Zod Schemas, Query Building
Last Updated	2026-02-14 00:00 GMT

Overview

Defines the complete set of Zod filter schemas and operator mappings used across the Langfuse platform for constructing type-safe filter conditions on table data in both PostgreSQL and ClickHouse queries.

Description

This module is the central definition for the filtering system in Langfuse. It exports:

Operator Mappings (filterOperators): A constant object mapping each filter type to its allowed operators:

• datetime: >, <, >=, <=
• string: =, contains, does not contain, starts with, ends with
• stringOptions: any of, none of
• categoryOptions: any of, none of
• arrayOptions: any of, none of, all of
• number: =, >, <, >=, <=
• stringObject / numberObject: Same as string/number but for JSON object key access
• boolean: =, <>
• null: is null, is not null
• positionInTrace: =

Individual Filter Schemas: Eleven Zod schemas, each validating a specific filter type with column, operator, value, and type fields:

• timeFilter, stringFilter, numberFilter, stringOptionsFilter, arrayOptionsFilter (with refinement that empty arrays require all of operator), stringObjectFilter (adds key field), numberObjectFilter (adds key field), booleanFilter, nullFilter, positionInTraceFilter (with superRefine for nth position validation), and categoryOptionsFilter (adds key field).

Union Schema (singleFilter): A Zod discriminated union on the type field that combines all eleven filter schemas into a single validated filter type.

Usage

Use these schemas and types throughout the application wherever filters are constructed, validated, or consumed. The singleFilter schema is the primary type used in API query parameters, tRPC inputs, and filter-to-SQL conversion functions. The filterOperators constant is used by UI components to render available operators per column type.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/interfaces/filters.ts
• Lines: 1-123

Signature

export const filterOperators: {
  datetime: readonly [">", "<", ">=", "<="];
  string: readonly ["=", "contains", "does not contain", "starts with", "ends with"];
  stringOptions: readonly ["any of", "none of"];
  categoryOptions: readonly ["any of", "none of"];
  arrayOptions: readonly ["any of", "none of", "all of"];
  number: readonly ["=", ">", "<", ">=", "<="];
  stringObject: readonly ["=", "contains", "does not contain", "starts with", "ends with"];
  numberObject: readonly ["=", ">", "<", ">=", "<="];
  boolean: readonly ["=", "<>"];
  null: readonly ["is null", "is not null"];
  positionInTrace: readonly ["="];
};

export const timeFilter: z.ZodObject<...>;
export const stringFilter: z.ZodObject<...>;
export const numberFilter: z.ZodObject<...>;
export const stringOptionsFilter: z.ZodObject<...>;
export const arrayOptionsFilter: z.ZodEffects<...>;
export const stringObjectFilter: z.ZodObject<...>;
export const numberObjectFilter: z.ZodObject<...>;
export const booleanFilter: z.ZodObject<...>;
export const nullFilter: z.ZodObject<...>;
export const positionInTraceFilter: z.ZodEffects<...>;
export const categoryOptionsFilter: z.ZodObject<...>;
export const singleFilter: z.ZodDiscriminatedUnion<...>;

Import

import {
  filterOperators,
  singleFilter,
  timeFilter,
  stringFilter,
  numberFilter,
} from "@langfuse/shared/src/interfaces/filters";

I/O Contract

Inputs

Name	Type	Required	Description
column	string	Yes	The name or ID of the column to filter on.
operator	string	Yes	The comparison operator (must be one of the allowed operators for the filter type).
value	varies	Yes	The filter value: Date for datetime, string for string, number for number, string[] for options, boolean for boolean, "" for null.
type	string	Yes	The discriminator field identifying the filter type.
key	string	No	JSON object key for stringObject, numberObject, and categoryOptions filter types.

Outputs

Name	Type	Description
singleFilter parse result	Discriminated union type	A validated filter object with the correct types for its specific filter kind.

Usage Examples

import { singleFilter, filterOperators } from "@langfuse/shared/src/interfaces/filters";

// Validate a datetime filter
const filter = singleFilter.parse({
  column: "startTime",
  operator: ">=",
  value: new Date("2024-01-01"),
  type: "datetime",
});

// Validate a string options filter
const optionsFilter = singleFilter.parse({
  column: "name",
  operator: "any of",
  value: ["chat-completion", "embedding"],
  type: "stringOptions",
});

// Get available operators for a filter type
const stringOps = filterOperators.string;
// => ["=", "contains", "does not contain", "starts with", "ends with"]