Package io.delta.kernel.unitycatalog

Class UCCatalogManagedClient

Object
io.delta.kernel.unitycatalog.UCCatalogManagedClient
@Experimental public class UCCatalogManagedClient extends Object
Client for interacting with Unity Catalog (UC) catalog-managed Delta tables.
See Also:
  • UCClient
  • Snapshot

  • Field Details

  • Constructor Details

    • UCCatalogManagedClient

      public UCCatalogManagedClient(io.delta.storage.commit.uccommitcoordinator.UCClient ucClient)

  • Method Details

    • loadSnapshot

      public io.delta.kernel.Snapshot loadSnapshot(io.delta.kernel.engine.Engine engine, String ucTableId, String tablePath, Optional<Long> versionOpt, Optional<Long> timestampOpt)
      Loads a Kernel Snapshot. If no version is specified, the latest version of the table is loaded.
      Parameters:
      engine - The Delta Kernel Engine to use for loading the table.
      ucTableId - The Unity Catalog table ID, which is a unique identifier for the table in UC.
      tablePath - The path to the Delta table in the underlying storage system.
      versionOpt - The optional version to time-travel to when loading the table. This must be mutually exclusive with timestampOpt.
      timestampOpt - The optional timestamp to time-travel to when loading the table. This must be mutually exclusive with versionOpt.
      Throws:
      IllegalArgumentException - if a negative version or timestamp is provided
      IllegalArgumentException - if both versionOpt and timestampOpt are defined

    • buildCreateTableTransaction

      @Deprecated public io.delta.kernel.transaction.CreateTableTransactionBuilder buildCreateTableTransaction(String ucTableId, String tablePath, io.delta.kernel.types.StructType schema, String engineInfo)
      Deprecated.
      Use buildCreateTableTransaction(String, String, StructType, String, UCTableIdentifier) which automatically finalizes the table.
      Builds a create table transaction for a Unity Catalog managed Delta table.

      Configures the transaction with a UCCatalogManagedCommitter and required table properties for catalog-managed table enablement.

      This assumes the table is being created in a staging location as per UC semantics. Once this transaction is built and committed, creating 000.json, you must call TablesApi::createTable to inform Unity Catalog of the successful table creation.

      Parameters:
      ucTableId - The Unity Catalog table ID.
      tablePath - The staging path to the Delta table.
      schema - The table schema.
      engineInfo - Information about the creating engine.
      Returns:
      A CreateTableTransactionBuilder configured for UC managed tables.

    • buildCreateTableTransaction

      public io.delta.kernel.transaction.CreateTableTransactionBuilder buildCreateTableTransaction(String ucTableId, String tablePath, io.delta.kernel.types.StructType schema, String engineInfo, UCTableIdentifier ucTableIdentifier)
      Builds a create table transaction with automatic UC finalization. When committed, the committer writes 000.json and then calls UC to finalize (promote) the staging table.
      Parameters:
      ucTableIdentifier - Logical UC table identifier for create-time registration.

    • loadCommitRange

      public io.delta.kernel.CommitRange loadCommitRange(io.delta.kernel.engine.Engine engine, String ucTableId, String tablePath, Optional<Long> startVersionOpt, Optional<Long> startTimestampOpt, Optional<Long> endVersionOpt, Optional<Long> endTimestampOpt)
      Loads a Kernel CommitRange for the provided boundaries. If no end boundary is provided, defaults to the latest version.

      A start boundary is required and must be specified using either startVersionOpt or startTimestampOpt. These parameters are mutually exclusive and at least one must be provided.

      Parameters:
      engine - The Delta Kernel Engine to use for loading the table.
      ucTableId - The Unity Catalog table ID, which is a unique identifier for the table in UC.
      tablePath - The path to the Delta table in the underlying storage system.
      startVersionOpt - The optional start version boundary. This must be mutually exclusive with startTimestampOpt. Either this or startTimestampOpt must be provided.
      startTimestampOpt - The optional start timestamp boundary. This must be mutually exclusive with startVersionOpt. Either this or startVersionOpt must be provided.
      endVersionOpt - The optional end version boundary. This must be mutually exclusive with endTimestampOpt.
      endTimestampOpt - The optional end timestamp boundary. This must be mutually exclusive with endVersionOpt.
      Throws:
      IllegalArgumentException - if neither startVersionOpt nor startTimestampOpt is provided
      IllegalArgumentException - if both startVersionOpt and startTimestampOpt are defined
      IllegalArgumentException - if both endVersionOpt and endTimestampOpt are defined
      IllegalArgumentException - if either startVersionOpt or endVersionOpt is provided and is greater than the latest ratified version from UC