Quarry is a query builder first. It is not trying to be an ORM or hide ClickHouse behind a generic multi-dialect SQL abstraction.

Why Quarry

• ClickHouse-first surface area: FINAL, PREWHERE, SETTINGS, typed joins, INSERT INTO ... SELECT, and explicit table sources.
• Runtime-honest types: UInt64 comes back as string, Decimal comes back as number, and the docs are explicit about those semantics.
• Plain TypeScript DB types: Quarry stays focused on query building instead of asking you to maintain a second schema DSL.
• Inspectable output: every query can be compiled with toSQL() before you execute it.

Install

pnpm add @oorestisime/quarry @clickhouse/client

Quarry expects you to bring your own @clickhouse/client instance.

Quick look

import { createClient } from "@clickhouse/client";
import { createClickHouseDB } from "@oorestisime/quarry";

interface DB {
  event_logs: {
    user_id: number;
    event_type: string;
    created_at: string;
  };
}

const db = createClickHouseDB<DB>({
  client: createClient({ url: "http://localhost:8123" }),
});

const query = db
  .selectFrom("event_logs as e")
  .select("e.user_id", "e.event_type")
  .where("e.event_type", "=", "signup")
  .orderBy("e.created_at", "desc")
  .limit(50);

const compiled = query.toSQL();
const rows = await query.execute();

Choose a path

• Getting started — install Quarry, create a typed db, run a first query, inspect SQL.
• Introspection — bootstrap plain Tables, Views, and DB types from ClickHouse.
• API reference — exact builder methods, helper surfaces, and selected live type tables.
• Deep dive — runtime semantics, scope rules, ClickHouse quirks, and architecture.

Docs

Public docs are available at ch-quarry.vercel.app.

The docs source lives in docs/ and is built with Fumadocs. To run it locally:

pnpm install
pnpm --dir docs install
pnpm --dir docs dev

The site will be available on http://localhost:3000.

Status

This package is still in the early alpha stage. The current API is already validated against a real ClickHouse instance in integration tests, but the surface may still change before a stable release.

Current Scope

• typed selects and inserts, including INSERT INTO ... SELECT
• joins, subqueries, and CTEs
• FINAL, PREWHERE, GROUP BY, and HAVING
• toSQL() and execute()

See the docs site for the full supported API, runtime semantics, and concept guides.

• Roadmap — what is likely to land next

Naming

The project name is Quarry. The npm package name is @oorestisime/quarry.