Implementation:Langfuse Langfuse ClickHouse OrderBy Factory

Knowledge Sources	Langfuse
Domains	Query Building, ClickHouse, Sorting
Last Updated	2026-02-14 00:00 GMT

Overview

Factory module that converts frontend OrderByState into validated ClickHouse ORDER BY SQL clauses or structured OrderByEntry arrays.

Description

The ClickHouse OrderBy Factory provides two functions for transforming the UI sorting state into ClickHouse-compatible ORDER BY representations:

• orderByToClickhouseSql: Produces a raw SQL ORDER BY ... string. It supports an optional usedInAggregation flag that wraps columns in anyLast() for use in aggregated queries.
• orderByToEntries: Produces a structured array of OrderByEntry objects (with column and direction properties) for use with the BaseEventsQueryBuilder.

Both functions validate the column name against the provided UiColumnMappings whitelist and validate the direction with a Zod enum restricted to "ASC" or "DESC", throwing errors for invalid input. They handle both single OrderByState values and arrays, filtering out null entries.

Usage

Use orderByToClickhouseSql when constructing raw ClickHouse SQL queries that need an ORDER BY clause. Use orderByToEntries when working with the BaseEventsQueryBuilder which accepts structured order-by entries.

Code Reference

Source Location

• Repository: Langfuse
• File: packages/shared/src/server/queries/clickhouse-sql/orderby-factory.ts
• Lines: 1-110

Signature

export function orderByToClickhouseSql(
  orderBy?: OrderByState | OrderByState[],
  tableColumns: UiColumnMappings,
  usedInAggregation?: boolean,
): string;

export function orderByToEntries(
  orderBy?: OrderByState | OrderByState[],
  tableColumns: UiColumnMappings,
): OrderByEntry[];

Import

import {
  orderByToClickhouseSql,
  orderByToEntries,
} from "@langfuse/shared/src/server/queries/clickhouse-sql/orderby-factory";

I/O Contract

Inputs

Name	Type	Required	Description
orderBy	OrderByState[]	No	Frontend sorting state; can be a single value, an array, null, or undefined
tableColumns	UiColumnMappings	Yes	Whitelist of valid UI-to-ClickHouse column mappings
usedInAggregation	boolean	No	When true, wraps columns in anyLast() for aggregated queries (only for orderByToClickhouseSql)

Outputs

orderByToClickhouseSql

Name	Type	Description
(return)	string	A complete ORDER BY col1 ASC, col2 DESC SQL clause, or empty string if no valid orderBy provided

orderByToEntries

Name	Type	Description
(return)	OrderByEntry[]	"DESC" } objects

Usage Examples

import { orderByToClickhouseSql, orderByToEntries } from "./orderby-factory";
import { tracesTableUiColumnDefinitions } from "../../../tableDefinitions";

// Generate SQL ORDER BY clause
const orderBySql = orderByToClickhouseSql(
  { column: "timestamp", order: "DESC" },
  tracesTableUiColumnDefinitions,
);
// Result: "ORDER BY t.timestamp DESC"

// Generate structured entries for query builder
const entries = orderByToEntries(
  [{ column: "timestamp", order: "DESC" }, { column: "name", order: "ASC" }],
  tracesTableUiColumnDefinitions,
);
// Result: [{ column: "t.timestamp", direction: "DESC" }, { column: "t.name", direction: "ASC" }]

Related Pages

• Environment:Langfuse_Langfuse_ClickHouse_Analytics