Package io.delta.kernel.internal.rowtracking

Class RowTracking

Object

io.delta.kernel.internal.rowtracking.RowTracking

public class RowTracking
extends Object

A collection of helper methods for working with row tracking.

Method Summary

Modifier and Type	Method	Description
static CloseableIterable<Row>	assignBaseRowIdAndDefaultRowCommitVersion(Optional<SnapshotImpl> txnReadSnapshotOpt, Protocol txnProtocol, Optional<Long> winningTxnRowIdHighWatermark, Optional<Long> prevCommitVersion, long currCommitVersion, CloseableIterable<Row> txnDataActions)	Assigns or reassigns baseRowIds and defaultRowCommitVersions to AddFile actions in the provided dataActions.
static boolean	isEnabled(Protocol protocol, Metadata metadata)	Check if row tracking is enabled for reading.
static boolean	isRowTrackingColumn(StructField field)	Checks if the provided field is a row tracking column, i.e., either the row ID or the row commit version column.
static void	throwIfRowTrackingToggled(Metadata oldMetadata, Metadata newMetadata)	Throws an exception if row tracking enablement is toggled between the old and the new metadata.
static List<DomainMetadata>	updateRowIdHighWatermarkIfNeeded(Optional<SnapshotImpl> txnReadSnapshotOpt, Protocol txnProtocol, Optional<Long> winningTxnRowIdHighWatermark, CloseableIterable<Row> txnDataActions, List<DomainMetadata> txnDomainMetadatas, Optional<Long> providedRowIdHighWatermark)	Inserts or updates the DomainMetadata action reflecting the new row ID high watermark when this transaction adds rows and pushed it higher.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

isEnabled

public static boolean isEnabled(Protocol protocol,
 Metadata metadata)

Check if row tracking is enabled for reading.

Parameters:

protocol - the protocol to check

metadata - the metadata to check

Returns:

true if row tracking is enabled

Throws:

IllegalStateException - if row tracking is enabled in metadata but not supported by protocol

isRowTrackingColumn

public static boolean isRowTrackingColumn(StructField field)

Checks if the provided field is a row tracking column, i.e., either the row ID or the row commit version column.

Parameters:

field - the field to check

Returns:

true if the field is a row tracking column, false otherwise

assignBaseRowIdAndDefaultRowCommitVersion

public static CloseableIterable<Row> assignBaseRowIdAndDefaultRowCommitVersion(Optional<SnapshotImpl> txnReadSnapshotOpt,
 Protocol txnProtocol,
 Optional<Long> winningTxnRowIdHighWatermark,
 Optional<Long> prevCommitVersion,
 long currCommitVersion,
 CloseableIterable<Row> txnDataActions)

Assigns or reassigns baseRowIds and defaultRowCommitVersions to AddFile actions in the provided dataActions. This method should be invoked only when the 'rowTracking' feature is supported and is used in two scenarios:

1. Initial Assignment: Assigns row tracking fields to AddFile actions during commit preparation before they are committed.
2. Conflict Resolution: Updates row tracking fields when a transaction conflict occurs. Since the losing transaction gets a new commit version and winning transactions may have increased the row ID high watermark, this method reassigns the fields for the losing transaction using the latest state from winning transactions before retrying the commit.

Parameters:

txnReadSnapshotOpt - the snapshot of the table that this transaction is reading from

txnProtocol - the (updated, if any) protocol that will result from this txn

winningTxnRowIdHighWatermark - the latest row ID high watermark from the winning transactions. Should be empty for initial assignment and present for conflict resolution.

prevCommitVersion - the commit version used by this transaction in the previous commit attempt. Should be empty for initial assignment and present for conflict resolution.

currCommitVersion - the transaction's (latest) commit version

txnDataActions - a CloseableIterable of data actions this txn is trying to commit

Returns:

a CloseableIterable of data actions with baseRowIds and defaultRowCommitVersions assigned or reassigned

updateRowIdHighWatermarkIfNeeded

public static List<DomainMetadata> updateRowIdHighWatermarkIfNeeded(Optional<SnapshotImpl> txnReadSnapshotOpt,
 Protocol txnProtocol,
 Optional<Long> winningTxnRowIdHighWatermark,
 CloseableIterable<Row> txnDataActions,
 List<DomainMetadata> txnDomainMetadatas,
 Optional<Long> providedRowIdHighWatermark)

Inserts or updates the DomainMetadata action reflecting the new row ID high watermark when this transaction adds rows and pushed it higher.

This method should only be called when the 'rowTracking' feature is supported. Similar to assignBaseRowIdAndDefaultRowCommitVersion(java.util.Optional<io.delta.kernel.internal.SnapshotImpl>, io.delta.kernel.internal.actions.Protocol, java.util.Optional<java.lang.Long>, java.util.Optional<java.lang.Long>, long, io.delta.kernel.utils.CloseableIterable<io.delta.kernel.data.Row>), it should be called during the initial row ID assignment or conflict resolution to reflect the change to the row ID high watermark.

Parameters:

txnReadSnapshotOpt - the snapshot of the table that this transaction is reading at

txnProtocol - the (updated, if any) protocol that will result from this txn

winningTxnRowIdHighWatermark - the latest row ID high watermark from the winning transaction. Should be empty for initial assignment and present for conflict resolution.

txnDataActions - a CloseableIterable of data actions this txn is trying to commit

txnDomainMetadatas - a list of domain metadata actions this txn is trying to commit

providedRowIdHighWatermark - Optional row ID high watermark explicitly provided by the transaction builder.

Returns:

Updated list of domain metadata actions for commit

throwIfRowTrackingToggled

public static void throwIfRowTrackingToggled(Metadata oldMetadata,
 Metadata newMetadata)

Throws an exception if row tracking enablement is toggled between the old and the new metadata.