Getting started

Install

pnpm add @oorestisime/quarry @clickhouse/client

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

Create a typed DB

Define your schema as a plain TypeScript interface and pass it as the type parameter to createClickHouseDB.

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

interface DB {
  event_logs: {
    user_id: number;
    event_type: string;
    created_at: string;
    event_date: string;
    properties: string;
  };
  users: {
    id: number;
    email: string;
    status: string;
  };
}

const client = createClient({
  url: "http://localhost:8123",
});

const db = createClickHouseDB<DB>({ client });

That db value is now strongly typed against your schema. Table names, columns, and aliases are all checked.

Why Quarry stays plain

Quarry is a query builder, not a schema modeling framework. The library stays honest by typing what your queries read and write under ClickHouse's runtime semantics instead of asking you to maintain a second schema DSL.

If you already have a database and want help bootstrapping the DB type, use the CLI introspection flow instead of writing the interface by hand.

npx @oorestisime/quarry-cli introspect --database analytics --out db.ts

For repeatable generation, the introspection guide shows how to keep connection options, filters, and column type overrides in quarry.introspect.json.

Build and execute a query

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 rows = await 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)
  .execute();
    
SelectQueryBuilder<DB, { e: { user_id: number; event_type: string; created_at: string; }; }, { user_id: number; event_type: string; }, { user_id: QueryColumn<number, number>; event_type: QueryColumn<...>; }>.execute(options?: ClickHouseExecutionOptions): Promise<{
    user_id: number;
    event_type: string;
}[]>

Hover over rows above — the result type is inferred from the columns you actually selected.

Inspect SQL without executing

When you want to see what Quarry is going to send to ClickHouse without running it, use toSQL() instead of execute().

const compiled = db
  .selectFrom("event_logs as e")
  .select("e.user_id", "e.event_type")
  .where("e.event_type", "=", "signup")
  .toSQL();

compiled.query;
// SELECT e.user_id, e.event_type
// FROM event_logs AS e
// WHERE e.event_type = {p0:String}

compiled.params;
// { p0: "signup" }

The placeholders are ClickHouse parameterised queries, not string interpolation. The driver substitutes them server-side.