@dudousxd/nestjs-filter-clickhouse/dist/clickhouse-query.d.ts

ClickHouse adapter for @dudousxd/nestjs-filter: compiles structured filter input to parameterized ClickHouse SQL.

import { ClickHouseParams } from './sql.js';
import type { ClickHouseTable } from './table.js';
/**
 * The part of a ClickHouse client the adapter uses — `@clickhouse/client`'s `ClickHouseClient`
 * satisfies it. Declared structurally so the adapter has no runtime dependency on the driver.
 */
export interface ClickHouseClientLike {
    query(params: {
        query: string;
        query_params?: Record<string, unknown>;
        format?: 'JSONEachRow';
        clickhouse_settings?: Record<string, unknown>;
    }): Promise<{
        json<T = unknown>(): Promise<T>;
    }>;
}
/** A compiled statement: SQL text plus its bound parameters. */
export interface ClickHouseStatement {
    query: string;
    params: Record<string, unknown>;
}
/** One projected output column: its public name and trusted expression. */
export interface ClickHouseProjection {
    name: string;
    expr: string;
}
/**
 * Output columns are aliased with this prefix in the generated SQL and un-prefixed on the way out.
 * ClickHouse resolves aliases inside WHERE and aggregate arguments, so `sum(errors) AS errors` or
 * `lower(provider) AS provider` would otherwise recurse into their own alias.
 */
export declare const ALIAS_PREFIX = "__";
/** Strips {@link ALIAS_PREFIX} from a result row's keys. */
export declare function unalias(row: Record<string, unknown>): Record<string, unknown>;
/**
 * The ClickHouse adapter's query builder: an accumulator of WHERE / HAVING conditions, ordering, a
 * page window and a projection over one {@link ClickHouseTable}, compiled to parameterized SQL.
 *
 * ```ts
 * const q = adapter.query(events);
 * await runner.apply(EventFilter, input, q);
 * q.toSQL();                    // { query, params } — inspect or run with your own client
 * await q.executeAndCount();    // { rows, total } through the adapter's client
 * ```
 */
export declare class ClickHouseQuery<T = Record<string, unknown>> {
    readonly table: ClickHouseTable<T>;
    private readonly client?;
    /** Parameters shared by every fragment of this query (and its count query). */
    readonly params: ClickHouseParams;
    private readonly whereParts;
    private readonly havingParts;
    private readonly order;
    private window;
    private distinctProjection;
    private selection;
    private readonly computed;
    constructor(table: ClickHouseTable<T>, client?: ClickHouseClientLike | undefined);
    /**
     * Adds a WHERE condition (ANDed). The text is trusted SQL: bind client values through
     * {@link bind} — `q.where(\`provider = ${q.bind('String', value)}\`)`.
     */
    where(condition: string | undefined): this;
    /** Adds a HAVING condition (aggregated tables). Same trust rules as {@link where}. */
    having(condition: string | undefined): this;
    /** Binds a value as a typed parameter of this query and returns its placeholder. */
    bind(type: string, value: unknown): string;
    /** Adds a raw ORDER BY term (trusted SQL, e.g. `ts_col DESC`). */
    orderBy(term: string): this;
    /**
     * Orders by a declared field. Resolved when the SQL is compiled: a field the query projects
     * under an alias (a DISTINCT member, a group dimension or measure of an aggregated table) is
     * ordered by that alias, anything else by its expression. NULLs sort as on Postgres — last
     * ascending, first descending.
     */
    orderByField(field: string, direction: 'asc' | 'desc'): this;
    clearOrderBy(): this;
    limit(limit: number | undefined): this;
    offset(offset: number | undefined): this;
    /** `SELECT DISTINCT` of the given members (replaces the projection). */
    distinct(members: ClickHouseProjection[]): this;
    addDistinct(member: ClickHouseProjection): this;
    /**
     * Narrows the projection to these fields. On an aggregated table the selected DIMENSIONS are the
     * GROUP BY, and selected measures narrow which measures are computed.
     */
    select(fields: string[]): this;
    /** Adds a computed expression to the projection under `name`. */
    addComputed(member: ClickHouseProjection): this;
    isDistinct(): boolean;
    getWhere(): string | undefined;
    getHaving(): string | undefined;
    /** The GROUP BY dimensions of an aggregated table: selected dimensions, else the table's default. */
    groupDimensions(): string[];
    private projection;
    private fromWhere;
    private groupHaving;
    private windowSql;
    private orderSql;
    /** The page query. Every client value is in `params`; the text holds only placeholders. */
    toSQL(): ClickHouseStatement;
    /** The total the page is a window of: rows, groups, or distinct tuples. */
    toCountSQL(): ClickHouseStatement;
    private requireClient;
    private run;
    /** Runs the page query; rows are keyed by field name (the alias prefix is stripped). */
    execute(): Promise<T[]>;
    count(): Promise<number>;
    executeAndCount(): Promise<{
        rows: T[];
        total: number;
    }>;
}
//# sourceMappingURL=clickhouse-query.d.ts.map