# ck-orm

> A typed ClickHouse query layer for modern JavaScript runtimes. This reference covers version 0.0.32.

Before version 0.1.0, there will be significant API adjustments. If needed, please pin the version number.

It gives you:

- a schema DSL for ClickHouse tables and columns
- a typed query builder for the common path
- raw SQL when ClickHouse-specific syntax is the better tool
- session helpers for temporary-table workflows
- observability through a logger and query lifecycle plugins, with OpenTelemetry tracing in `ck-orm/otel`

The design goal is straightforward: make everyday ClickHouse access easier to structure without hiding the parts that make ClickHouse different.

Use `ck-orm` with these boundaries in mind:

- `ckType.*` defines schema column types
- `ckTable(...)` defines table schemas
- `ck.*` is the query-helper namespace
- `fn.*` is the SQL function-helper namespace
- schema describes tables and columns, not the database name
- the database connection lives on `clickhouseClient(...)`
- builder queries are the default path, with raw SQL available for ClickHouse-specific expressions
- `runInSession()` is a ClickHouse session helper, not a transaction
- `plugins` observe every request ck-orm sends; tracing is the opt-in `ck-orm/otel` plugin, kept out of the main entry
- `leftJoin()` and `asofLeftJoin()` use SQL-style null semantics by default
- large or high-risk numeric results are decoded conservatively rather than silently coerced

`ck-orm` focuses on typed ClickHouse access: table definitions, query composition, write helpers, session helpers, and observability. `createTable()`, `createMaterializedView()` and `dropTable()` each run one DDL statement; schema migrations (comparing schemas, `ALTER`, versioning) remain in the migration tooling used by the application.

## Docs

- [Installation](https://ck-orm.lyz.cloud/reference/installation.md): ck-orm has no required dependencies.
- [Quick start](https://ck-orm.lyz.cloud/reference/quick-start.md): The examples below use a single table so the main flow stays easy to follow. Covers 1. Define a schema, 2. Create a client, 3. Query data, 4. Observe queries.
- [Examples](https://ck-orm.lyz.cloud/reference/examples.md): The examples page shows runnable queries with the exact SQL each one sends to ClickHouse.
- [Mental model](https://ck-orm.lyz.cloud/reference/mental-model.md): Use `ck-orm` with these boundaries in mind.
- [Schema DSL](https://ck-orm.lyz.cloud/reference/schema-dsl.md): Use `ckTable(name, columns, options?)` to define a table. Covers `ckTable()`, Type inference, Refining column types with `$type<T>()`, Diverging insert and select types with `$type<{ select, insert }>()`, Insert model rules: DEFAULT, MATERIALIZED, ALIAS, Runtime validation with `$validator(schema)`, JSON column type, `ckAlias()`, Column names, Column builders, Column Type Cookbook.
- [Client configuration](https://ck-orm.lyz.cloud/reference/client-configuration.md): Create a client with `clickhouseClient()`. Covers Connection modes, Common fields, Advanced fields, ClickHouse settings, Authentication.
- [Query builder](https://ck-orm.lyz.cloud/reference/query-builder.md): The snippets below assume `db`, `probeTelemetry`, and the referenced helpers imported from `ck-orm`. Covers `select()`, `from()`, `innerJoin()`, `leftJoin()`, `asofJoin()`, `asofLeftJoin()`, `where()` and condition helpers, `groupBy()`, `having()`, `orderBy()`, `limit()`, `offset()`, `final()`, `limitBy()`, Execution modes, Inspecting the SQL with `toSQL()`, Subqueries and CTEs, `db.count()`.
- [Join null semantics](https://ck-orm.lyz.cloud/reference/join-null-semantics.md): `leftJoin()` and `asofLeftJoin()` default to SQL-style null semantics by automatically applying `join_use_nulls = 1`.
- [Writes](https://ck-orm.lyz.cloud/reference/writes.md): Use the builder when you want typed inserts that follow the table schema. Covers `insert(table).values(...)`, `insert(table).fromSelect(select)`, `insertJsonEachRow()`.
- [Raw SQL](https://ck-orm.lyz.cloud/reference/raw-sql.md): `ck-orm` includes its own SQL template API. Covers `` ckSql`...` ``, `ckSql.join()` and `ckSql.identifier()`, Raw SQL with `query_params`, `ck.expr()`, Raw query formats, Decimal precision in expressions.
- [Window expressions](https://ck-orm.lyz.cloud/reference/window-expressions.md): Wrap an `fn.*` function expression with `fn.over(...)`.
- [Functions and table functions](https://ck-orm.lyz.cloud/reference/functions-and-table-functions.md): Generic, conversion, aggregate, JSON, tuple, and table-related helpers include. Covers `fn`, Conditional branch types, Regex replacement, Typed tuple aggregation, `fn.count` / `fn.uniqExact` modes, `fn.table`.
- [Tables and materialized views](https://ck-orm.lyz.cloud/reference/tables-and-materialized-views.md): `createTable()`, `createMaterializedView()` and `dropTable()` each send one DDL statement built from schema objects. Covers `createTable()`, `createMaterializedView()`, `dropTable()`.
- [Sessions and temporary tables](https://ck-orm.lyz.cloud/reference/sessions-and-temporary-tables.md): ClickHouse does not provide traditional transactions. Covers `runInSession()`, Session behavior, Session concurrency contract.
- [Runtime methods](https://ck-orm.lyz.cloud/reference/runtime-methods.md): Beyond the builder, the client also exposes lower-level runtime methods. Covers `execute()`, `stream()`, `command()`, `withSettings()`, Compiled query integration, `ping()` and `replicasStatus()`.
- [Observability](https://ck-orm.lyz.cloud/reference/observability.md): `ck-orm` provides two observability layers. Covers Logger, OpenTelemetry plugin, Writing plugins.
- [Error model](https://ck-orm.lyz.cloud/reference/error-model.md): Public error types (type-only exports).
- [Security](https://ck-orm.lyz.cloud/reference/security.md): `ck-orm` is designed to make unsafe SQL construction difficult by default. Covers Trusted-only APIs, Tracing data exposure, Error responses.

## Examples

- [Examples](https://ck-orm.lyz.cloud/examples/index.md): Runnable queries with the exact SQL each one sends to ClickHouse: decimal-sum, literal-search, left-join, trace-list, support-tickets, website-analytics, asof-price, dynamic-signals, bluesky-events, cdc-rollup, usage-metering, request-latency, query-plugins, otel-tracing.

## Optional

- [Complete reference](https://ck-orm.lyz.cloud/llms-full.txt): Every section above in one file.
- [Type declarations](https://cdn.jsdelivr.net/npm/ck-orm@0.0.32/index.d.ts): Bundled `.d.ts` with the exact signature of every public export.
- [End-to-end tests](https://github.com/MunMunMiao/ck-orm/tree/main/e2e): Runnable scenarios against a real ClickHouse server.