ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/clickhouse/index.d.ts

@@ -0,0 +1,660 @@
+/**
+ * ClickHouse dialect implementation for the TypeScript ORM
+ *
+ * ClickHouse is a columnar OLAP database, not an OLTP relational database like the
+ * other dialects in this codebase. Several assumptions the rest of this ORM makes
+ * about "a SQL database" do not hold for ClickHouse, and this file tries to be
+ * explicit (in comments, thrown errors, and generated SQL) about where ClickHouse
+ * genuinely behaves differently rather than papering over the differences:
+ *
+ *  - `CREATE TABLE` requires an `ENGINE = ...` clause (e.g. `MergeTree()`), and
+ *    MergeTree-family engines require an `ORDER BY` clause - ClickHouse's sorting
+ *    key, which stands in for a traditional single-column auto-increment primary
+ *    key (there is no such concept here).
+ *  - There is no enforced FOREIGN KEY, UNIQUE, or (traditionally) PRIMARY KEY
+ *    constraint. ClickHouse will happily store duplicate "keys" - the ORDER BY
+ *    key only controls physical sort order/merges, it does not deduplicate or
+ *    enforce uniqueness unless combined with a ReplacingMergeTree engine and a
+ *    subsequent (asynchronous, background) merge/`OPTIMIZE ... FINAL`.
+ *  - There are no synchronous, transactional UPDATE/DELETE statements. ClickHouse
+ *    supports `ALTER TABLE ... UPDATE` / `ALTER TABLE ... DELETE`, but these are
+ *    asynchronous *mutations*: the statement returns as soon as the mutation is
+ *    scheduled, and the actual rewrite happens in the background (progress is
+ *    visible in `system.mutations`).
+ *  - There is no multi-statement ACID transaction support (no BEGIN/COMMIT/
+ *    ROLLBACK spanning multiple statements). A single INSERT is atomic at the
+ *    block level; nothing else is. `startTransaction`/`commitTransaction`/
+ *    `rollbackTransaction` throw a clear error rather than silently no-op-ing,
+ *    matching how this codebase signals genuinely unsupported capabilities
+ *    elsewhere (see MSSQL's partition methods, or the FDW/extension stubs on
+ *    non-PostgreSQL dialects).
+ *  - "Upsert" is not a synchronous `ON CONFLICT` / `MERGE` statement. The
+ *    idiomatic ClickHouse pattern is: insert a new row into a
+ *    ReplacingMergeTree(-family) table and let ClickHouse's background merges
+ *    asynchronously drop older rows sharing the same ORDER BY key (optionally
+ *    keeping the row with the greatest `version` column). `buildUpsertQuery()`
+ *    therefore just emits a plain INSERT and documents this loudly instead of
+ *    pretending to provide synchronous upsert semantics ClickHouse doesn't have.
+ */
+import type { ClickHouseClient as CHClient } from '@clickhouse/client';
+import { Dialect, DialectOptions, ColumnDefinition, TableOptions, DropTableOptions, TableDescription, IndexOptions, IndexDefinition, InsertOptions, UpdateOptions as DUpdateOptions, DeleteOptions, SelectOptions, UpsertQueryOptions, DropSchemaOptions, ViewOptions, DropViewOptions, ConstraintDefinition, DropConstraintOptions, BuildOptions, FdwForeignServerOptions, FdwAlterForeignServerOptions, FdwUserMappingOptions, FdwForeignTableOptions, FdwImportForeignSchemaOptions, ExtensionInfo } from '../dialect';
+import { Transaction, TransactionOptions, QueryResult, QueryOptions, DataType, WhereOptions, Order, CreatePartitionOptions, AttachPartitionOptions, DetachPartitionOptions, StoredProcedureOptions, DropStoredProcedureOptions, ExecuteStoredProcedureOptions, StreamOptions } from '../../types';
+import { Readable } from 'stream';
+import { Literal } from '../../prorm';
+/**
+ * Typed configuration for ClickHouse's MergeTree engine family, passed as
+ * `(options as any).mergeTreeEngine` (or the `mergeTreeEngine` field on the
+ * loosely-typed `TableOptions` extension this dialect already uses for
+ * `orderBy`/`partitionBy`/`ttl`) to `createTable()`/`createPartitionedTable()`.
+ *
+ * Each variant has genuinely different merge/aggregation semantics and a
+ * distinct set of required columns, which `buildMergeTreeEngineClause()`
+ * validates against the table's declared columns before ever reaching
+ * ClickHouse (rather than letting a caller discover a missing `Sign` column
+ * via an opaque server-side error at INSERT/merge time):
+ *
+ *  - `MergeTree` / `ReplacingMergeTree`: already-supported plain engines.
+ *    `ReplacingMergeTree` optionally takes a `version` column (keeps the row
+ *    with the greatest value on merge) and, since v22.6, an `isDeleted`
+ *    column (paired with `version`, for soft-delete-on-merge semantics).
+ *  - `SummingMergeTree`: sums numeric columns (not part of the ORDER BY key)
+ *    on merge. `columns`, if given, restricts summing to specific numeric
+ *    columns instead of every numeric column in the table.
+ *  - `AggregatingMergeTree`: merges rows sharing an ORDER BY key by combining
+ *    partial aggregate states. Requires at least one `AggregateFunction(...)`
+ *    (or `SimpleAggregateFunction(...)`) column - ClickHouse's real rollup
+ *    mechanism, almost always paired with a materialized view.
+ *  - `CollapsingMergeTree`: cancels out row pairs sharing an ORDER BY key via
+ *    a `Sign Int8` column (`1` = insert the "current" state, `-1` = cancel a
+ *    previous one). Requires that `Sign Int8` column to exist.
+ *  - `VersionedCollapsingMergeTree`: like `CollapsingMergeTree`, but adds a
+ *    `Version` column so out-of-order (e.g. multi-threaded) inserts of
+ *    matching +1/-1 pairs still collapse correctly. Requires both the
+ *    `Sign Int8` column and a numeric `Version` column.
+ */
+export type MergeTreeEngineConfig = {
+    type: 'MergeTree';
+} | {
+    type: 'ReplacingMergeTree';
+    version?: string;
+    isDeleted?: string;
+} | {
+    type: 'SummingMergeTree';
+    columns?: string[];
+} | {
+    type: 'AggregatingMergeTree';
+} | {
+    type: 'CollapsingMergeTree';
+    sign: string;
+} | {
+    type: 'VersionedCollapsingMergeTree';
+    sign: string;
+    version: string;
+};
+/**
+ * Definition of a MergeTree-family "projection": a table-scoped, ClickHouse-
+ * maintained alternate physical layout (its own sort order and, optionally,
+ * its own pre-aggregation) of a subset of a table's columns, kept in sync on
+ * every INSERT/merge. ClickHouse's query planner transparently substitutes a
+ * matching projection when it would answer a query more cheaply than the
+ * base table - this is ClickHouse's real mechanism for "multiple sort orders
+ * of the same data" / materialized rollups without a separate table.
+ *
+ * Maps onto the real SQL grammar, which uses the same projection body shape
+ * in both places ClickHouse accepts one:
+ *   - inline at `CREATE TABLE` time: `PROJECTION name (SELECT ... [GROUP BY
+ *     ...] [ORDER BY ...])`
+ *   - `ALTER TABLE t ADD PROJECTION name (SELECT ... [GROUP BY ...]
+ *     [ORDER BY ...])`
+ * `select` is the column list only (e.g. `'id, value'` or
+ * `'toStartOfHour(ts) AS hour, count() AS c'`) - a projection body has no
+ * `FROM` clause, only the column list and optional GROUP BY/ORDER BY.
+ */
+export interface ProjectionDefinition {
+    /** Column list / expressions selected into the projection (no `SELECT` keyword, no `FROM`). */
+    select: string;
+    /** Optional `GROUP BY` expression(s) for a pre-aggregated (rollup) projection. */
+    groupBy?: string | string[];
+    /** Optional `ORDER BY` expression(s) - the projection's own physical sort key. */
+    orderBy?: string | string[];
+}
+/**
+ * ClickHouse dialect connection/behavior options.
+ */
+export interface ClickHouseDialectOptions extends DialectOptions {
+    /** ClickHouse HTTP interface host. @default 'localhost' */
+    host?: string;
+    /** ClickHouse HTTP interface port. @default 8123 (ClickHouse's default HTTP port) */
+    port?: number;
+    /** 'http' or 'https'. @default 'http' */
+    protocol?: 'http' | 'https';
+    database?: string;
+    username?: string;
+    password?: string;
+    /**
+     * Default `ENGINE = ...` clause used by createTable()/createPartitionedTable()
+     * when `TableOptions.engine` is not supplied for a given call.
+     * @default 'MergeTree()'
+     */
+    engine?: string;
+    /**
+     * Default ORDER BY expression/columns used by createTable() when the caller
+     * doesn't specify one (via a non-standard `orderBy` field on TableOptions) and
+     * no column is marked `primaryKey`. ClickHouse's MergeTree-family engines
+     * REQUIRE an ORDER BY (their sorting key) - there is no implicit single-column
+     * auto-increment primary key the way OLTP databases have.
+     */
+    orderBy?: string | string[];
+    /** Request timeout in milliseconds, forwarded to `@clickhouse/client`. */
+    requestTimeout?: number;
+    /** Arbitrary ClickHouse session settings applied to every request. */
+    clickhouseSettings?: Record<string, unknown>;
+}
+/**
+ * ClickHouse dialect class that implements the Dialect interface.
+ *
+ * Uses the official `@clickhouse/client` (Promise-native) driver, talking to
+ * ClickHouse's HTTP interface (default port 8123).
+ */
+export declare class ClickHouseDialect implements Dialect {
+    readonly name = "clickhouse";
+    readonly library = "@clickhouse/client";
+    private client;
+    private _isConnected;
+    private config;
+    constructor(config: ClickHouseDialectOptions);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnection(): CHClient | null;
+    isConnected(): boolean;
+    getDatabaseVersion(): Promise<string>;
+    /**
+     * Stream query results by paging through `sql` via repeated
+     * dialect-appropriate LIMIT/OFFSET queries (see
+     * `createPaginatedQueryStream()` in `src/dialects/query-stream-helper.ts`)
+     * instead of loading the whole result set into memory at once.
+     * @param sql - The SELECT statement to stream
+     * @param options - Streaming options (batch size, backpressure watermark, model mapping)
+     */
+    queryStream(sql: string, options?: StreamOptions): Readable;
+    /**
+     * Execute a raw SQL statement.
+     *
+     * `@clickhouse/client` exposes distinct methods for statements that return
+     * data (`query()`, used here for SELECT/SHOW/DESCRIBE/EXPLAIN) versus
+     * statements that don't (`command()`, used here for everything else - DDL,
+     * INSERT, and the ALTER TABLE ... UPDATE/DELETE mutations built below).
+     * `command()` does not return row data, so non-SELECT statements always come
+     * back with `rows: []`; in particular, `rowCount` after an
+     * `ALTER TABLE ... UPDATE/DELETE` mutation is NOT the number of rows the
+     * mutation will eventually touch - ClickHouse only reports that
+     * asynchronously via `system.mutations`.
+     */
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Substitute `?` (positional) or `:name` (named) placeholders with escaped
+     * literal values. ClickHouse's HTTP client sends a single opaque SQL string
+     * per request - unlike the pg/mysql2/mssql drivers used by the other
+     * dialects in this codebase, there is no native positional-parameter binding
+     * for arbitrary values and WHERE trees (ClickHouse's own `{name:Type}` query
+     * parameters require a separate `query_params` map and only support scalar
+     * substitution). So, exactly like the SQLite/PostgreSQL dialects already do
+     * when `options.replacements` is supplied to `query()`, this performs plain
+     * string substitution with escaped literals before the SQL is sent.
+     */
+    replaceReplacements(sql: string, replacements?: Record<string, unknown> | unknown[]): string;
+    escape(value: unknown): string;
+    private escapeString;
+    private formatDateTime;
+    escapeId(identifier: unknown): string;
+    quoteIdentifier(identifier: string): string;
+    quoteTable(tableName: string, schema?: string): string;
+    createSchema(schema: string): Promise<void>;
+    dropSchema(schema: string, options?: DropSchemaOptions): Promise<void>;
+    showAllSchemas(): Promise<string[]>;
+    listSchemas(): Promise<string[]>;
+    createDatabaseSQL(options: {
+        name: string;
+        encoding?: string;
+        lcCollate?: string;
+        lcCtype?: string;
+        template?: string;
+        tablespace?: string;
+        collate?: string;
+        isTemplate?: boolean;
+    }): string;
+    dropDatabaseSQL(name: string): string;
+    createSavepointSQL(_name?: string): string;
+    releaseSavepointSQL(_name: string): string;
+    rollbackToSavepointSQL(_name: string): string;
+    createExtension(_extensionName: string, _options?: unknown): Promise<void>;
+    dropExtension(_extensionName: string, _options?: unknown): Promise<void>;
+    getExtensions(): Promise<ExtensionInfo[]>;
+    hasExtension(_extensionName: string): Promise<boolean>;
+    /**
+     * Resolve the ORDER BY (sorting key) clause for a MergeTree-family table:
+     * an explicit `orderBy` (non-standard extension read off `options` since
+     * `TableOptions` doesn't declare it), else column(s) marked `primaryKey`,
+     * else the dialect-level default, else the first declared column, else
+     * `tuple()` (ClickHouse's explicit "no sorting key" spelling).
+     */
+    private resolveOrderBy;
+    /**
+     * Build a validated `ENGINE = ...` clause for one of the MergeTree-family
+     * engines from a typed `MergeTreeEngineConfig`, checking the distinct
+     * required-column rules each engine variant has (see the doc comment on
+     * `MergeTreeEngineConfig` above) against the table's declared columns.
+     * Throws a descriptive error - rather than emitting SQL ClickHouse would
+     * reject at CREATE TABLE or (worse) silently misbehave on at merge time -
+     * when a required column is missing or the wrong type.
+     */
+    private buildMergeTreeEngineClause;
+    /**
+     * Build a projection body - `name (SELECT ... [GROUP BY ...] [ORDER BY ...])`
+     * - shared by the inline `PROJECTION` clause in `CREATE TABLE` and
+     * `ALTER TABLE ... ADD PROJECTION`, since both use the exact same grammar.
+     */
+    private buildProjectionClause;
+    private getColumnDefinitionSql;
+    private getDefaultValue;
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions): Promise<void>;
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    createPartitionedTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: TableOptions & {
+        partitionBy: {
+            type: 'range' | 'list' | 'hash';
+            column: string | string[];
+        };
+        partitions?: {
+            name: string;
+        }[];
+    }): Promise<void>;
+    createPartition(_options: CreatePartitionOptions): Promise<void>;
+    attachPartition(options: AttachPartitionOptions): Promise<void>;
+    detachPartition(_options: DetachPartitionOptions): Promise<void>;
+    dropPartition(_partitionName: string, _options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /** Format a partition value/expression for ATTACH/DETACH/DROP PARTITION. */
+    private formatPartitionExpr;
+    createView(viewName: string, query: string, options?: ViewOptions): Promise<void>;
+    /**
+     * `CREATE MATERIALIZED VIEW ... TO <target> AS SELECT ...` - ClickHouse's
+     * real materialized-view syntax. Unlike a plain (or most other databases')
+     * view, a ClickHouse materialized view is a push-based, insert-triggered
+     * transform: every time a row is INSERTed into the underlying source
+     * table(s) referenced by `query`'s FROM clause, ClickHouse runs `query`
+     * against just the newly-inserted block and appends the result into the
+     * `to` target table - it is NOT recomputed at read time the way a normal
+     * view or a re-run query would be, and it does not "backfill" existing
+     * rows already in the source table unless `populate: true` is given.
+     *
+     * `showViews()` already queries `system.tables` for `engine =
+     * 'MaterializedView'`, so this is the corresponding write-side method that
+     * was previously entirely missing (only plain, non-materialized
+     * `CREATE VIEW` existed via `createView()` above).
+     *
+     * Two real ClickHouse forms are supported:
+     *   - `{ to: 'target_table' }`: the common, recommended form - the target
+     *     table is created separately (with its own ENGINE/ORDER BY, e.g. an
+     *     AggregatingMergeTree for rollups) and the materialized view just
+     *     describes the transform feeding it.
+     *   - Omitting `to` (with an inline `engine`/`orderBy0`): ClickHouse also
+     *     allows a materialized view to own an implicit hidden target table
+     *     (`CREATE MATERIALIZED VIEW ... ENGINE = ... AS SELECT ...`); provide
+     *     `engine`/`orderBy` in that case instead of `to`.
+     */
+    createMaterializedView(viewName: string, query: string, options?: {
+        to?: string;
+        schema?: string;
+        engine?: string;
+        orderBy?: string | string[];
+        populate?: boolean;
+        ifNotExists?: boolean;
+        replace?: boolean;
+    }): Promise<void>;
+    dropView(viewName: string, options?: DropViewOptions): Promise<void>;
+    showViews(): Promise<string[]>;
+    /**
+     * Run `OPTIMIZE TABLE <t> [PARTITION ...] [FINAL] [DEDUPLICATE [BY ...]]` —
+     * ClickHouse's on-demand merge trigger. This is the *write-side* counterpart
+     * to reading with `FINAL`: it forces the background merge that collapses
+     * ReplacingMergeTree/CollapsingMergeTree rows to their final state so that
+     * ordinary (non-`FINAL`) reads see deduplicated data.
+     *
+     * Prefer this after a batch of ReplacingMergeTree "upserts" (which are plain
+     * INSERTs — see {@link buildUpsertQuery}) when you want subsequent reads to be
+     * clean without paying the per-query `FINAL` merge-on-read cost. Note
+     * `OPTIMIZE` is heavy and not guaranteed to merge everything in one pass on
+     * very large tables; `FINAL` on the read is the guaranteed-correct fallback.
+     *
+     * @param options.final - append `FINAL` (merge even a single existing part).
+     * @param options.deduplicate - append `DEDUPLICATE` (drop fully-identical rows).
+     * @param options.deduplicateBy - column list for `DEDUPLICATE BY (...)`.
+     * @param options.partition - restrict to a single partition (`PARTITION <expr>`).
+     */
+    optimizeTable(tableName: string, options?: {
+        final?: boolean;
+        deduplicate?: boolean;
+        deduplicateBy?: string[];
+        partition?: string;
+    }): Promise<void>;
+    /**
+     * `CREATE DICTIONARY <name> (attrs) PRIMARY KEY <key> SOURCE(...) LAYOUT(...)
+     * LIFETIME(...)` — ClickHouse's in-memory key/value lookup/enrichment object
+     * backed by another table, file, or HTTP/DB source. Exposed so callers get a
+     * typed builder instead of hand-writing the multi-clause DDL.
+     *
+     * @param options.attributes - dictionary columns (`name type`, optional default/expression).
+     * @param options.primaryKey - key attribute name(s).
+     * @param options.source - raw `SOURCE(...)` body, e.g. `CLICKHOUSE(TABLE 'users')`.
+     * @param options.layout - raw `LAYOUT(...)` body, e.g. `HASHED()` / `FLAT()` / `COMPLEX_KEY_HASHED()`.
+     * @param options.lifetime - refresh lifetime; a number => `LIFETIME(n)`, a
+     *   `{min,max}` => `LIFETIME(MIN min MAX max)`.
+     */
+    createDictionary(name: string, options: {
+        attributes: Array<{
+            name: string;
+            type: string;
+            default?: string;
+            expression?: string;
+        }>;
+        primaryKey: string | string[];
+        source: string;
+        layout: string;
+        lifetime?: number | {
+            min: number;
+            max: number;
+        };
+        replace?: boolean;
+        ifNotExists?: boolean;
+        comment?: string;
+    }): Promise<void>;
+    dropDictionary(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    showTables(): Promise<string[]>;
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    changeColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    addForeignKey(_tableName: string, _columnName: string, _referencedTableName: string, _referencedColumnName: string, _options?: any): Promise<void>;
+    bulkInsert(tableName: string, records: Record<string, any>[], _options?: any): Promise<QueryResult>;
+    showConstraints(_tableName: string): Promise<any[]>;
+    addConstraint(tableName: string, options: {
+        type: 'UNIQUE' | 'CHECK' | 'PRIMARY KEY' | 'FOREIGN KEY';
+        fields: string[];
+        name?: string;
+        references?: {
+            table: string;
+            fields: string[];
+        };
+        check?: string;
+    }): Promise<void>;
+    removeConstraint(tableName: string, constraintName: string): Promise<void>;
+    createConstraint(tableName: string, constraintDef: ConstraintDefinition): Promise<void>;
+    dropConstraint(tableName: string, constraintName: string, _options?: DropConstraintOptions): Promise<void>;
+    showIndexes(tableName: string): Promise<any[]>;
+    addIndex(tableName: string, indexName: string, fields?: string[], options?: IndexOptions): Promise<void>;
+    removeIndex(tableName: string, indexName: string): Promise<void>;
+    createIndex(tableName: string, indexDef: IndexDefinition): Promise<void>;
+    dropIndex(tableName: string, indexName: string, options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    /**
+     * `ALTER TABLE table ADD PROJECTION name (SELECT ... [GROUP BY ...] [ORDER BY ...])`.
+     *
+     * Adding a projection only registers its definition; ClickHouse does not
+     * retroactively backfill it for existing parts. Call
+     * `materializeProjection()` (`ALTER TABLE ... MATERIALIZE PROJECTION`)
+     * afterwards to build it for data that already exists - new
+     * inserts/merges are kept in sync automatically from this point on
+     * either way.
+     */
+    addProjection(tableName: string, projectionName: string, definition: ProjectionDefinition): Promise<void>;
+    /**
+     * `ALTER TABLE table DROP PROJECTION [IF EXISTS] name`.
+     *
+     * Implemented as a mutation: removes the projection's definition from the
+     * table's metadata and deletes its files from disk.
+     */
+    dropProjection(tableName: string, projectionName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    /**
+     * `ALTER TABLE table MATERIALIZE PROJECTION [IF EXISTS] name [IN PARTITION partition]`.
+     *
+     * Builds (or rebuilds) a projection for existing data. Needed after
+     * `addProjection()` on a table that already has rows - a freshly-added
+     * projection definition otherwise only applies to data inserted/merged
+     * after it was added.
+     */
+    materializeProjection(tableName: string, projectionName: string, options?: {
+        ifExists?: boolean;
+        partition?: string;
+    }): Promise<void>;
+    createFulltextIndex(tableName: string, indexName: string, fields: string[], _options?: {
+        parser?: string;
+        comment?: string;
+    }): Promise<void>;
+    createSpatialIndex(_tableName: string, _indexName: string, _fields: string[], _options?: {
+        storage?: string;
+        srid?: number;
+    }): Promise<void>;
+    describeTable(tableName: string): Promise<TableDescription>;
+    renameTable(oldName: string, newName: string): Promise<void>;
+    changeOwner(_newOwner: string, _tableName: string): Promise<void>;
+    createSecurityPolicy(policyName: string, tableName: string, options?: {
+        predicate?: string;
+    }): Promise<void>;
+    dropSecurityPolicy(policyName: string, tableName: string): Promise<void>;
+    startTransaction(_options?: TransactionOptions): Promise<Transaction>;
+    commitTransaction(_transaction: Transaction): Promise<void>;
+    rollbackTransaction(_transaction: Transaction): Promise<void>;
+    getDataTypeSql(dataType: DataType): string;
+    /**
+     * `uniq(column)` - ClickHouse's default approximate distinct-count
+     * (adaptive sampling, small constant memory, ~1-2% error). The fastest and
+     * least memory-hungry of the `uniq*` family; prefer this unless you need
+     * `uniqExact`'s precision or `uniqCombined`'s tunable accuracy/memory
+     * trade-off.
+     */
+    uniq(column: string, alias?: string): Literal;
+    /**
+     * `uniqCombined([precision])(column)` - approximate distinct count that
+     * blends an array, a hash table, and HyperLogLog depending on cardinality,
+     * giving better accuracy-per-byte than plain `uniq` at the cost of a bit
+     * more CPU. `precision` (`HLL_precision`, default 17) trades memory for
+     * accuracy: higher precision = more memory, lower error.
+     */
+    uniqCombined(column: string, alias?: string, precision?: number): Literal;
+    /** `uniqHLL12(column)` - classic HyperLogLog-based approximate distinct count. */
+    uniqHLL12(column: string, alias?: string): Literal;
+    /**
+     * `uniqExact(column)` - EXACT distinct count (not approximate - despite
+     * living in the `uniq*` family). Included here for symmetry/discoverability
+     * since callers reaching for `uniq*` helpers need an easy way to opt into
+     * exactness when cardinality is low enough that the memory/CPU cost is
+     * acceptable.
+     */
+    uniqExact(column: string, alias?: string): Literal;
+    /**
+     * `quantile(level)(column)` - approximate percentile/quantile estimation
+     * (reservoir sampling) - e.g. `quantile(0.99)(latency_ms)` for p99 latency.
+     * `level` must be in `[0, 1]`.
+     */
+    quantile(level: number, column: string, alias?: string): Literal;
+    /**
+     * `quantiles(level1, level2, ...)(column)` - like `quantile()`, but computes
+     * several quantiles in one pass (e.g. p50/p90/p99 together is cheaper than
+     * three separate `quantile()` calls since ClickHouse shares the sample).
+     * Returns an Array(Float64) column.
+     */
+    quantiles(levels: number[], column: string, alias?: string): Literal;
+    /**
+     * `quantileExact(level)(column)` - EXACT quantile (loads all values into
+     * memory; use for small-to-medium datasets where precision matters more
+     * than the approximate functions' bounded memory usage).
+     */
+    quantileExact(level: number, column: string, alias?: string): Literal;
+    /**
+     * `quantileTDigest(level)(column)` - approximate quantile via the t-digest
+     * algorithm: lower memory than `quantileExact`, better accuracy at extreme
+     * percentiles (e.g. p99.9) than the default reservoir-sampling `quantile()`.
+     */
+    quantileTDigest(level: number, column: string, alias?: string): Literal;
+    private assertQuantileLevel;
+    buildWhereClause(where: WhereOptions, _options?: BuildOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    buildOrderClause(order: Order, _options?: BuildOptions): string;
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * ClickHouse has no synchronous UPSERT / `ON CONFLICT` / `MERGE` statement.
+     * The idiomatic ClickHouse pattern is: insert a new row into a
+     * ReplacingMergeTree(-family) table and let ClickHouse's background merges
+     * asynchronously drop older rows sharing the same ORDER BY key (optionally
+     * keeping the row with the greatest `version` column, if the engine and
+     * table were set up with one). Until that merge runs, duplicate rows for
+     * the same key coexist, and reads must use `SELECT ... FINAL` (or the table
+     * must be `OPTIMIZE ... FINAL`-ed) to see "the latest" value.
+     *
+     * This method therefore only ever builds a plain INSERT - `conflictFields`/
+     * `updateOnDuplicate` are accepted (to satisfy the shared Dialect signature)
+     * but silently have no effect, and that is called out loudly below rather
+     * than pretending this performs a real, synchronous upsert.
+     *
+     * IMPORTANT: pass `{ final: true }` to `buildSelectQuery()` on subsequent
+     * reads of this table (`SELECT ... FROM <table> FINAL`) to force ClickHouse
+     * to apply ReplacingMergeTree's merge-time dedup logic at query time -
+     * otherwise a plain SELECT can return duplicate/stale rows for the same
+     * ORDER BY key until a background merge happens. See the doc comment on
+     * `buildSelectQuery()`'s `final` handling for why this is opt-in rather
+     * than automatic.
+     */
+    buildUpsertQuery(tableName: string, values: Record<string, unknown>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * `ALTER TABLE ... UPDATE` is an asynchronous ClickHouse *mutation*, not a
+     * synchronous, transactional UPDATE. The statement returns as soon as the
+     * mutation is scheduled; ClickHouse rewrites the affected data parts in the
+     * background (progress/completion is visible via `system.mutations`), so
+     * `query()`'s `rowCount` for this statement is always 0 - it reflects "rows
+     * returned by this HTTP request", not "rows the mutation will touch".
+     */
+    buildUpdateQuery(tableName: string, values: Record<string, unknown>, where: WhereOptions, options?: DUpdateOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * `ALTER TABLE ... DELETE` is likewise an asynchronous mutation (see
+     * buildUpdateQuery's doc comment above) - not a synchronous, transactional
+     * DELETE. ClickHouse also offers a syntactically lighter `DELETE FROM ...
+     * WHERE ...` ("lightweight delete", available since v23.3) which marks rows
+     * deleted immediately for query purposes while physically removing them in
+     * the background; this builder intentionally uses the classic, more widely
+     * supported `ALTER TABLE ... DELETE` mutation form instead.
+     */
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    buildSelectQuery(options: SelectOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Increment/decrement is built on the same asynchronous ALTER TABLE ...
+     * UPDATE mutation mechanism as buildUpdateQuery() - see its doc comment.
+     */
+    buildIncrementQuery(tableName: string, fields: string | string[] | Record<string, number>, where: WhereOptions, options?: {
+        by?: number;
+    }): {
+        sql: string;
+        values: unknown[];
+    };
+    private fdwUnsupported;
+    buildCreateServerQuery(_name: string, _opts: FdwForeignServerOptions): string;
+    buildAlterServerQuery(_name: string, _opts: FdwAlterForeignServerOptions): string;
+    buildDropServerQuery(_name: string, _opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    buildCreateUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildAlterUserMappingQuery(_opts: FdwUserMappingOptions): string;
+    buildDropUserMappingQuery(_serverName: string, _user: string, _opts?: {
+        ifExists?: boolean;
+    }): string;
+    buildCreateForeignTableQuery(_tableName: string, _opts: FdwForeignTableOptions): string;
+    buildDropForeignTableQuery(_tableName: string, _opts?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): string;
+    buildImportForeignSchemaQuery(_remoteSchema: string, _serverName: string, _opts?: FdwImportForeignSchemaOptions): string;
+    getServersQuery(): string;
+    createForeignDataWrapper(_fdwName: string, _options?: {
+        handler?: string;
+    }): Promise<void>;
+    dropForeignDataWrapper(_fdwName: string, _options?: {
+        ifExists?: boolean;
+    }): Promise<void>;
+    createForeignServer(_serverName: string, _fdwName: string, _options?: {
+        options?: Record<string, string>;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    dropForeignServer(_serverName: string, _options?: {
+        ifExists?: boolean;
+        cascade?: boolean;
+    }): Promise<void>;
+    createForeignTable(_tableName: string, _columns: Record<string, {
+        type: string;
+    }>, _options?: {
+        serverName?: string;
+        ifNotExists?: boolean;
+    }): Promise<void>;
+    createUserMapping(_userName: string, _serverName: string, _options?: any): Promise<void>;
+    dropUserMapping(_userName: string, _serverName: string, _options?: any): Promise<void>;
+    buildCreateUserQuery(username: string, options?: any): string;
+    buildAlterUserQuery(username: string, options: any): string;
+    buildDropUserQuery(username: string, options?: any): string;
+    getUsersQuery(): string;
+    buildGrantQuery(options: any): string;
+    buildRevokeQuery(options: any): string;
+    buildShowGrantsQuery(username: string, _host?: string): string;
+    buildFlushPrivilegesQuery(): string;
+    buildCreateRoleQuery(roleName: string, options?: any): string;
+    buildDropRoleQuery(roleName: string, options?: any): string;
+    buildGrantRoleQuery(role: string, to: any, _options?: any): string;
+    buildRevokeRoleQuery(role: string, from: any, _options?: any): string;
+    getRolesQuery(): string;
+    createStoredProcedure(_options: StoredProcedureOptions): Promise<void>;
+    createProcedure(options: StoredProcedureOptions): Promise<void>;
+    dropStoredProcedure(_procedureName: string, _options?: DropStoredProcedureOptions): Promise<void>;
+    dropProcedure(procedureName: string, options?: DropStoredProcedureOptions): Promise<void>;
+    executeStoredProcedure(_options: ExecuteStoredProcedureOptions): Promise<QueryResult>;
+    hasStoredProcedure(_procedureName: string, _schema?: string): Promise<boolean>;
+    /**
+     * Build an expression to shred a JSON document/array into relational rows.
+     * ClickHouse has no `JSON_TABLE`/`OPENJSON` function; the real equivalent composes
+     * `JSONExtractArrayRaw` (split a JSON array into raw per-element JSON strings) with
+     * `arrayJoin` (explode an array into rows), then per-column `JSONExtract*` functions
+     * (chosen by the requested column type) to pull typed values out of each element.
+     * ClickHouse: (SELECT JSONExtractString(elem, 'name') AS name, ... FROM
+     *   (SELECT arrayJoin(JSONExtractArrayRaw(expr, 'rowPath')) AS elem)) AS alias
+     */
+    buildJsonTable(jsonExpression: string, rowPath: string, columns: Array<{
+        name: string;
+        type?: string;
+        path?: string;
+        forOrdinality?: boolean;
+    }>, alias: string): string;
+}
+export declare function createClickHouseDialect(config: ClickHouseDialectOptions): ClickHouseDialect;