ts-prorm-orm 1.1.0 → 1.2.0

package/dist/dialects/databricks/index.js

@@ -52,6 +52,46 @@ class DatabricksDialect extends index_1.MySQLDialect {
         // Databricks SQL Warehouses are reached over HTTPS on port 443.
         super({ port: 443, ...config });
         this.name = 'databricks';
+        this.unityCatalog = config.catalog;
+        this.unitySchema = config.schema;
+    }
+    /**
+     * 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, schema) {
+        const raw = String(tableName ?? '');
+        if (raw.includes('.')) {
+            // Already qualified — quote each segment, don't double-prefix.
+            return raw.split('.').map((p) => this.escapeId(p)).join('.');
+        }
+        const effectiveSchema = schema ?? this.unitySchema;
+        if (this.unityCatalog) {
+            const parts = [this.escapeId(this.unityCatalog), this.escapeId(effectiveSchema ?? 'default')];
+            parts.push(this.escapeId(raw));
+            return parts.join('.');
+        }
+        if (effectiveSchema) {
+            return `${this.escapeId(effectiveSchema)}.${this.escapeId(raw)}`;
+        }
+        return this.escapeId(raw);
+    }
+    /**
+     * 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.
+     */
+    qualifiedTable(tableName, schema) {
+        return this.quoteTable(tableName, schema);
     }
     /**
      * Map an ORM {@link DataType} to a Spark SQL / Delta type. The key
@@ -176,7 +216,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
         if (options?.ifNotExists) {
             sql += ' IF NOT EXISTS';
         }
-        sql += ` ${this.escapeId(tableName)} (${columnDefs.join(', ')})`;
+        sql += ` ${this.qualifiedTable(tableName)} (${columnDefs.join(', ')})`;
         // Data source / format. Delta is the default when unspecified.
         const format = options?.using || 'DELTA';
         sql += ` USING ${format}`;
@@ -218,7 +258,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
         if (options?.ifNotExists) {
             sql += ' IF NOT EXISTS';
         }
-        sql += ` ${this.escapeId(tableName)}`;
+        sql += ` ${this.qualifiedTable(tableName)}`;
         sql += ` USING ${options?.using || 'DELTA'}`;
         if (options?.partitionedBy && options.partitionedBy.length > 0) {
             sql += ` PARTITIONED BY (${options.partitionedBy.map((c) => this.escapeId(c)).join(', ')})`;
@@ -288,7 +328,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
         const updateFields = options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
             ? options.updateOnDuplicate
             : columns.filter((c) => !conflictFields.includes(c));
-        const target = this.escapeId(tableName);
+        const target = this.qualifiedTable(tableName);
         let sql = `MERGE INTO ${target} AS target USING (SELECT ${sourceSelect}) AS source ON ${onClause}`;
         if (updateFields.length > 0) {
             const setClause = updateFields
@@ -386,7 +426,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
      * `ADD COLUMN col ...`.
      */
     buildAddColumnSql(tableName, columnName, definition) {
-        return `ALTER TABLE ${this.escapeId(tableName)} ADD COLUMNS (${this.buildAddColumnSpecSql(columnName, definition)})`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} ADD COLUMNS (${this.buildAddColumnSpecSql(columnName, definition)})`;
     }
     async addColumn(tableName, columnName, definition) {
         await this.query(this.buildAddColumnSql(tableName, columnName, definition));
@@ -397,7 +437,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
      * MySQL, so behaviourally inherited but surfaced as a sync builder for tests.
      */
     buildDropColumnSql(tableName, columnName) {
-        return `ALTER TABLE ${this.escapeId(tableName)} DROP COLUMN ${this.escapeId(columnName)}`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} DROP COLUMN ${this.escapeId(columnName)}`;
     }
     async removeColumn(tableName, columnName) {
         await this.query(this.buildDropColumnSql(tableName, columnName));
@@ -408,7 +448,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
      * re-stating the type). This override needs no `DESCRIBE` round-trip.
      */
     buildRenameColumnSql(tableName, oldColumnName, newColumnName) {
-        return `ALTER TABLE ${this.escapeId(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} RENAME COLUMN ${this.escapeId(oldColumnName)} TO ${this.escapeId(newColumnName)}`;
     }
     async renameColumn(tableName, oldColumnName, newColumnName) {
         await this.query(this.buildRenameColumnSql(tableName, oldColumnName, newColumnName));
@@ -427,7 +467,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
     }
     /** Build `ALTER TABLE t ALTER COLUMN col COMMENT '...'` (Delta-supported). */
     buildSetColumnCommentSql(tableName, columnName, comment) {
-        return `ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} COMMENT ${this.escape(comment)}`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} ALTER COLUMN ${this.escapeId(columnName)} COMMENT ${this.escape(comment)}`;
     }
     async setColumnComment(tableName, columnName, comment) {
         await this.query(this.buildSetColumnCommentSql(tableName, columnName, comment));
@@ -437,7 +477,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
      */
     buildSetColumnNullabilitySql(tableName, columnName, notNull) {
         const action = notNull ? 'SET NOT NULL' : 'DROP NOT NULL';
-        return `ALTER TABLE ${this.escapeId(tableName)} ALTER COLUMN ${this.escapeId(columnName)} ${action}`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} ALTER COLUMN ${this.escapeId(columnName)} ${action}`;
     }
     async setColumnNullability(tableName, columnName, notNull) {
         await this.query(this.buildSetColumnNullabilitySql(tableName, columnName, notNull));
@@ -452,7 +492,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
         if (options?.ifExists) {
             sql += ' IF EXISTS';
         }
-        sql += ` ${this.escapeId(tableName)}`;
+        sql += ` ${this.qualifiedTable(tableName)}`;
         return sql;
     }
     async dropTable(tableName, options) {
@@ -466,7 +506,7 @@ class DatabricksDialect extends index_1.MySQLDialect {
         const props = Object.entries(properties)
             .map(([k, v]) => `'${k}'=${this.escape(v)}`)
             .join(', ');
-        return `ALTER TABLE ${this.escapeId(tableName)} SET TBLPROPERTIES (${props})`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} SET TBLPROPERTIES (${props})`;
     }
     async setTableProperties(tableName, properties) {
         await this.query(this.buildSetTablePropertiesSql(tableName, properties));
@@ -474,11 +514,193 @@ class DatabricksDialect extends index_1.MySQLDialect {
     /** Build `ALTER TABLE t UNSET TBLPROPERTIES [IF EXISTS] ('k', ...)`. */
     buildUnsetTablePropertiesSql(tableName, keys, ifExists = false) {
         const list = keys.map((k) => `'${k}'`).join(', ');
-        return `ALTER TABLE ${this.escapeId(tableName)} UNSET TBLPROPERTIES ${ifExists ? 'IF EXISTS ' : ''}(${list})`;
+        return `ALTER TABLE ${this.qualifiedTable(tableName)} UNSET TBLPROPERTIES ${ifExists ? 'IF EXISTS ' : ''}(${list})`;
     }
     async unsetTableProperties(tableName, keys, ifExists = false) {
         await this.query(this.buildUnsetTablePropertiesSql(tableName, keys, ifExists));
     }
+    // ---------------------------------------------------------------------------
+    // Delta Lake operational commands
+    //
+    // Delta's answer to indexing/compaction/retention/history. These are the
+    // ORM-level, no-raw-SQL entry points for the features the index API can't
+    // express (OPTIMIZE/Z-ORDER replaces CREATE INDEX; time travel replaces
+    // ad-hoc snapshot SQL; COPY INTO is the idempotent bulk loader).
+    // ---------------------------------------------------------------------------
+    /**
+     * 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, options) {
+        let sql = `OPTIMIZE ${this.qualifiedTable(tableName)}`;
+        if (options?.where) {
+            sql += ` WHERE ${options.where}`;
+        }
+        if (options?.zorderBy && options.zorderBy.length > 0) {
+            sql += ` ZORDER BY (${options.zorderBy.map((c) => this.escapeId(c)).join(', ')})`;
+        }
+        return sql;
+    }
+    /** Run `OPTIMIZE ... [ZORDER BY ...]` (see {@link buildOptimizeSql}). */
+    async optimize(tableName, options) {
+        await this.query(this.buildOptimizeSql(tableName, options));
+    }
+    /**
+     * 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, options) {
+        let sql = `VACUUM ${this.qualifiedTable(tableName)}`;
+        if (options?.retainHours !== undefined) {
+            sql += ` RETAIN ${Number(options.retainHours)} HOURS`;
+        }
+        if (options?.dryRun) {
+            sql += ' DRY RUN';
+        }
+        return sql;
+    }
+    /** Run `VACUUM ...` (see {@link buildVacuumSql}). */
+    async vacuum(tableName, options) {
+        await this.query(this.buildVacuumSql(tableName, options));
+    }
+    /**
+     * 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, options) {
+        if (options.version === undefined && options.timestamp === undefined) {
+            throw new Error('buildTimeTravelSelectSql requires either `version` or `timestamp`.');
+        }
+        if (options.version !== undefined && options.timestamp !== undefined) {
+            throw new Error('buildTimeTravelSelectSql accepts only one of `version` or `timestamp`, not both.');
+        }
+        const cols = options.columns && options.columns.length > 0
+            ? options.columns.map((c) => this.escapeId(c)).join(', ')
+            : '*';
+        let sql = `SELECT ${cols} FROM ${this.qualifiedTable(tableName)}`;
+        if (options.version !== undefined) {
+            sql += ` VERSION AS OF ${Number(options.version)}`;
+        }
+        else {
+            const ts = options.timestamp instanceof Date ? options.timestamp.toISOString() : String(options.timestamp);
+            sql += ` TIMESTAMP AS OF ${this.escape(ts)}`;
+        }
+        if (options.where) {
+            sql += ` WHERE ${options.where}`;
+        }
+        return sql;
+    }
+    /** Read a historical snapshot via Delta time travel (see {@link buildTimeTravelSelectSql}). */
+    async selectAsOf(tableName, options) {
+        const result = await this.query(this.buildTimeTravelSelectSql(tableName, options));
+        return result.rows;
+    }
+    /**
+     * 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, options) {
+        if (options.version === undefined && options.timestamp === undefined) {
+            throw new Error('buildRestoreSql requires either `version` or `timestamp`.');
+        }
+        let sql = `RESTORE TABLE ${this.qualifiedTable(tableName)}`;
+        if (options.version !== undefined) {
+            sql += ` TO VERSION AS OF ${Number(options.version)}`;
+        }
+        else {
+            const ts = options.timestamp instanceof Date ? options.timestamp.toISOString() : String(options.timestamp);
+            sql += ` TO TIMESTAMP AS OF ${this.escape(ts)}`;
+        }
+        return sql;
+    }
+    /** Restore a Delta table to a prior version/timestamp (see {@link buildRestoreSql}). */
+    async restore(tableName, options) {
+        await this.query(this.buildRestoreSql(tableName, options));
+    }
+    /**
+     * 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, source, options) {
+        let sql = `COPY INTO ${this.qualifiedTable(tableName)} FROM ${this.escape(source)}`;
+        sql += ` FILEFORMAT = ${options.fileFormat}`;
+        if (options.files && options.files.length > 0) {
+            sql += ` FILES = (${options.files.map((f) => this.escape(f)).join(', ')})`;
+        }
+        if (options.pattern) {
+            sql += ` PATTERN = ${this.escape(options.pattern)}`;
+        }
+        if (options.formatOptions && Object.keys(options.formatOptions).length > 0) {
+            const opts = Object.entries(options.formatOptions)
+                .map(([k, v]) => `${this.escape(k)} = ${this.escape(v)}`)
+                .join(', ');
+            sql += ` FORMAT_OPTIONS (${opts})`;
+        }
+        if (options.copyOptions && Object.keys(options.copyOptions).length > 0) {
+            const opts = Object.entries(options.copyOptions)
+                .map(([k, v]) => `${this.escape(k)} = ${this.escape(v)}`)
+                .join(', ');
+            sql += ` COPY_OPTIONS (${opts})`;
+        }
+        return sql;
+    }
+    /** Run a `COPY INTO` bulk load (see {@link buildCopyIntoSql}). */
+    async copyInto(tableName, source, options) {
+        await this.query(this.buildCopyIntoSql(tableName, source, options));
+    }
+    /**
+     * 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, source, options) {
+        const targetAlias = options.targetAlias || 'target';
+        const sourceAlias = options.sourceAlias || 'source';
+        let sql = `MERGE INTO ${this.qualifiedTable(tableName)} AS ${targetAlias}` +
+            ` USING ${source} AS ${sourceAlias}` +
+            ` ON ${options.on}`;
+        if (options.whenMatchedUpdate === 'ALL') {
+            sql += ' WHEN MATCHED THEN UPDATE SET *';
+        }
+        else if (options.whenMatchedUpdate) {
+            const set = Object.entries(options.whenMatchedUpdate)
+                .map(([col, expr]) => `${this.escapeId(col)} = ${expr}`)
+                .join(', ');
+            sql += ` WHEN MATCHED THEN UPDATE SET ${set}`;
+        }
+        if (options.whenMatchedDelete) {
+            sql += ' WHEN MATCHED THEN DELETE';
+        }
+        if (options.whenNotMatchedInsert === 'ALL') {
+            sql += ' WHEN NOT MATCHED THEN INSERT *';
+        }
+        else if (options.whenNotMatchedInsert) {
+            const cols = Object.keys(options.whenNotMatchedInsert).map((c) => this.escapeId(c)).join(', ');
+            const vals = Object.values(options.whenNotMatchedInsert).join(', ');
+            sql += ` WHEN NOT MATCHED THEN INSERT (${cols}) VALUES (${vals})`;
+        }
+        return sql;
+    }
+    /** Run a general Delta `MERGE INTO` (see {@link buildMergeSql}). */
+    async mergeInto(tableName, source, options) {
+        await this.query(this.buildMergeSql(tableName, source, options));
+    }
     async addIndex(_tableName, _indexName, _fields, _options) {
         throw new Error(DatabricksDialect.INDEX_UNSUPPORTED);
     }