@hypequery/clickhouse 2.2.0 → 2.4.0

package/dist/core/adapters/clickhouse-adapter.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseAdapter, QueryExecutionOptions } from './database-adapter.js';
+import type { DatabaseAdapter, QueryExecutionOptions, InsertExecutionOptions, InsertResultSummary } from './database-adapter.js';
 import type { ClickHouseConfig } from '../query-builder.js';
 export declare class ClickHouseAdapter implements DatabaseAdapter {
     private config;
@@ -8,6 +8,7 @@ export declare class ClickHouseAdapter implements DatabaseAdapter {
     constructor(config: ClickHouseConfig);
     query<T>(sql: string, params?: unknown[], options?: QueryExecutionOptions): Promise<T[]>;
     stream<T>(sql: string, params?: unknown[], options?: QueryExecutionOptions): Promise<ReadableStream<T[]>>;
+    insert<T extends Record<string, unknown>>(table: string, rows: T[], options?: InsertExecutionOptions): Promise<InsertResultSummary>;
     render(sql: string, params?: unknown[]): string;
 }
 export declare function createClickHouseAdapter(config: ClickHouseConfig): DatabaseAdapter;

package/dist/core/adapters/clickhouse-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clickhouse-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/clickhouse-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AA4B5D,qBAAa,iBAAkB,YAAW,eAAe;IAK3C,OAAO,CAAC,MAAM;IAJ1B,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAmB;gBAEb,MAAM,EAAE,gBAAgB;IAKtC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAW5F,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAYnH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM;CAGpD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAEjF"}
+{"version":3,"file":"clickhouse-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/clickhouse-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAsC5D,qBAAa,iBAAkB,YAAW,eAAe;IAK3C,OAAO,CAAC,MAAM;IAJ1B,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,MAAM,CAAmB;gBAEb,MAAM,EAAE,gBAAgB;IAKtC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAW5F,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAY7G,MAAM,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,CAAC;IAuB/B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,MAAM;CAGpD;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,gBAAgB,GAAG,eAAe,CAEjF"}

package/dist/core/adapters/clickhouse-adapter.js

@@ -3,6 +3,7 @@ import { substituteParameters } from '../utils.js';
 import { getConnectionEndpoint } from '../utils/connection-endpoint.js';
 import { createJsonEachRowStream } from '../utils/streaming-helpers.js';
 import { getAutoClientModule } from '../env/auto-client.js';
+import { assertSafeInsertIdentifiers } from '../utils/insert-identifiers.js';
 function createClickHouseClient(config) {
     if (isClientConfig(config)) {
         return config.client;
@@ -19,6 +20,13 @@ function deriveNamespace(config) {
     const username = 'username' in config ? config.username : 'default';
     return `${endpoint || 'unknown-host'}|${database || 'default'}|${username || 'default'}`;
 }
+function jsonOutputSettings(settings) {
+    return {
+        // Matches generated Int64+ result types and prevents JSON.parse precision loss.
+        output_format_json_quote_64bit_integers: 1,
+        ...settings,
+    };
+}
 export class ClickHouseAdapter {
     config;
     name = 'clickhouse';
@@ -34,7 +42,7 @@ export class ClickHouseAdapter {
         const result = await this.client.query({
             query: finalSQL,
             format: 'JSONEachRow',
-            clickhouse_settings: options?.clickhouseSettings,
+            clickhouse_settings: jsonOutputSettings(options?.clickhouseSettings),
             query_id: options?.queryId,
         });
         return result.json();
@@ -44,12 +52,34 @@ export class ClickHouseAdapter {
         const result = await this.client.query({
             query: finalSQL,
             format: 'JSONEachRow',
-            clickhouse_settings: options?.clickhouseSettings,
+            clickhouse_settings: jsonOutputSettings(options?.clickhouseSettings),
             query_id: options?.queryId,
         });
         const stream = result.stream();
         return createJsonEachRowStream(stream);
     }
+    async insert(table, rows, options) {
+        assertSafeInsertIdentifiers(table, options?.columns);
+        const result = await this.client.insert({
+            table,
+            values: rows,
+            format: 'JSONEachRow',
+            ...(options?.columns && options.columns.length > 0
+                ? { columns: options.columns }
+                : {}),
+            clickhouse_settings: {
+                // Lets ISO-8601 timestamps (JSON.stringify'd Date values) parse into DateTime columns.
+                date_time_input_format: 'best_effort',
+                ...options?.clickhouseSettings,
+            },
+            query_id: options?.queryId,
+        });
+        return {
+            queryId: result.query_id,
+            executed: result.executed,
+            summary: result.summary,
+        };
+    }
     render(sql, params = []) {
         return substituteParameters(sql, params);
     }

package/dist/core/adapters/database-adapter.d.ts

@@ -1,13 +1,33 @@
-import type { ClickHouseSettings } from '@clickhouse/client-common';
+import type { ClickHouseSettings, ClickHouseSummary } from '@clickhouse/client-common';
 export interface QueryExecutionOptions {
     clickhouseSettings?: ClickHouseSettings;
     queryId?: string;
 }
+export interface InsertExecutionOptions {
+    clickhouseSettings?: ClickHouseSettings;
+    queryId?: string;
+    /** Explicit column subset; adapters must preserve it so omitted columns take table DEFAULTs. */
+    columns?: string[];
+}
+export interface InsertResultSummary {
+    /** Empty when no request was sent or the backing engine does not provide query IDs. */
+    queryId: string;
+    executed: boolean;
+    /** Server-side insert summary when the client provides one (e.g. written_rows). */
+    summary?: ClickHouseSummary;
+}
 export interface DatabaseAdapter {
     readonly name: string;
     readonly namespace?: string;
     query<T>(sql: string, params?: unknown[], options?: QueryExecutionOptions): Promise<T[]>;
     stream?<T>(sql: string, params?: unknown[], options?: QueryExecutionOptions): Promise<ReadableStream<T[]>>;
+    /**
+     * Inserts rows that have already been normalized for JSONEachRow-compatible
+     * execution. The executor filters explicit empty batches before calling the
+     * adapter. When `options.columns` is present, omitted table columns must be
+     * left for the engine to fill via DEFAULT or Nullable semantics.
+     */
+    insert?<T extends Record<string, unknown>>(table: string, rows: T[], options?: InsertExecutionOptions): Promise<InsertResultSummary>;
     render?(sql: string, params?: unknown[]): string;
 }
 //# sourceMappingURL=database-adapter.d.ts.map

package/dist/core/adapters/database-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/database-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACzF,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3G,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;CAClD"}
+{"version":3,"file":"database-adapter.d.ts","sourceRoot":"","sources":["../../../src/core/adapters/database-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAEvF,MAAM,WAAW,qBAAqB;IACpC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,mFAAmF;IACnF,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IACzF,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3G;;;;;OAKG;IACH,MAAM,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,EAAE,EACT,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;CAClD"}

package/dist/core/features/aggregations.d.ts

@@ -1,6 +1,6 @@
 import type { BuilderState, SchemaDefinition } from '../types/builder-state.js';
 import { QueryBuilder } from '../query-builder.js';
-import type { SelectQueryNode, SelectionNode } from '../../types/index.js';
+import type { SelectQueryNode } from '../../types/index.js';
 export declare class AggregationFeature<Schema extends SchemaDefinition<Schema>, State extends BuilderState<Schema, string, any, keyof Schema, Partial<Record<string, keyof Schema>>>> {
     private builder;
     private static readonly TRAILING_ALIAS_PATTERN;
@@ -11,31 +11,23 @@ export declare class AggregationFeature<Schema extends SchemaDefinition<Schema>,
     private createAggregateSelection;
     private shouldInferGroupByFromSelection;
     private inferGroupBySelections;
+    /**
+     * Appends an aggregate selection (marked `isAggregate`, so GROUP BY
+     * inference never treats it as a grouping key) and infers GROUP BY from any
+     * plain selections already present.
+     */
+    private appendAggregateSelection;
     private createAggregation;
     sum(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
     count(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
     avg(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
     min(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
     max(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
-    countDistinct(column: string, alias: string): {
-        select: SelectionNode[];
-        kind: "select-query";
-        from?: import("../../types/base.js").SourceNode;
-        arrayJoins?: import("../../types/base.js").ArrayJoinNode[];
-        prewhere?: import("../../types/base.js").ExprNode;
-        where?: import("../../types/base.js").ExprNode;
-        groupBy?: import("../../types/base.js").GroupByItemNode[];
-        withTotals?: boolean;
-        having?: import("../../types/base.js").HavingNode[];
-        limitBy?: import("../../types/base.js").LimitByNode;
-        limit?: number;
-        offset?: number;
-        distinct?: boolean;
-        orderBy?: import("../../types/base.js").OrderByItemNode[];
-        joins?: import("../../types/base.js").JoinNode[];
-        ctes?: import("../../types/base.js").CteNode[];
-        unionQueries?: string[];
-        settings?: import("@clickhouse/client-common").ClickHouseSettings;
-    };
+    countDistinct(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
+    argMax(column: string, argColumn: string, alias: string): SelectQueryNode<State["output"], Schema>;
+    argMin(column: string, argColumn: string, alias: string): SelectQueryNode<State["output"], Schema>;
+    quantile(column: string, level: number, alias: string): SelectQueryNode<State["output"], Schema>;
+    stddev(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
+    variance(column: string, alias: string): SelectQueryNode<State["output"], Schema>;
 }
 //# sourceMappingURL=aggregations.d.ts.map

package/dist/core/features/aggregations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../src/core/features/aggregations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE3E,qBAAa,kBAAkB,CAC7B,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC;IAKxF,OAAO,CAAC,OAAO;IAH3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAsC;IACpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,8BAA8B,CAAoC;gBAEtE,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAExD,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,+BAA+B;IAYvC,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,iBAAiB;IAsBzB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAInC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;CAiB5C"}
+{"version":3,"file":"aggregations.d.ts","sourceRoot":"","sources":["../../../src/core/features/aggregations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,sBAAsB,CAAC;AAE3E,qBAAa,kBAAkB,CAC7B,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,MAAM,CAAC,CAAC,CAAC;IAMxF,OAAO,CAAC,OAAO;IAJ3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAsC;IACpF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,8BAA8B,CACuB;gBAEzD,OAAO,EAAE,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC;IAExD,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,oBAAoB;IAK5B,OAAO,CAAC,wBAAwB;IAQhC,OAAO,CAAC,+BAA+B;IAYvC,OAAO,CAAC,sBAAsB;IAa9B;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,iBAAiB;IAQzB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAInC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIjC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAI3C,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIvD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIvD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAOrD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAIpC,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAGvC"}

package/dist/core/features/aggregations.js

@@ -1,7 +1,7 @@
 export class AggregationFeature {
     builder;
     static TRAILING_ALIAS_PATTERN = /\s+AS\s+[A-Za-z_][A-Za-z0-9_]*$/i;
-    static LEADING_AGGREGATE_CALL_PATTERN = /^(COUNT|SUM|AVG|MIN|MAX)\s*\(/i;
+    static LEADING_AGGREGATE_CALL_PATTERN = /^(COUNT|SUM|AVG|MIN|MAX|argMax|argMin|quantile|stddevSamp|varSamp)\s*\(/i;
     constructor(builder) {
         this.builder = builder;
     }
@@ -40,8 +40,12 @@ export class AggregationFeature {
             };
         });
     }
-    createAggregation(column, fn, alias) {
-        const aggregationSQL = `${fn}(${column}) AS ${alias}`;
+    /**
+     * Appends an aggregate selection (marked `isAggregate`, so GROUP BY
+     * inference never treats it as a grouping key) and infers GROUP BY from any
+     * plain selections already present.
+     */
+    appendAggregateSelection(aggregationSQL) {
         const query = this.builder.getQueryNode();
         if (query.select) {
             return {
@@ -55,6 +59,9 @@ export class AggregationFeature {
             select: [this.createAggregateSelection(aggregationSQL)]
         };
     }
+    createAggregation(column, fn, alias) {
+        return this.appendAggregateSelection(`${fn}(${column}) AS ${alias}`);
+    }
     sum(column, alias) {
         return this.createAggregation(column, 'SUM', alias);
     }
@@ -71,18 +78,24 @@ export class AggregationFeature {
         return this.createAggregation(column, 'MAX', alias);
     }
     countDistinct(column, alias) {
-        const aggregationSQL = `COUNT(DISTINCT ${column}) AS ${alias}`;
-        const query = this.builder.getQueryNode();
-        if (query.select) {
-            return {
-                ...query,
-                select: [...query.select, this.createAggregateSelection(aggregationSQL)],
-                groupBy: query.groupBy || this.inferGroupBySelections(query.select),
-            };
+        return this.appendAggregateSelection(`COUNT(DISTINCT ${column}) AS ${alias}`);
+    }
+    argMax(column, argColumn, alias) {
+        return this.appendAggregateSelection(`argMax(${column}, ${argColumn}) AS ${alias}`);
+    }
+    argMin(column, argColumn, alias) {
+        return this.appendAggregateSelection(`argMin(${column}, ${argColumn}) AS ${alias}`);
+    }
+    quantile(column, level, alias) {
+        if (typeof level !== 'number' || !Number.isFinite(level) || level < 0 || level > 1) {
+            throw new Error(`Invalid quantile level ${level}: expected a number between 0 and 1.`);
         }
-        return {
-            ...query,
-            select: [this.createAggregateSelection(aggregationSQL)],
-        };
+        return this.appendAggregateSelection(`quantile(${level})(${column}) AS ${alias}`);
+    }
+    stddev(column, alias) {
+        return this.appendAggregateSelection(`stddevSamp(${column}) AS ${alias}`);
+    }
+    variance(column, alias) {
+        return this.appendAggregateSelection(`varSamp(${column}) AS ${alias}`);
     }
 }

package/dist/core/features/insert-executor.d.ts

@@ -0,0 +1,45 @@
+import type { ClickHouseSettings } from '@clickhouse/client-common';
+import type { AnyInsertState, SchemaDefinition } from '../types/builder-state.js';
+import type { InsertResultSummary } from '../adapters/database-adapter.js';
+import { InsertBuilder } from '../insert-builder.js';
+interface InsertExecutorRunOptions {
+    queryId?: string;
+}
+/**
+ * Prepares rows for JSONEachRow serialization: `Date` values become ISO-8601
+ * strings and `bigint` values become decimal strings (JSON.stringify throws on
+ * bigint). Recurses through arrays and plain objects (Map columns).
+ */
+export declare function normalizeInsertRows<T extends Record<string, unknown>>(rows: T[]): Record<string, unknown>[];
+export interface JsonEachRowInsertOptions {
+    /** Explicit column subset; omitted columns take table DEFAULTs. */
+    columns?: string[];
+    /** Merged over the default `date_time_input_format: 'best_effort'`. */
+    clickhouseSettings?: ClickHouseSettings;
+}
+/**
+ * Renders a complete `INSERT INTO ... FORMAT JSONEachRow` statement with the
+ * row payload inlined as newline-delimited JSON.
+ *
+ * Exported for `DatabaseAdapter` authors (e.g. embedded engines like chDB) so
+ * a custom `insert` implementation stays byte-identical with the built-in
+ * adapter: rows are normalized the same way (see {@link normalizeInsertRows})
+ * and `date_time_input_format='best_effort'` is inlined in the SETTINGS clause
+ * by default so DateTime columns accept the normalized ISO timestamps.
+ *
+ * @example
+ * ```ts
+ * async insert(table, rows, options) {
+ *   await runSql(buildJsonEachRowInsert(table, rows, options));
+ *   return { queryId: '', executed: true };
+ * }
+ * ```
+ */
+export declare function buildJsonEachRowInsert(table: string, rows: ReadonlyArray<Record<string, unknown>>, options?: JsonEachRowInsertOptions): string;
+export declare class InsertExecutorFeature<Schema extends SchemaDefinition<Schema>, State extends AnyInsertState> {
+    private builder;
+    constructor(builder: InsertBuilder<Schema, State>);
+    execute(options?: InsertExecutorRunOptions): Promise<InsertResultSummary>;
+}
+export {};
+//# sourceMappingURL=insert-executor.d.ts.map

package/dist/core/features/insert-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-executor.d.ts","sourceRoot":"","sources":["../../../src/core/features/insert-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAOrD,UAAU,wBAAwB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA+BD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,IAAI,EAAE,CAAC,EAAE,GACR,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAE3B;AAED,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAaD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5C,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAeR;AAED,qBAAa,qBAAqB,CAChC,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,cAAc;IAEhB,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC;IAEnD,OAAO,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAkEhF"}

package/dist/core/features/insert-executor.js

@@ -0,0 +1,144 @@
+import { logger } from '../utils/logger.js';
+import { assertSafeIdentifier, assertSafeInsertIdentifiers, } from '../utils/insert-identifiers.js';
+function normalizeInsertValue(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        // JSON.stringify would silently coerce NaN/Infinity to null.
+        throw new Error(`Cannot insert non-finite number ${value}: JSON serialization would coerce it to null.`);
+    }
+    if (Array.isArray(value)) {
+        return value.map(normalizeInsertValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto === Object.prototype || proto === null) {
+            const normalized = {};
+            for (const [key, entry] of Object.entries(value)) {
+                normalized[key] = normalizeInsertValue(entry);
+            }
+            return normalized;
+        }
+    }
+    return value;
+}
+/**
+ * Prepares rows for JSONEachRow serialization: `Date` values become ISO-8601
+ * strings and `bigint` values become decimal strings (JSON.stringify throws on
+ * bigint). Recurses through arrays and plain objects (Map columns).
+ */
+export function normalizeInsertRows(rows) {
+    return rows.map(row => normalizeInsertValue(row));
+}
+function renderSettingValue(value) {
+    if (typeof value === 'number') {
+        return String(value);
+    }
+    if (typeof value === 'boolean') {
+        return value ? '1' : '0';
+    }
+    const escaped = String(value).replace(/\\/g, '\\\\').replace(/'/g, "''");
+    return `'${escaped}'`;
+}
+/**
+ * Renders a complete `INSERT INTO ... FORMAT JSONEachRow` statement with the
+ * row payload inlined as newline-delimited JSON.
+ *
+ * Exported for `DatabaseAdapter` authors (e.g. embedded engines like chDB) so
+ * a custom `insert` implementation stays byte-identical with the built-in
+ * adapter: rows are normalized the same way (see {@link normalizeInsertRows})
+ * and `date_time_input_format='best_effort'` is inlined in the SETTINGS clause
+ * by default so DateTime columns accept the normalized ISO timestamps.
+ *
+ * @example
+ * ```ts
+ * async insert(table, rows, options) {
+ *   await runSql(buildJsonEachRowInsert(table, rows, options));
+ *   return { queryId: '', executed: true };
+ * }
+ * ```
+ */
+export function buildJsonEachRowInsert(table, rows, options) {
+    assertSafeInsertIdentifiers(table, options?.columns);
+    Object.keys(options?.clickhouseSettings ?? {})
+        .forEach(key => assertSafeIdentifier(key, 'setting'));
+    const normalized = normalizeInsertRows([...rows]);
+    const columnsSql = options?.columns?.length ? ` (${options.columns.join(', ')})` : '';
+    const settings = {
+        date_time_input_format: 'best_effort',
+        ...options?.clickhouseSettings,
+    };
+    const settingsSql = Object.entries(settings)
+        .map(([key, value]) => `${key}=${renderSettingValue(value)}`)
+        .join(', ');
+    const payload = normalized.map(row => JSON.stringify(row)).join('\n');
+    return `INSERT INTO ${table}${columnsSql} SETTINGS ${settingsSql} FORMAT JSONEachRow\n${payload}`;
+}
+export class InsertExecutorFeature {
+    builder;
+    constructor(builder) {
+        this.builder = builder;
+    }
+    async execute(options) {
+        const queryNode = this.builder.getQueryNode();
+        if (!this.builder.hasValues()) {
+            throw new Error('No values provided. Call .values() before .execute().');
+        }
+        const adapter = this.builder.getAdapter();
+        if (!adapter.insert) {
+            throw new Error(`Inserts are not supported by adapter "${adapter.name}". Implement DatabaseAdapter.insert to enable them.`);
+        }
+        if (queryNode.rows.length === 0) {
+            // An explicit empty batch sends no request, mirroring the native client.
+            return { queryId: '', executed: false };
+        }
+        // Synthetic statement for logs only — row data is never serialized into logs.
+        const tableName = this.builder.getTableName();
+        assertSafeInsertIdentifiers(tableName, queryNode.columns);
+        const columnsSql = queryNode.columns?.length ? ` (${queryNode.columns.join(', ')})` : '';
+        const renderSql = `INSERT INTO ${tableName}${columnsSql} FORMAT JSONEachRow /* ${queryNode.rows.length} rows */`;
+        const startTime = Date.now();
+        logger.logQuery({
+            query: renderSql,
+            startTime,
+            status: 'started',
+            queryId: options?.queryId,
+        });
+        try {
+            const rows = normalizeInsertRows(queryNode.rows);
+            const result = await adapter.insert(tableName, rows, {
+                clickhouseSettings: queryNode.settings,
+                queryId: options?.queryId,
+                columns: queryNode.columns,
+            });
+            const endTime = Date.now();
+            logger.logQuery({
+                query: renderSql,
+                startTime,
+                endTime,
+                duration: endTime - startTime,
+                status: 'completed',
+                rowCount: queryNode.rows.length,
+                queryId: result.queryId || options?.queryId,
+            });
+            return result;
+        }
+        catch (error) {
+            const endTime = Date.now();
+            logger.logQuery({
+                query: renderSql,
+                startTime,
+                endTime,
+                duration: endTime - startTime,
+                status: 'error',
+                error: error,
+                queryId: options?.queryId,
+            });
+            throw error;
+        }
+    }
+}

package/dist/core/insert-builder.d.ts

@@ -0,0 +1,72 @@
+import type { ClickHouseSettings } from '@clickhouse/client-common';
+import type { DatabaseAdapter, InsertResultSummary } from './adapters/database-adapter.js';
+import type { InsertQueryNode } from '../types/index.js';
+import type { SchemaDefinition, InsertState, InitialInsertState, UpdateInsertRow } from './types/builder-state.js';
+import type { InsertRowForColumns } from '../types/insert.js';
+export interface InsertExecuteOptions {
+    queryId?: string;
+}
+/**
+ * A type-safe insert builder for ClickHouse tables.
+ * The builder carries a single state object that encodes the schema, target
+ * table, and accepted row shape.
+ *
+ * Row shapes are derived from the schema: `Nullable(...)` columns are optional,
+ * every other column is required. Use {@link columns} to insert a subset of
+ * columns and let ClickHouse fill table DEFAULTs for the rest.
+ *
+ * Instances are immutable — every method returns a new builder.
+ *
+ * @example
+ * ```ts
+ * await db.insert('events')
+ *   .values([{ id: 1, name: 'signup', created_at: new Date() }])
+ *   .execute();
+ * ```
+ */
+export declare class InsertBuilder<Schema extends SchemaDefinition<Schema>, State extends InsertState<Schema, keyof Schema, any>> {
+    private query;
+    private tableName;
+    private state;
+    private executor;
+    private adapter;
+    private valuesProvided;
+    constructor(tableName: string, state: State, adapter: DatabaseAdapter, query?: InsertQueryNode);
+    private fork;
+    private updateQuery;
+    /**
+     * Restricts the insert to a subset of columns. Omitted columns take their
+     * table DEFAULT values. Must be called before {@link values}.
+     *
+     * @example
+     * ```ts
+     * await db.insert('events')
+     *   .columns(['id', 'name'])
+     *   .values([{ id: 1, name: 'a' }])
+     *   .execute();
+     * ```
+     */
+    columns<K extends Extract<keyof Schema[State['table']], string>>(columns: readonly K[]): InsertBuilder<Schema, UpdateInsertRow<State, InsertRowForColumns<Schema[State['table']], K>>>;
+    /**
+     * Adds one row or an array of rows to insert. Can be chained; rows accumulate.
+     *
+     * An explicit empty array is a valid no-op batch: `execute()` sends no
+     * request and resolves `{ executed: false }`, mirroring the native client.
+     */
+    values(rows: State['row'] | ReadonlyArray<State['row']>): this;
+    /**
+     * Merges ClickHouse settings applied to this insert
+     * (e.g. `{ async_insert: 1, wait_for_async_insert: 1 }`).
+     */
+    settings(opts: ClickHouseSettings): this;
+    getTableName(): string;
+    getAdapter(): DatabaseAdapter;
+    getQueryNode(): InsertQueryNode;
+    hasValues(): boolean;
+    /**
+     * Executes the insert through the adapter's native insert path (JSONEachRow).
+     */
+    execute(options?: InsertExecuteOptions): Promise<InsertResultSummary>;
+}
+export type InsertQB<Schema extends SchemaDefinition<Schema>, Table extends keyof Schema> = InsertBuilder<Schema, InitialInsertState<Schema, Table>>;
+//# sourceMappingURL=insert-builder.d.ts.map

package/dist/core/insert-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insert-builder.d.ts","sourceRoot":"","sources":["../../src/core/insert-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC3F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAI9D,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa,CACxB,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,WAAW,CAAC,MAAM,EAAE,MAAM,MAAM,EAAE,GAAG,CAAC;IAEpD,OAAO,CAAC,KAAK,CAAkB;IAC/B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,cAAc,CAAS;gBAG7B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,eAAe,EACxB,KAAK,CAAC,EAAE,eAAe;IASzB,OAAO,CAAC,IAAI;IAcZ,OAAO,CAAC,WAAW;IAInB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,EAC7D,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,aAAa,CAAC,MAAM,EAAE,eAAe,CAAC,KAAK,EAAE,mBAAmB,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAchG;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI;IAU9D;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI;IAQxC,YAAY;IAIZ,UAAU,IAAI,eAAe;IAI7B,YAAY,IAAI,eAAe;IAI/B,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAGtE;AAED,MAAM,MAAM,QAAQ,CAClB,MAAM,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACvC,KAAK,SAAS,MAAM,MAAM,IACxB,aAAa,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC"}

package/dist/core/insert-builder.js

@@ -0,0 +1,109 @@
+import { cloneInsertQueryNode, createInsertQueryNode } from './query-node.js';
+import { InsertExecutorFeature } from './features/insert-executor.js';
+/**
+ * A type-safe insert builder for ClickHouse tables.
+ * The builder carries a single state object that encodes the schema, target
+ * table, and accepted row shape.
+ *
+ * Row shapes are derived from the schema: `Nullable(...)` columns are optional,
+ * every other column is required. Use {@link columns} to insert a subset of
+ * columns and let ClickHouse fill table DEFAULTs for the rest.
+ *
+ * Instances are immutable — every method returns a new builder.
+ *
+ * @example
+ * ```ts
+ * await db.insert('events')
+ *   .values([{ id: 1, name: 'signup', created_at: new Date() }])
+ *   .execute();
+ * ```
+ */
+export class InsertBuilder {
+    query;
+    tableName;
+    state;
+    executor;
+    adapter;
+    valuesProvided = false;
+    constructor(tableName, state, adapter, query) {
+        this.tableName = tableName;
+        this.query = query ? cloneInsertQueryNode(query) : createInsertQueryNode();
+        this.state = state;
+        this.adapter = adapter;
+        this.executor = new InsertExecutorFeature(this);
+    }
+    fork(state, query) {
+        const builder = new InsertBuilder(this.tableName, state, this.adapter, query);
+        builder.valuesProvided = this.valuesProvided;
+        return builder;
+    }
+    updateQuery(updater) {
+        return this.fork(this.state, updater(this.query));
+    }
+    /**
+     * Restricts the insert to a subset of columns. Omitted columns take their
+     * table DEFAULT values. Must be called before {@link values}.
+     *
+     * @example
+     * ```ts
+     * await db.insert('events')
+     *   .columns(['id', 'name'])
+     *   .values([{ id: 1, name: 'a' }])
+     *   .execute();
+     * ```
+     */
+    columns(columns) {
+        if (this.query.rows.length > 0) {
+            throw new Error('Call .columns() before .values().');
+        }
+        const nextState = {
+            ...this.state,
+            row: {},
+        };
+        return this.fork(nextState, { ...this.query, columns: [...columns] });
+    }
+    /**
+     * Adds one row or an array of rows to insert. Can be chained; rows accumulate.
+     *
+     * An explicit empty array is a valid no-op batch: `execute()` sends no
+     * request and resolves `{ executed: false }`, mirroring the native client.
+     */
+    values(rows) {
+        const added = (Array.isArray(rows) ? rows : [rows]);
+        const next = this.updateQuery(query => ({
+            ...query,
+            rows: [...query.rows, ...added],
+        }));
+        next.valuesProvided = true;
+        return next;
+    }
+    /**
+     * Merges ClickHouse settings applied to this insert
+     * (e.g. `{ async_insert: 1, wait_for_async_insert: 1 }`).
+     */
+    settings(opts) {
+        return this.updateQuery(query => ({
+            ...query,
+            settings: { ...query.settings, ...opts },
+        }));
+    }
+    // Make needed properties accessible to features
+    getTableName() {
+        return this.tableName;
+    }
+    getAdapter() {
+        return this.adapter;
+    }
+    getQueryNode() {
+        return cloneInsertQueryNode(this.query);
+    }
+    hasValues() {
+        return this.valuesProvided;
+    }
+    /**
+     * Executes the insert through the adapter's native insert path (JSONEachRow).
+     */
+    execute(options) {
+        return this.executor.execute(options);
+    }
+}