API reference

Everything on this page is exported from the root entry point (@maple-dev/effect-clickhouse) unless marked otherwise.

Naming conventions

Some ClickHouse functions collide with JavaScript reserved words or globals. The source defines those with a trailing underscore, and the root barrel drops it: min_, max_, any_, toString_, length_, left_, extract_, least_, greatest_, position_, lower_, round_, path_ and domain_ are all exported from the root under their bare names.

One exception, because it cannot be anything else:

Importing the kitchen-sink namespace (import * as CH from "@maple-dev/effect-clickhouse/expr") gives you the raw underscored names uniformly, which some codebases prefer for exactly this reason.

What's only on a subpath

The root barrel is curated. These are exported by the package but not from it:

Every column-type constructor and every expression helper is on the root as well as on its subpath. See Running a query for what the /sql statement helpers are for. See Benchmarking for the complete benchmark API, command workflow, result verification, and JSON protocol.

Note /sql exports a compile (fragment → string) distinct from the root compile (query → CompiledQuery), and a when distinct from the root when (optional conditions).

Entry points

Query construction

CHQuery methods

CHUnionQuery offers only orderBy, limit, offset, format.

Compilation

Params

param.string(name), param.int(name), param.float(name), param.bool(name), param.dateTime(name), param.dateTimeString(name), param.dateTimeSeconds(name), and param.of(type, name) for any column type. Each checks the value it is handed at compile time; see Params and compilation.

Expressions

Expr<T> methods: eq, neq, gt, gte, lt, lte, in_, notIn, like, notLike, ilike (string-only), and add, sub, mul, div, mod (number-only, no parentheses). div and mod decode as number | null — ClickHouse sends inf/nan as JSON null — except by a numeric literal of magnitude ≥ 1 (Quotient<L, R>), which keeps the dividend's nullability; use ifNull(ifNotFinite(expr, 0), lit(0)) for a guaranteed number otherwise.

Spliced sub-SELECTs

For SQL the builder has no syntax for — an inner query's text inside an aggregate or a tuple comparison. The inner query is compiled by the outer compile, so its params resolve from the outer set and its failures land in the outer error channel. See Joins and subqueries.

wrap receives the inner SQL and returns the text to emit. It defaults to wrapping the SQL in parentheses, which is the plain "this value is a sub-SELECT" case.

Condition methods: and, or (both parenthesise; both drop the tenant marker).

ColumnRef adds .get(key) for Map columns; the result decodes as the map's value type.

Extensibility

ClickHouse functions

Aggregate

count(), countIf(cond), avg(e), sum(e), min(e), max(e), any(e), uniq(e), sumIf(e, cond), avgIf(e, cond), minIf(e, cond), maxIf(e, cond), anyIf(e, cond), groupUniqArray(e), groupUniqArrayIf(e, cond), groupUniqArrayArray(e), uniqIf(e, cond), uniqExact(e), argMin(value, order), argMax(value, order), argMaxMerge(e), quantile(q)(e) (curried), windowFunnel(window, mode?)(ts, ...conds) and sequenceMatch(pattern)(ts, ...conds) (both curried; WindowFunnelMode is the mode union).

min/max return Expr<NonNullable<T>>; groupUniqArray returns Expr<ReadonlyArray<T>>.

String

toString(e), length(e), lower(e), hex(e), match(e, pattern), matchCond(e, pattern) → Condition, domain(url), path(url), cutQueryString(url), position(haystack, needle), positionCaseInsensitive(a, b), left(e, n), extract(e, pattern), replaceOne(haystack, pattern, replacement), concat(...exprs), hasToken(haystack, token), hasAllTokens(haystack, tokens).

hasToken and hasAllTokens return Condition.

Numeric

toFloat64(e), toFloat64OrZero(e), toUInt16OrZero(e), toUInt64(e), toInt64(e), intDiv(a, b), round(e, decimals?), least(...exprs), greatest(...exprs), cityHash64(...exprs).

Date/time

toStartOfInterval(col, seconds), toStartOfHour(col), toUnixTimestamp(col), toUnixTimestamp64Nano(col), intervalSub(col, seconds), intervalAdd(col, seconds), formatDateTime(col, format), toDateTime(col), toStartOfMinute(col), toHour(col).

