Package org.apache.spark.sql.connector.catalog.transactions

Interface Transaction

All Superinterfaces:
AutoCloseable, Closeable
@Evolving public interface Transaction extends Closeable
Represents a transaction.

Spark begins a transaction with TransactionalCatalogPlugin.beginTransaction(org.apache.spark.sql.connector.catalog.transactions.TransactionInfo) and executes read/write operations against the transaction's catalog. On success, Spark calls commit(); on failure, Spark calls abort(). In both cases Spark subsequently calls close() to release resources.

Since:
4.2.0

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    abort()
    Aborts the transaction, discarding any staged changes.
    CatalogPlugin
    catalog()
    Returns the catalog associated with this transaction.
    void
    close()
    Releases any resources held by this transaction.
    void
    commit()
    Commits the transaction.
    boolean
    registerScans(Scan[] scans)
    Attempts to register materialized scans against this transaction's read set.

  • Method Details

    • catalog

      CatalogPlugin catalog()
      Returns the catalog associated with this transaction. This catalog is responsible for tracking read/write operations that occur within the boundaries of a transaction. This allows connectors to perform conflict resolution at commit time.

    • commit

      void commit()
      Commits the transaction. All writes performed under it become visible to other readers.

      The connector is responsible for detecting and resolving conflicting commits or throwing an exception if resolution is not possible.

      This method will be called exactly once per transaction. Spark calls close() immediately after this method returns.

      Throws:
      IllegalStateException - if the transaction has already been committed or aborted.

    • abort

      void abort()
      Aborts the transaction, discarding any staged changes.

      This method must be idempotent. If the transaction has already been committed or aborted, invoking it must have no effect.

      Spark calls close() immediately after this method returns.

    • registerScans

      boolean registerScans(Scan[] scans)
      Attempts to register materialized scans against this transaction's read set.

      An example use case is cache reuse. Spark passes the scans of a candidate cached subtree for the transaction's catalog and the connector decides whether to accept them.

      The connector must either accept all passed scans (returning true after adding the scans to the read set) or refuse (returning false without modifying the read set).

      Parameters:
      scans - the materialized scans Spark offers for registration against this transaction's read set.
      Returns:
      true if the connector accepts the scans; false otherwise.

    • close

      void close()
      Releases any resources held by this transaction.

      Spark always calls this method after commit() or abort(), regardless of whether those methods succeed or not.

      This method must be idempotent. If the transaction has already been closed, invoking it must have no effect.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable