@housekit/orm 0.1.47 → 0.1.49

package/dist/relational.d.ts

@@ -2,10 +2,6 @@ import * as ops from './expressions';
 import * as cond from './modules/conditional';
 import { ClickHouseColumn, type RelationDefinition, type TableDefinition, type CleanSelect } from './core';
 import type { SQLExpression } from './expressions';
-/**
- * Internal map of SQL operators provided to relational query callbacks.
- * These match the standard HouseKit operators but are bundled for ergonomic access.
- */
 declare const operators: {
     eq: typeof ops.eq;
     ne: typeof ops.ne;
@@ -37,16 +33,7 @@ type RelationsOf<TTable> = TTable extends {
 } ? R : {};
 type NormalizedRelations<TTable> = RelationsOf<TTable> extends Record<string, RelationDefinition<any>> ? RelationsOf<TTable> : {};
 type RelationTarget<T> = T extends RelationDefinition<infer TTarget> ? TTarget : never;
-/**
- * Join strategy for relational queries.
- *
- * ClickHouse performance varies significantly depending on the join strategy used,
- * especially in distributed environments.
- */
 export type JoinStrategy = 'auto' | 'standard' | 'global' | 'any' | 'global_any';
-/**
- * Configuration options for the Relational Query API (`findMany`, `findFirst`).
- */
 export type RelationalWith<TTable> = [
     keyof NormalizedRelations<TTable>
 ] extends [never] ? Record<string, boolean | RelationalFindOptions<any>> : {
@@ -68,66 +55,17 @@ type WhereObject<TTable> = TTable extends TableDefinition<infer TCols> ? {
     [K in keyof TCols]?: TCols[K] extends ClickHouseColumn<infer T> ? T | SQLExpression : any;
 } : Record<string, any>;
 export type RelationalFindOptions<TTable = any> = {
-    /**
-     * Filter rows.
-     *
-     * @example
-     * // Object syntax (simplest)
-     * where: { email: 'a@b.com' }
-     * where: { role: 'admin', active: true }
-     *
-     * // Direct expression
-     * where: eq(users.active, true)
-     *
-     * // Callback for complex filters
-     * where: (cols, { eq, and, gt }) => and(eq(cols.role, 'admin'), gt(cols.age, 18))
-     */
     where?: WhereObject<TTable> | SQLExpression | ((columns: TTable extends TableDefinition<infer TCols> ? TCols : any, ops: typeof operators) => SQLExpression);
-    /** Max rows to return */
     limit?: number;
-    /**
-     * Select specific columns. By default all columns are returned.
-     *
-     * @example
-     * columns: { id: true, email: true }
-     */
     columns?: TTable extends TableDefinition<infer TCols> ? {
         [K in keyof TCols]?: boolean;
     } : Record<string, boolean>;
-    /** Rows to skip */
     offset?: number;
-    /**
-     * Sort results. Accepts direct value, array, or callback.
-     *
-     * @example
-     * // Direct
-     * orderBy: desc(users.createdAt)
-     *
-     * // Array
-     * orderBy: [desc(users.createdAt), asc(users.name)]
-     *
-     * // Callback
-     * orderBy: (cols, { desc }) => desc(cols.createdAt)
-     */
     orderBy?: OrderByValue | OrderByValue[] | ((columns: TTable extends TableDefinition<infer TCols> ? TCols : any, fns: {
         asc: typeof ops.asc;
         desc: typeof ops.desc;
     }) => OrderByValue | OrderByValue[]);
-    /**
-     * Include related data. Use `true` for all columns or an object for filtering.
-     *
-     * @example
-     * with: {
-     *   posts: true,                          // All posts
-     *   comments: { limit: 5 },               // Latest 5 comments
-     *   profile: { where: eq(profile.public, true) }  // Only public profile
-     * }
-     */
     with?: RelationalWith<TTable>;
-    /**
-     * Join strategy for distributed clusters.
-     * @default 'auto'
-     */
     joinStrategy?: JoinStrategy;
 };
 type OrderByValue = {
@@ -136,30 +74,10 @@ type OrderByValue = {
 };
 export type RelationalAPI<TSchema extends Record<string, TableDefinition<any>>> = {
     [K in keyof TSchema]: {
-        /** Find multiple records with optional filtering, pagination, and relations */
         findMany: <TOpts extends RelationalFindOptions<TSchema[K]> | undefined>(opts?: TOpts) => Promise<Array<RelationalResult<TSchema[K], TOpts extends RelationalFindOptions<TSchema[K]> ? TOpts['with'] : undefined>>>;
-        /** Find a single record (first match) */
         findFirst: <TOpts extends RelationalFindOptions<TSchema[K]> | undefined>(opts?: TOpts) => Promise<RelationalResult<TSchema[K], TOpts extends RelationalFindOptions<TSchema[K]> ? TOpts['with'] : undefined> | null>;
-        /**
-         * Find a record by its primary key
-         * @example
-         * const user = await db.query.users.findById('uuid-here')
-         * const user = await db.query.users.findById('uuid', { with: { posts: true } })
-         */
         findById: <TOpts extends Omit<RelationalFindOptions<TSchema[K]>, 'where' | 'limit'> | undefined>(id: string | number, opts?: TOpts) => Promise<RelationalResult<TSchema[K], TOpts extends RelationalFindOptions<TSchema[K]> ? TOpts['with'] : undefined> | null>;
     };
 };
-/**
- * Build a modern relational API with ClickHouse-specific optimizations.
- *
- * Key architectural features:
- * - **groupUniqArray Optimization**: Instead of flat-joining which causes row explosion,
- *   HouseKit uses ClickHouse aggregation to fetch nested relations as arrays of tuples.
- * - **Automatic Cluster Handling**: Detects sharded tables and applies GLOBAL JOINs.
- * - **Smart Deduplication**: Merges results in-memory when flat joins are unavoidable.
- *
- * @param client - The ClickHouse client instance.
- * @param schema - The shared schema definition containing all table and relation metadata.
- */
 export declare function buildRelationalAPI<TSchema extends Record<string, TableDefinition<any>>>(client: any, schema?: TSchema): RelationalAPI<TSchema> | undefined;
 export {};

package/dist/relational.js

@@ -0,0 +1,290 @@
+import { ClickHouseQueryBuilder } from './builders/select';
+import * as ops from './expressions';
+import * as cond from './modules/conditional';
+const operators = {
+    eq: ops.eq,
+    ne: ops.ne,
+    gt: ops.gt,
+    gte: ops.gte,
+    lt: ops.lt,
+    lte: ops.lte,
+    inArray: ops.inArray,
+    notInArray: ops.notInArray,
+    between: ops.between,
+    notBetween: ops.notBetween,
+    has: ops.has,
+    hasAll: ops.hasAll,
+    hasAny: ops.hasAny,
+    sql: ops.sql,
+    and: cond.and,
+    or: cond.or,
+    not: cond.not,
+    isNull: cond.isNull,
+    isNotNull: cond.isNotNull,
+    asc: ops.asc,
+    desc: ops.desc,
+};
+function buildJoinCondition(fields, references) {
+    if (!fields || !references || fields.length === 0 || references.length === 0)
+        return null;
+    const pairs = fields.map((f, i) => ops.sql `${f} = ${references[i]}`);
+    const filtered = pairs.filter((p) => Boolean(p));
+    if (filtered.length === 0)
+        return null;
+    if (filtered.length === 1)
+        return filtered[0];
+    return cond.and(...filtered) || null;
+}
+function isDistributedTable(tableDef) {
+    const options = tableDef.$options;
+    return !!(options?.onCluster || options?.shardKey);
+}
+export function buildRelationalAPI(client, schema) {
+    if (!schema)
+        return undefined;
+    const api = {};
+    for (const [tableKey, tableDef] of Object.entries(schema)) {
+        api[tableKey] = {
+            findMany: async (opts) => {
+                let builder = new ClickHouseQueryBuilder(client).from(tableDef);
+                const selectedColumns = opts?.columns;
+                const baseColumns = selectedColumns
+                    ? Object.entries(tableDef.$columns).filter(([key]) => selectedColumns[key] === true)
+                    : Object.entries(tableDef.$columns);
+                const relations = tableDef.$relations;
+                const requestedTopLevel = opts?.with ? Object.entries(opts.with).filter(([, v]) => v) : [];
+                const requestedRelations = requestedTopLevel
+                    .map(([relName, val]) => {
+                    const rel = relations?.[relName];
+                    return { relName, rel, options: typeof val === 'object' ? val : {} };
+                })
+                    .filter((r) => Boolean(r.rel));
+                const needsGrouping = requestedRelations.length > 0;
+                const allColumns = Object.entries(tableDef.$columns);
+                const groupByColumns = needsGrouping ? allColumns.map(([, col]) => col) : [];
+                const joinStrategy = opts?.joinStrategy || 'auto';
+                const isDistributed = isDistributedTable(tableDef);
+                const useGlobal = joinStrategy === 'global' || joinStrategy === 'global_any' || (joinStrategy === 'auto' && isDistributed);
+                const useAny = joinStrategy === 'any' || joinStrategy === 'global_any';
+                function buildNestedSelection(currentTableDef, currentWith, prefix = '', outerJoinStrategy, outerUseGlobal, outerUseAny, columnsFilter) {
+                    let currentSelection = {};
+                    let currentJoins = [];
+                    Object.entries(currentTableDef.$columns).forEach(([key, col]) => {
+                        if (!columnsFilter || columnsFilter[key] === true) {
+                            currentSelection[`${prefix}${key}`] = col;
+                        }
+                    });
+                    if (!currentWith)
+                        return { selection: currentSelection, joins: currentJoins };
+                    const currentRelations = currentTableDef.$relations;
+                    const requestedNested = Object.entries(currentWith)
+                        .map(([relName, val]) => {
+                        const rel = currentRelations?.[relName];
+                        return { relName, rel, options: typeof val === 'object' ? val : {} };
+                    })
+                        .filter((r) => Boolean(r.rel));
+                    for (const { relName, rel, options } of requestedNested) {
+                        const newPrefix = prefix ? `${prefix}_${relName}_` : `${relName}_`;
+                        let relWhere = null;
+                        if (options.where) {
+                            if (typeof options.where === 'function') {
+                                relWhere = options.where(rel.table.$columns, operators);
+                            }
+                            else if (typeof options.where === 'object' && !('toSQL' in options.where)) {
+                                const conditions = Object.entries(options.where).map(([key, value]) => {
+                                    const col = rel.table.$columns[key];
+                                    if (!col)
+                                        throw new Error(`Column '${key}' not found in relation '${relName}'`);
+                                    return ops.eq(col, value);
+                                });
+                                relWhere = conditions.length === 1 ? conditions[0] : cond.and(...conditions);
+                            }
+                            else {
+                                relWhere = options.where;
+                            }
+                        }
+                        let joinCondition = buildJoinCondition(rel.fields, rel.references);
+                        if (joinCondition) {
+                            const joinType = (() => {
+                                const relIsDistributed = isDistributedTable(rel.table);
+                                const useRelGlobal = outerUseGlobal || (outerJoinStrategy === 'auto' && relIsDistributed);
+                                if (useRelGlobal && outerUseAny)
+                                    return builder.globalAnyJoin;
+                                if (useRelGlobal)
+                                    return builder.globalLeftJoin;
+                                if (outerUseAny)
+                                    return builder.anyLeftJoin;
+                                return builder.leftJoin;
+                            })();
+                            if (rel.relation === 'many' && !prefix) {
+                                const relCols = Object.entries(rel.table.$columns);
+                                const tupleArgs = relCols.map(([, col]) => ops.sql `${col}`);
+                                if (relWhere) {
+                                    currentSelection[relName] = ops.sql `groupUniqArrayIf(tuple(${ops.sql.join(tupleArgs, ops.sql `, `)}), ${relWhere})`;
+                                }
+                                else {
+                                    currentSelection[relName] = ops.sql `groupUniqArray(tuple(${ops.sql.join(tupleArgs, ops.sql `, `)}))`;
+                                }
+                            }
+                            else if (relWhere) {
+                                joinCondition = cond.and(joinCondition, relWhere);
+                            }
+                            currentJoins.push({ type: joinType, table: rel.table, on: joinCondition });
+                        }
+                        const nestedResult = buildNestedSelection(rel.table, options.with, newPrefix, outerJoinStrategy, outerUseGlobal, outerUseAny, options.columns);
+                        if (!(rel.relation === 'many' && !prefix)) {
+                            Object.assign(currentSelection, nestedResult.selection);
+                        }
+                        currentJoins.push(...nestedResult.joins);
+                    }
+                    return { selection: currentSelection, joins: currentJoins };
+                }
+                const { selection: flatSelection, joins: allJoins } = buildNestedSelection(tableDef, opts?.with, '', joinStrategy, useGlobal, useAny, opts?.columns);
+                for (const joinDef of allJoins) {
+                    builder = joinDef.type.call(builder, joinDef.table, joinDef.on);
+                }
+                builder = builder.select(flatSelection);
+                if (needsGrouping && groupByColumns.length > 0) {
+                    builder = builder.groupBy(...groupByColumns);
+                }
+                if (opts?.where) {
+                    let whereValue;
+                    if (typeof opts.where === 'function') {
+                        whereValue = opts.where(tableDef.$columns, operators);
+                    }
+                    else if (opts.where && typeof opts.where === 'object' && !('toSQL' in opts.where)) {
+                        const conditions = Object.entries(opts.where).map(([key, value]) => {
+                            const col = tableDef.$columns[key];
+                            if (!col)
+                                throw new Error(`Column '${key}' not found in table`);
+                            return ops.eq(col, value);
+                        });
+                        whereValue = conditions.length === 1 ? conditions[0] : cond.and(...conditions);
+                    }
+                    else {
+                        whereValue = opts.where;
+                    }
+                    builder = builder.where(whereValue);
+                }
+                if (opts?.orderBy) {
+                    const orderByFns = { asc: ops.asc, desc: ops.desc };
+                    const orderByValue = typeof opts.orderBy === 'function'
+                        ? opts.orderBy(tableDef.$columns, orderByFns)
+                        : opts.orderBy;
+                    const orderByArray = Array.isArray(orderByValue) ? orderByValue : [orderByValue];
+                    for (const ob of orderByArray) {
+                        builder = builder.orderBy(ob.col, ob.dir);
+                    }
+                }
+                if (opts?.limit)
+                    builder = builder.limit(opts.limit);
+                if (opts?.offset)
+                    builder = builder.offset(opts.offset);
+                const rows = await builder.then();
+                function reconstructNested(row, currentTableDef, currentWith, prefix = '') {
+                    const result = {};
+                    Object.entries(currentTableDef.$columns).forEach(([key]) => {
+                        result[key] = row[`${prefix}${key}`];
+                    });
+                    if (!currentWith)
+                        return result;
+                    const currentRelations = currentTableDef.$relations;
+                    Object.entries(currentWith).filter(([, v]) => v).forEach(([relName, val]) => {
+                        const rel = currentRelations?.[relName];
+                        if (!rel)
+                            return;
+                        const options = typeof val === 'object' ? val : {};
+                        const newPrefix = prefix ? `${prefix}_${relName}_` : `${relName}_`;
+                        if (rel.relation === 'one') {
+                            const relatedData = reconstructNested(row, rel.table, options.with, newPrefix);
+                            const allNull = Object.values(relatedData).every(v => v === null || v === undefined);
+                            result[relName] = allNull ? null : relatedData;
+                        }
+                        else {
+                            const rawVal = row[relName];
+                            if (Array.isArray(rawVal)) {
+                                const relCols = Object.keys(rel.table.$columns);
+                                let items = rawVal.map((tuple) => {
+                                    const obj = {};
+                                    let allNull = true;
+                                    relCols.forEach((colKey, i) => {
+                                        const v = tuple[i];
+                                        if (v !== null && v !== undefined)
+                                            allNull = false;
+                                        obj[colKey] = v;
+                                    });
+                                    return allNull ? null : obj;
+                                }).filter(Boolean);
+                                if (options.offset)
+                                    items = items.slice(options.offset);
+                                if (options.limit)
+                                    items = items.slice(0, options.limit);
+                                result[relName] = items;
+                            }
+                            else {
+                                const relatedData = reconstructNested(row, rel.table, options.with, newPrefix);
+                                const allNull = Object.values(relatedData).every(v => v === null || v === undefined);
+                                result[relName] = allNull ? [] : [relatedData];
+                            }
+                        }
+                    });
+                    return result;
+                }
+                const results = rows.map((row) => reconstructNested(row, tableDef, opts?.with));
+                if (needsGrouping) {
+                    const grouped = new Map();
+                    const pkCols = Array.isArray(tableDef.$options.primaryKey)
+                        ? tableDef.$options.primaryKey
+                        : [tableDef.$options.primaryKey || Object.keys(tableDef.$columns)[0]];
+                    for (const item of results) {
+                        const id = pkCols.map((col) => {
+                            const val = item[col];
+                            return val instanceof Date ? val.getTime() : String(val);
+                        }).join('|');
+                        if (!grouped.has(id)) {
+                            grouped.set(id, item);
+                        }
+                        else {
+                            const existing = grouped.get(id);
+                            requestedRelations.forEach(({ relName, rel, options }) => {
+                                if (rel.relation === 'many' && Array.isArray(item[relName])) {
+                                    for (const newItem of item[relName]) {
+                                        const isDuplicate = existing[relName].some((x) => JSON.stringify(x) === JSON.stringify(newItem));
+                                        if (!isDuplicate)
+                                            existing[relName].push(newItem);
+                                    }
+                                    if (options.limit)
+                                        existing[relName] = existing[relName].slice(0, options.limit);
+                                }
+                            });
+                        }
+                    }
+                    return Array.from(grouped.values());
+                }
+                return results;
+            },
+            findFirst: async (opts) => {
+                const rows = await api[tableKey].findMany({ ...opts, limit: 1 });
+                return rows[0] ?? null;
+            },
+            findById: async (id, opts) => {
+                const pkOption = tableDef.$options?.primaryKey;
+                const pkCols = pkOption
+                    ? (Array.isArray(pkOption) ? pkOption : [pkOption])
+                    : [Object.keys(tableDef.$columns)[0]];
+                const pkColName = pkCols[0];
+                const pkColumn = tableDef.$columns[pkColName];
+                if (!pkColumn) {
+                    throw new Error(`Primary key column '${pkColName}' not found in table '${tableKey}'`);
+                }
+                const rows = await api[tableKey].findMany({
+                    ...opts,
+                    where: ops.eq(pkColumn, id),
+                    limit: 1
+                });
+                return rows[0] ?? null;
+            }
+        };
+    }
+    return api;
+}

package/dist/relations.js

@@ -0,0 +1,21 @@
+export function relations(table, callback) {
+    const helpers = {
+        one: (relTable, config) => ({
+            relation: 'one',
+            name: relTable.$table,
+            table: relTable,
+            fields: config.fields,
+            references: config.references
+        }),
+        many: (relTable, config = {}) => ({
+            relation: 'many',
+            name: relTable.$table,
+            table: relTable,
+            fields: config.fields,
+            references: config.references
+        })
+    };
+    const defs = callback(helpers);
+    table.$relations = defs;
+    return defs;
+}

package/dist/schema-builder.d.ts

@@ -1,23 +1,3 @@
-/**
- * HouseKit Schema Builder - Fluent API for Table Definitions
- *
- * This module provides a modern fluent syntax for defining tables using
- * a builder function pattern instead of individual imports.
- *
- * @example
- * ```typescript
- * import { defineTable, t } from '@housekit/orm';
- *
- * // Using the builder function pattern
- * export const users = defineTable('users', (t) => ({
- *     id: t.uuid('id').primaryKey(),
- *     name: t.string('name'),
- *     email: t.string('email'),
- *     age: t.int32('age').nullable(),
- *     createdAt: t.datetime('created_at').default('now()'),
- * }), { engine: Engine.MergeTree(), orderBy: 'createdAt' });
- * ```
- */
 import { ClickHouseColumn } from './column';
 import { chView, type TableOptions, type TableDefinition, type RelationDefinition, index, projection } from './table';
 import { chMaterializedView, detectMaterializedViewDrift, extractMVQuery, createMigrationBridge, generateBlueGreenMigration } from './materialized-views';
@@ -26,46 +6,17 @@ import { chDictionary } from './dictionary';
 import { chProjection } from './materialized-views';
 import { EngineConfiguration } from './engines';
 export { index };
-/**
- * Enhanced table options with column key references for orderBy, partitionBy, etc.
- */
 export type EnhancedTableOptions<TColKeys extends string = string> = Omit<TableOptions, 'orderBy' | 'partitionBy' | 'primaryKey' | 'sampleBy' | 'deduplicateBy' | 'versionColumn' | 'logicalPrimaryKey' | 'engine'> & {
     engine: EngineConfiguration;
     customEngine?: string;
-    /**
-     * Column(s) for ORDER BY. Can use column keys from your definition.
-     * @example orderBy: 'timestamp' or orderBy: ['user_id', 'timestamp']
-     */
     orderBy?: TColKeys | TColKeys[] | string | string[];
-    /**
-     * Column(s) for PARTITION BY. Can use column keys from your definition.
-     */
     partitionBy?: TColKeys | TColKeys[] | string | string[];
-    /**
-     * Column(s) for PRIMARY KEY. Can use column keys from your definition.
-     */
     primaryKey?: TColKeys | TColKeys[] | string | string[];
-    /**
-     * Column(s) for SAMPLE BY. Can use column keys from your definition.
-     */
     sampleBy?: TColKeys | TColKeys[] | string | string[];
-    /**
-     * Column(s) for deduplication (ReplacingMergeTree).
-     */
     deduplicateBy?: TColKeys | TColKeys[] | string | string[];
-    /**
-     * Version column for ReplacingMergeTree.
-     */
     versionColumn?: TColKeys | string;
-    /**
-     * Logical primary key (for documentation, not enforced).
-     */
     logicalPrimaryKey?: TColKeys | TColKeys[] | string | string[];
 };
-/**
- * ClickHouse data types builder.
- * All columns are NOT NULL by default, following ClickHouse philosophy.
- */
 declare function primaryUuid(): {
     id: ClickHouseColumn<string, true, true>;
 };
@@ -82,10 +33,6 @@ export declare const t: {
     int8: (name: string) => ClickHouseColumn<number, true, false>;
     int16: (name: string) => ClickHouseColumn<number, true, false>;
     integer: (name: string) => ClickHouseColumn<number, true, false>;
-    /**
-     * Int32 type. Signed 32-bit integer.
-     * @range -2147483648 to 2147483647
-     */
     int32: (name: string) => ClickHouseColumn<number, true, false>;
     int64: (name: string) => ClickHouseColumn<number, true, false>;
     int128: (name: string) => ClickHouseColumn<number, true, false>;
@@ -114,10 +61,6 @@ export declare const t: {
     date: (name: string) => ClickHouseColumn<string | Date, true, false>;
     date32: (name: string) => ClickHouseColumn<string | Date, true, false>;
     timestamp: (name: string, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
-    /**
-     * DateTime type. Stores date and time.
-     * @param timezone - Optional. Example: 'UTC', 'Europe/Madrid'
-     */
     datetime: (name: string, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
     datetime64: (name: string, precision?: number, timezone?: string) => ClickHouseColumn<string | Date, true, false>;
     boolean: (name: string) => ClickHouseColumn<boolean, true, false>;
@@ -131,11 +74,6 @@ export declare const t: {
     nested: (name: string, fields: Record<string, string>) => ClickHouseColumn<any, true, false>;
     json: <TSchema = Record<string, any>>(name: string) => ClickHouseColumn<TSchema, false, false>;
     dynamic: (name: string, maxTypes?: number) => ClickHouseColumn<any, true, false>;
-    /**
-     * LowCardinality type. Optimizes columns with few unique values
-     * (typically < 10,000) for ultra-fast reading.
-     * @see https://clickhouse.com/docs/en/sql-reference/data-types/lowcardinality
-     */
     lowCardinality: <T, TNotNull extends boolean, TAutoGenerated extends boolean>(col: ClickHouseColumn<T, TNotNull, TAutoGenerated>) => ClickHouseColumn<T, TNotNull, TAutoGenerated>;
     aggregateFunction: (name: string, funcName: string, ...argTypes: string[]) => ClickHouseColumn<any, true, false>;
     simpleAggregateFunction: (name: string, funcName: string, argType: string) => ClickHouseColumn<any, true, false>;
@@ -144,44 +82,19 @@ export declare const t: {
     polygon: (name: string) => ClickHouseColumn<[number, number][][], true, false>;
     multiPolygon: (name: string) => ClickHouseColumn<[number, number][][][], true, false>;
     enum: (name: string, values: readonly string[]) => ClickHouseColumn<string, false, false>;
-    /**
-     * Adds 'created_at' and 'updated_at' columns with default now().
-     */
     timestamps: () => {
         created_at: ClickHouseColumn<string | Date, true, true>;
         updated_at: ClickHouseColumn<string | Date, true, true>;
     };
-    /**
-     * Adds a standard UUID primary key column (default: 'id').
-     */
     primaryUuid: typeof primaryUuid;
-    /**
-     * Adds a UUID v7 primary key column (default: 'id').
-     */
     primaryUuidV7: typeof primaryUuidV7;
-    /**
-     * Adds 'is_deleted' and 'deleted_at' columns for soft deletes.
-     */
     softDeletes: () => {
         is_deleted: ClickHouseColumn<boolean, true, true>;
         deleted_at: ClickHouseColumn<string | Date, false, false>;
     };
 };
 export type ColumnBuilder = typeof t;
-/**
- * Define a strongly-typed ClickHouse table.
- *
- * @param name - Physical table name in ClickHouse.
- * @param columns - Column definition object or callback using `t` builder.
- * @param options - Engine configuration, sorting keys, partitioning, etc.
- */
 export declare function defineTable<T extends Record<string, ClickHouseColumn<any, any, any>>>(tableName: string, columnsOrCallback: T | ((t: ColumnBuilder) => T), options: EnhancedTableOptions<keyof T & string>): TableDefinition<T, TableOptions>;
-/**
- * Aliases for modern API - providing both short and explicit naming.
- *
- * NOTE: defineTable is the preferred explicit naming for library consistency,
- * while 'table' is provided as a shorthand similar to other ORMs.
- */
 export declare const table: typeof defineTable;
 export declare const view: typeof chView;
 export declare const defineView: typeof chView;
@@ -191,9 +104,6 @@ export declare const dictionary: typeof chDictionary;
 export declare const defineDictionary: typeof chDictionary;
 export { projection };
 export { chProjection as defineProjection };
-/**
- * Define relations for a table using a callback pattern.
- */
 export declare function relations<TTable extends TableDefinition<any>, TRelations extends Record<string, RelationDefinition<any>>>(table: TTable, relationsBuilder: (helpers: {
     one: <TTarget extends TableDefinition<any>>(table: TTarget, config: {
         fields: ClickHouseColumn<any, any, any>[];