Conditional

if_(cond, then, else), multiIf([[cond, value], …], fallback), coalesce(...exprs), nullIf(expr, value), ifNotFinite(expr, fallback) (expr unless it is nan/inf — the SQL-side guard for division; preserves SQL NULL). nullIf returns Expr<T | null>. avg, avgIf, and quantile return Expr<number | null> for empty input.

Array

arrayOf(...exprs), arrayStringConcat(arr, sep), arrayFilter(fn, arr), arrayJoin(arr), arraySort(arr), arrayReverseSort(arr), arrayDistinct(arr), arrayPushFront(arr, value), arrayElement(arr, index), has(arr, value) → Condition.

Map

mapContains(map, key) → Condition, mapGet(map, key), mapKeys(map), mapValues(map), mapLiteral(...[key, expr]). Prefer $.Column.get(key) for a declared Map column.

JSON

toJSONString(e).

Window

over(expr, spec), windowSpec({ partitionBy?, orderBy?, frame? }), rowsBetween(start, end), lagInFrame(expr, offset, defaultValue) (all three arguments required), and the frame bounds currentRow, unboundedPreceding, unboundedFollowing, preceding(n), following(n).

CH.over(
	CH.lagInFrame($.DurationMs, 1, 0),
	CH.windowSpec({
		partitionBy: [$.Name],
		orderBy: [[$.Timestamp, "asc"]],
		frame: CH.rowsBetween(CH.unboundedPreceding, CH.currentRow),
	}),
)

Types: WindowSpec, CompiledWindowSpec, WindowFrameBound, WindowRowsFrame, WindowOrderDirection.

Types

Column-type constructors — string, bool, uint8, uint16, uint32, uint64, int32, int64, float64, dateTime, dateTime64, dateTimeString, dateTime64String, map, array, nullable, aggregateState(fn, ...args), custom(sql, schema, literalSchema?), and untyped(sql) for a wire value passed through unvalidated. See Tables and column types.

Type descriptors — CHType, CHString, CHBool, CHUInt8, CHUInt16, CHUInt32, CHUInt64, CHInt32, CHInt64, CHFloat64, CHDateTime, CHDateTime64, CHDateTimeString, CHDateTime64String, CHMap, CHArray, CHNullable.

Inference — InferTS (the decoded type of a column), InferEncoded (its wire type), InferOutput, InferQueryOutput, InferUnionOutput, OutputToColumnDefs, NullableColumnDefs, ColumnDefs.

Everything else — Table, TableOptions, Expr, ColumnRef, Condition, Comparable (what a value of a type may be compared against), MapValueOf, Subquery, ParamMarker, ParamKind, CHQuery, CHUnionQuery, ColumnAccessor, JoinedColumnAccessor, JoinOnCallback, CompiledQuery, CompiledQueryInput, CompiledQueryRowSchema, RowSchemaMismatch, TenantScope, FnResult, WindowFunnelMode, WindowSpec, WindowRowsFrame, WindowFrameBound, WindowOrderDirection, CompiledWindowSpec.

Errors

These errors are Effect Schema.TaggedError classes. Expected failures can be caught by their full namespaced tag; QueryBuilderDefect remains a defect rather than a typed failure.

QueryBuilderError

Tag "@maple-dev/effect-clickhouse/QueryBuilderError". Raised while compiling, and surfaced in compile's error channel (thrown by compileUnsafe).

QueryBuilderDefect

Tag "@maple-dev/effect-clickhouse/QueryBuilderDefect". A DSL misuse no runtime value can cause — a query with no select(), an orderBy entry that is not a tuple, a bad param name, a comparison called on a param marker. Always a defect: compile maps only QueryBuilderError into the error channel. See Failures and defects.

CompiledQueryEncodeError

Tag "@maple-dev/effect-clickhouse/CompiledQueryEncodeError". Fails the encodeRows Effect when a decoded row cannot be written back to its wire shape. Fields: message, rowIndex, cause.

CompiledQueryDecodeError

Tag "@maple-dev/effect-clickhouse/CompiledQueryDecodeError". Fails the decodeRows / decodeFirstRow Effect. Fields: message, rowIndex, cause.