ts-prorm-orm 1.1.0 → 1.2.0

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

@@ -0,0 +1,397 @@
+/**
+ * Databricks SQL dialect implementation for the TypeScript ORM.
+ *
+ * Databricks SQL is built on Apache Spark SQL and the Delta Lake table format
+ * (a.k.a. the "lakehouse"). It uses backtick-quoted identifiers, exactly like
+ * MySQL/Spark SQL, so this dialect EXTENDS {@link MySQLDialect} purely to reuse
+ * the backtick quoting/escaping scaffolding and the general query-building
+ * skeleton, then overrides the pieces where Spark/Delta grammar genuinely
+ * differs from MySQL. A real deployment would connect over the Databricks SQL
+ * driver (Databricks SQL Warehouse / `@databricks/sql`) rather than mysql2 —
+ * the inherited connection code is not used against a real cluster.
+ *
+ * Notable differences from MySQL that this dialect overrides:
+ *
+ * - Default port is 443 (Databricks SQL Warehouses are reached over HTTPS),
+ *   not 3306.
+ * - CREATE TABLE emits Delta/Spark grammar: `USING DELTA` (the table's data
+ *   source/format, default DELTA; also PARQUET/CSV/JSON/etc.), `PARTITIONED BY
+ *   (cols)`, `CLUSTERED BY (cols) INTO n BUCKETS`, `TBLPROPERTIES (...)`,
+ *   `LOCATION 's3://...'` (external/unmanaged tables), and a trailing
+ *   `COMMENT '...'`. There is no MySQL `ENGINE=`/`ROW_FORMAT=`/charset concept.
+ * - CTAS: {@link DatabricksDialect.buildCreateTableAsSelect} emits
+ *   `CREATE TABLE ... USING DELTA AS SELECT ...`.
+ * - Upsert is expressed as a Delta Lake `MERGE INTO target USING source ON ...
+ *   WHEN MATCHED THEN UPDATE SET ... WHEN NOT MATCHED THEN INSERT ...`
+ *   statement (see {@link DatabricksDialect.buildUpsertQuery}) rather than
+ *   MySQL's `INSERT ... ON DUPLICATE KEY UPDATE`.
+ * - Auto-increment columns use Delta's `GENERATED ALWAYS AS IDENTITY` identity
+ *   columns instead of MySQL's `AUTO_INCREMENT`.
+ * - Type mapping uses Spark SQL types: `STRING` (there is no `VARCHAR`/`TEXT`),
+ *   `BIGINT`, `INT`, `DOUBLE`, `FLOAT`, `BOOLEAN`, `TIMESTAMP`, `DATE`,
+ *   `BINARY`, `DECIMAL(p,s)`, and the complex types `ARRAY<>`, `MAP<>`,
+ *   `STRUCT<>` (see {@link DatabricksDialect.getDataTypeSql}).
+ * - PRIMARY KEY / FOREIGN KEY constraints in Databricks are INFORMATIONAL only
+ *   (they are declared `NOT ENFORCED` and used by the optimizer for query
+ *   planning); they do not enforce uniqueness or referential integrity. This
+ *   dialect emits them inline as informational constraints and never relies on
+ *   them for correctness.
+ */
+import { MySQLDialect, MySQLDialectOptions } from '../mysql/index';
+import { ColumnDefinition, TableOptions, UpsertQueryOptions, InsertOptions, UpdateOptions, DeleteOptions, DropTableOptions, IndexOptions, IndexDefinition } from '../dialect';
+import { DataType, WhereOptions } from '../../types';
+/**
+ * Data source / file format backing a Databricks table (`USING <format>`).
+ * Delta Lake is the default and the only format with full ACID/upsert support.
+ */
+export type DatabricksTableFormat = 'DELTA' | 'PARQUET' | 'CSV' | 'JSON' | 'ORC' | 'AVRO';
+/**
+ * Databricks connection options. Adds Unity Catalog three-level namespace
+ * defaults (`catalog`.`schema`.`table`) on top of the inherited MySQL options.
+ * When a `catalog` is configured, unqualified table names are resolved to
+ * `` `catalog`.`schema`.`table` `` (see {@link DatabricksDialect.quoteTable}).
+ */
+export interface DatabricksDialectOptions extends MySQLDialectOptions {
+    /**
+     * Unity Catalog catalog name (the first level of `catalog.schema.table`).
+     * When set, unqualified names emitted by this dialect are catalog-qualified.
+     */
+    catalog?: string;
+    /**
+     * Default Unity Catalog schema (a.k.a. database — the middle level). Used
+     * when a table name is neither dotted nor given an explicit schema. Defaults
+     * to `'default'` when a catalog is configured but no schema is given.
+     */
+    schema?: string;
+}
+/**
+ * Databricks/Delta-specific CREATE TABLE options layered on top of the shared
+ * {@link TableOptions}. Passed alongside the common options; a plain
+ * `TableOptions` value remains valid since every field here is optional.
+ */
+export interface DatabricksTableOptions extends TableOptions {
+    /** Data source / format for the table (`USING <format>`). Defaults to `'DELTA'`. */
+    using?: DatabricksTableFormat;
+    /** Columns to partition the table's storage by (`PARTITIONED BY (cols)`). */
+    partitionedBy?: string[];
+    /**
+     * Bucketing (hash-clustering) spec: `CLUSTERED BY (cols) INTO n BUCKETS`.
+     * Databricks distributes rows into a fixed number of buckets by hashing the
+     * given columns.
+     */
+    clusteredBy?: {
+        columns: string[];
+        buckets: number;
+    };
+    /**
+     * Delta/Spark table properties (`TBLPROPERTIES ('key'='value', ...)`), e.g.
+     * `{ 'delta.appendOnly': 'true' }`.
+     */
+    tblproperties?: Record<string, string>;
+    /**
+     * Storage location for an external/unmanaged table (`LOCATION 's3://...'`).
+     * When omitted the table is managed by the metastore.
+     */
+    location?: string;
+}
+/**
+ * Databricks SQL dialect. See the file header for the full list of
+ * Spark/Delta-specific overrides.
+ */
+export declare class DatabricksDialect extends MySQLDialect {
+    readonly name = "databricks";
+    /** Configured Unity Catalog catalog (undefined => no catalog qualification). */
+    protected readonly unityCatalog?: string;
+    /** Configured default Unity Catalog schema (database). */
+    protected readonly unitySchema?: string;
+    constructor(config: DatabricksDialectOptions);
+    /**
+     * Quote a table name using Unity Catalog's three-level namespace when a
+     * catalog is configured: `` `catalog`.`schema`.`table` ``.
+     *
+     * - A name that already contains dots (the caller passed a qualified
+     *   `catalog.schema.table` or `schema.table`) is quoted segment-by-segment
+     *   and returned as-is — the caller's qualification always wins.
+     * - An unqualified name is prefixed with the configured catalog and the
+     *   given/`schema` option/`'default'` schema.
+     * - With no catalog configured, behaves like the inherited MySQL/Spark
+     *   backtick quoting (still dot-aware).
+     */
+    quoteTable(tableName: string, schema?: string): string;
+    /**
+     * Resolve a table reference to its fully-qualified, quoted Unity Catalog form.
+     * Thin wrapper over {@link quoteTable} used by the Databricks-specific DDL/DML
+     * builders (which historically emitted a bare `escapeId(table)`), so those
+     * now honor the configured catalog/schema too.
+     */
+    protected qualifiedTable(tableName: string, schema?: string): string;
+    /**
+     * Map an ORM {@link DataType} to a Spark SQL / Delta type. The key
+     * difference from MySQL is that character types collapse to `STRING`
+     * (Spark SQL has no `VARCHAR(n)`/`TEXT`), and the complex types
+     * `ARRAY<>`/`MAP<>`/`STRUCT<>` are supported.
+     */
+    getDataTypeSql(dataType: DataType): string;
+    /**
+     * Resolve the element/value type for a complex (ARRAY/MAP) type, defaulting
+     * to `STRING` when the element type is unspecified.
+     */
+    private getComplexElementType;
+    /**
+     * Build a single column definition for a Databricks CREATE TABLE. Emits
+     * Delta `GENERATED ALWAYS AS IDENTITY` for auto-increment columns and an
+     * informational (not-enforced) inline `PRIMARY KEY` where requested.
+     */
+    buildColumnDefinitionSql(columnName: string, definition: ColumnDefinition): string;
+    /**
+     * Build the `CREATE TABLE` statement using Delta/Spark grammar. Exposed
+     * synchronously (separate from the async {@link createTable}) so callers can
+     * inspect the generated SQL without a live connection.
+     */
+    buildCreateTableSql(tableName: string, columns: Record<string, ColumnDefinition>, options?: DatabricksTableOptions): string;
+    /**
+     * Create a table using Delta/Spark grammar. Delegates SQL generation to
+     * {@link buildCreateTableSql} and executes it.
+     */
+    createTable(tableName: string, columns: Record<string, ColumnDefinition>, options?: DatabricksTableOptions): Promise<void>;
+    /**
+     * Build a `CREATE TABLE ... USING <format> AS SELECT ...` (CTAS) statement.
+     * The column list and types are inferred from the SELECT, so only the format
+     * and (optionally) partitioning/location apply.
+     */
+    buildCreateTableAsSelect(tableName: string, selectQuery: string, options?: Pick<DatabricksTableOptions, 'using' | 'partitionedBy' | 'location' | 'comment' | 'ifNotExists' | 'tblproperties'>): string;
+    /**
+     * Build a Delta Lake `MERGE INTO` upsert. Delta has no MySQL-style
+     * `ON DUPLICATE KEY UPDATE`; instead the row(s) to upsert are supplied as an
+     * inline `source` relation and matched against the target on the conflict
+     * (key) columns:
+     *
+     *   MERGE INTO `t` AS target
+     *   USING (SELECT ? AS `id`, ? AS `name`) AS source
+     *   ON target.`id` = source.`id`
+     *   WHEN MATCHED THEN UPDATE SET target.`name` = source.`name`
+     *   WHEN NOT MATCHED THEN INSERT (`id`, `name`) VALUES (source.`id`, source.`name`)
+     *
+     * @param tableName - Target table.
+     * @param values - Column/value pairs for the row to upsert.
+     * @param options - `conflictFields` picks the ON/match key columns (defaults
+     *   to all columns); `updateOnDuplicate` restricts which columns the
+     *   WHEN MATCHED branch updates (defaults to all non-key columns).
+     */
+    buildUpsertQuery(tableName: string, values: Record<string, unknown>, options?: UpsertQueryOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a `LIMIT`/`OFFSET` tail. Spark SQL supports `LIMIT n` and, since
+     * Spark 3.4 / Databricks Runtime 11+, a standalone `OFFSET n` (with or
+     * without a preceding `LIMIT`). Unlike MySQL there is NO need for the
+     * `LIMIT 18446744073709551615 OFFSET n` sentinel trick — Spark accepts
+     * `OFFSET` on its own — so this override drops that MySQL-only hack.
+     *
+     * NOTE: `OFFSET` is only valid on the outermost query and requires a
+     * recent Spark/DBR; on older runtimes it raises a parser error. For deep
+     * pagination prefer a keyset/`WHERE` predicate over large offsets.
+     */
+    buildLimitOffset(limit?: number | string, offset?: number | string): string;
+    /**
+     * Build an INSERT. A plain insert (`INSERT INTO t (cols) VALUES (...)`) is
+     * valid Spark SQL and reuses the inherited MySQL builder verbatim. When the
+     * caller sets `upsert`, MySQL would emit `... ON DUPLICATE KEY UPDATE`, which
+     * Spark/Delta rejects — so route to a Delta `MERGE INTO` instead.
+     */
+    buildInsertQuery(tableName: string, values: Record<string, unknown>, options?: InsertOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build an UPDATE. Delta Lake supports `UPDATE t SET ... WHERE ...`, but
+     * (unlike MySQL) it does NOT support a trailing `LIMIT` on UPDATE, nor a
+     * `RETURNING` clause. Strip `LIMIT` and reject `RETURNING` rather than emit
+     * SQL Spark would reject.
+     */
+    buildUpdateQuery(tableName: string, values: Record<string, unknown>, where: WhereOptions, options?: UpdateOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Build a DELETE. Delta Lake supports `DELETE FROM t WHERE ...`, but not a
+     * trailing `LIMIT` or `RETURNING`. Strip `LIMIT` and reject `RETURNING`.
+     */
+    buildDeleteQuery(tableName: string, where: WhereOptions, options?: DeleteOptions): {
+        sql: string;
+        values: unknown[];
+    };
+    /**
+     * Column spec for `ALTER TABLE ... ADD COLUMNS`. Spark only accepts
+     * `name type [COMMENT '...']` (optionally `FIRST`/`AFTER col`) here — it does
+     * NOT accept `NOT NULL`, `DEFAULT`, `PRIMARY KEY`, or identity clauses on an
+     * added column, so those are intentionally omitted (unlike the full CREATE
+     * TABLE column definition).
+     */
+    private buildAddColumnSpecSql;
+    /**
+     * Build `ALTER TABLE t ADD COLUMNS (col type ...)`. Spark uses the plural
+     * `ADD COLUMNS (...)` with a parenthesised list — NOT MySQL's singular
+     * `ADD COLUMN col ...`.
+     */
+    buildAddColumnSql(tableName: string, columnName: string, definition: ColumnDefinition): string;
+    addColumn(tableName: string, columnName: string, definition: ColumnDefinition): Promise<void>;
+    /**
+     * Build `ALTER TABLE t DROP COLUMN col`. Valid Delta grammar (requires Delta
+     * column-mapping mode to be enabled on the table); identical in shape to
+     * MySQL, so behaviourally inherited but surfaced as a sync builder for tests.
+     */
+    buildDropColumnSql(tableName: string, columnName: string): string;
+    removeColumn(tableName: string, columnName: string): Promise<void>;
+    /**
+     * Build `ALTER TABLE t RENAME COLUMN old TO new`. Spark/Delta uses
+     * `RENAME COLUMN`; MySQL uses `CHANGE old new <type>` (which also requires
+     * re-stating the type). This override needs no `DESCRIBE` round-trip.
+     */
+    buildRenameColumnSql(tableName: string, oldColumnName: string, newColumnName: string): string;
+    renameColumn(tableName: string, oldColumnName: string, newColumnName: string): Promise<void>;
+    /**
+     * Delta only supports a narrow set of in-place column alterations
+     * (comment, nullability, ordering — and, on recent runtimes, limited type
+     * widening). MySQL's `CHANGE col <full-def>` is not valid Spark SQL, so
+     * rather than emit something a cluster would reject, expose the two
+     * supported primitives explicitly and fail fast on the generic path.
+     */
+    changeColumn(_tableName: string, _columnName: string, _definition: ColumnDefinition): Promise<void>;
+    /** Build `ALTER TABLE t ALTER COLUMN col COMMENT '...'` (Delta-supported). */
+    buildSetColumnCommentSql(tableName: string, columnName: string, comment: string): string;
+    setColumnComment(tableName: string, columnName: string, comment: string): Promise<void>;
+    /**
+     * Build `ALTER TABLE t ALTER COLUMN col SET|DROP NOT NULL` (Delta-supported).
+     */
+    buildSetColumnNullabilitySql(tableName: string, columnName: string, notNull: boolean): string;
+    setColumnNullability(tableName: string, columnName: string, notNull: boolean): Promise<void>;
+    /**
+     * Build `DROP TABLE [IF EXISTS] t`. Spark has no `CASCADE` on `DROP TABLE`
+     * (that's a MySQL/Postgres construct), so the inherited CASCADE handling is
+     * overridden away.
+     */
+    buildDropTableSql(tableName: string, options?: DropTableOptions): string;
+    dropTable(tableName: string, options?: DropTableOptions): Promise<void>;
+    /**
+     * Build `ALTER TABLE t SET TBLPROPERTIES ('k'='v', ...)` — the Delta/Spark
+     * way to change table-level options after creation.
+     */
+    buildSetTablePropertiesSql(tableName: string, properties: Record<string, string>): string;
+    setTableProperties(tableName: string, properties: Record<string, string>): Promise<void>;
+    /** Build `ALTER TABLE t UNSET TBLPROPERTIES [IF EXISTS] ('k', ...)`. */
+    buildUnsetTablePropertiesSql(tableName: string, keys: string[], ifExists?: boolean): string;
+    unsetTableProperties(tableName: string, keys: string[], ifExists?: boolean): Promise<void>;
+    /**
+     * Build `OPTIMIZE table [WHERE ...] [ZORDER BY (cols)]` — Delta's file
+     * compaction command. Z-ordering co-locates related data across the given
+     * columns to make data-skipping effective, and is the closest Delta analog to
+     * a secondary index. `where` restricts compaction to matching partitions.
+     */
+    buildOptimizeSql(tableName: string, options?: {
+        zorderBy?: string[];
+        where?: string;
+    }): string;
+    /** Run `OPTIMIZE ... [ZORDER BY ...]` (see {@link buildOptimizeSql}). */
+    optimize(tableName: string, options?: {
+        zorderBy?: string[];
+        where?: string;
+    }): Promise<void>;
+    /**
+     * Build `VACUUM table [RETAIN n HOURS] [DRY RUN]` — removes data files no
+     * longer referenced by the Delta log and older than the retention window
+     * (default 168 hours / 7 days). Reclaims storage from prior versions; note it
+     * also truncates the time-travel window it removes.
+     */
+    buildVacuumSql(tableName: string, options?: {
+        retainHours?: number;
+        dryRun?: boolean;
+    }): string;
+    /** Run `VACUUM ...` (see {@link buildVacuumSql}). */
+    vacuum(tableName: string, options?: {
+        retainHours?: number;
+        dryRun?: boolean;
+    }): Promise<void>;
+    /**
+     * Build a Delta time-travel `SELECT` reading a historical snapshot of a table
+     * by version number (`VERSION AS OF n`) or timestamp (`TIMESTAMP AS OF '...'`).
+     * Exactly one of `version`/`timestamp` must be given.
+     *
+     *   SELECT * FROM `t` VERSION AS OF 12
+     *   SELECT `a`, `b` FROM `t` TIMESTAMP AS OF '2024-01-01 00:00:00'
+     */
+    buildTimeTravelSelectSql(tableName: string, options: {
+        version?: number;
+        timestamp?: string | Date;
+        columns?: string[];
+        where?: string;
+    }): string;
+    /** Read a historical snapshot via Delta time travel (see {@link buildTimeTravelSelectSql}). */
+    selectAsOf(tableName: string, options: {
+        version?: number;
+        timestamp?: string | Date;
+        columns?: string[];
+        where?: string;
+    }): Promise<unknown[]>;
+    /**
+     * Build `RESTORE TABLE t TO VERSION AS OF n` / `TO TIMESTAMP AS OF '...'` —
+     * roll a Delta table back to a prior version in place.
+     */
+    buildRestoreSql(tableName: string, options: {
+        version?: number;
+        timestamp?: string | Date;
+    }): string;
+    /** Restore a Delta table to a prior version/timestamp (see {@link buildRestoreSql}). */
+    restore(tableName: string, options: {
+        version?: number;
+        timestamp?: string | Date;
+    }): Promise<void>;
+    /**
+     * Build a Databricks `COPY INTO` bulk-load statement — the idempotent,
+     * exactly-once loader from a cloud file location into a Delta table:
+     *
+     *   COPY INTO `t` FROM 's3://bucket/path'
+     *   FILEFORMAT = CSV
+     *   FILES = ('a.csv','b.csv')            -- or PATTERN = '*.csv'
+     *   FORMAT_OPTIONS ('header'='true')
+     *   COPY_OPTIONS ('mergeSchema'='true')
+     */
+    buildCopyIntoSql(tableName: string, source: string, options: {
+        fileFormat: 'CSV' | 'JSON' | 'PARQUET' | 'AVRO' | 'ORC' | 'TEXT' | 'BINARYFILE';
+        files?: string[];
+        pattern?: string;
+        formatOptions?: Record<string, string>;
+        copyOptions?: Record<string, string>;
+    }): string;
+    /** Run a `COPY INTO` bulk load (see {@link buildCopyIntoSql}). */
+    copyInto(tableName: string, source: string, options: Parameters<DatabricksDialect['buildCopyIntoSql']>[2]): Promise<void>;
+    /**
+     * Build a general Delta `MERGE INTO ... USING <source relation> ON ...` that
+     * supports all three action branches — including `WHEN MATCHED THEN DELETE`,
+     * which the single-row {@link buildUpsertQuery} upsert path can't express.
+     * The `source` is a caller-supplied relation (a subquery/table/CTAS alias,
+     * e.g. `staging_updates`); this method wires the ON/action clauses around it.
+     */
+    buildMergeSql(tableName: string, source: string, options: {
+        sourceAlias?: string;
+        targetAlias?: string;
+        on: string;
+        whenMatchedUpdate?: Record<string, string> | 'ALL';
+        whenMatchedDelete?: boolean;
+        whenNotMatchedInsert?: Record<string, string> | 'ALL';
+    }): string;
+    /** Run a general Delta `MERGE INTO` (see {@link buildMergeSql}). */
+    mergeInto(tableName: string, source: string, options: Parameters<DatabricksDialect['buildMergeSql']>[2]): Promise<void>;
+    private static readonly INDEX_UNSUPPORTED;
+    addIndex(_tableName: string, _indexName: string, _fields?: string[], _options?: IndexOptions): Promise<void>;
+    createIndex(_tableName: string, _indexDef: IndexDefinition): Promise<void>;
+    removeIndex(_tableName: string, _indexName: string): Promise<void>;
+    dropIndex(_tableName: string, _indexName: string): Promise<void>;
+    createFulltextIndex(): Promise<void>;
+    createSpatialIndex(): Promise<void>;
+}
+/**
+ * Convenience factory mirroring the other dialects' `create*Dialect` helpers.
+ */
+export declare function createDatabricksDialect(options?: DatabricksDialectOptions): DatabricksDialect;