Struct TableTransaction

pub struct TableTransaction<'table> { /* private fields */ }

A transaction that can perform multiple operations on a table atomically

TableTransaction allows grouping multiple table operations (like schema updates, appends, overwrites) into a single atomic transaction. The transaction must be committed for changes to take effect.

Type Parameters

• 'table - Lifetime of the reference to the table being modified

Examples

let mut table = // ... get table reference
table.new_transaction(None)
    .add_schema(new_schema)
    .append(data_files)
    .commit()
    .await?;

Implementations

impl<'table> TableTransaction<'table>

pub fn add_schema(self, schema: Schema) -> Self

Adds a new schema to the table

This operation adds a new schema version to the table. The schema ID will be automatically assigned when the transaction is committed.

Arguments

• schema - The new schema to add to the table

Returns

• Self - The transaction builder for method chaining

pub fn set_default_spec(self, spec_id: i32) -> Self

Sets the default partition specification ID for the table

Arguments

• spec_id - The ID of the partition specification to set as default

Returns

• Self - The transaction builder for method chaining

The specified partition specification must already exist in the table metadata.

pub fn append_data(self, files: Vec<DataFile>) -> Self

Appends new data files to the table

This operation adds new data files to the table’s current snapshot. Multiple append operations in the same transaction will be combined.

Arguments

• files - Vector of data files to append to the table

Returns

• Self - The transaction builder for method chaining

Examples

let transaction = table.new_transaction(None)
    .append_data(data_files)
    .commit()
    .await?;

pub fn append_delete(self, files: Vec<DataFile>) -> Self

Appends delete files to the table

This operation adds files that mark records for deletion in the table’s current snapshot. Multiple delete operations in the same transaction will be combined. The delete files specify which records should be removed when reading the table.

Arguments

• files - Vector of delete files to append to the table

Returns

• Self - The transaction builder for method chaining

Examples

let transaction = table.new_transaction(None)
    .append_delete(delete_files)
    .commit()
    .await?;

pub fn replace(self, files: Vec<DataFile>) -> Self

Replaces all data files in the table with new ones

This operation removes all existing data files and replaces them with the provided files. Multiple replace operations in the same transaction will be combined.

Arguments

• files - Vector of data files that will replace the existing ones

Returns

• Self - The transaction builder for method chaining

Examples

let transaction = table.new_transaction(None)
    .replace(new_files)
    .commit()
    .await?;

pub fn replace_with_lineage( self, files: Vec<DataFile>, additional_summary: HashMap<String, String>, ) -> Self

Quickly append files to the table

pub fn update_properties(self, entries: Vec<(String, String)>) -> Self

Updates the table properties with new key-value pairs

This operation adds or updates table properties. Multiple update operations in the same transaction will be combined.

Arguments

• entries - Vector of (key, value) pairs to update in the table properties

Returns

• Self - The transaction builder for method chaining

Examples

let transaction = table.new_transaction(None)
    .update_properties(vec![
        ("write.format.default".to_string(), "parquet".to_string()),
        ("write.metadata.compression-codec".to_string(), "gzip".to_string())
    ])
    .commit()
    .await?;

pub fn set_snapshot_ref(self, entry: (String, SnapshotReference)) -> Self

Sets a snapshot reference for the table

This operation creates or updates a named reference to a specific snapshot, allowing for features like branches and tags.

Arguments

• entry - Tuple of (reference name, snapshot reference) defining the reference

Returns

• Self - The transaction builder for method chaining

Examples

let transaction = table.new_transaction(None)
    .set_snapshot_ref((
        "test-branch".to_string(),
        SnapshotReference {
            snapshot_id: 123,
            retention: SnapshotRetention::default(),
        }
    ))
    .commit()
    .await?;

pub async fn commit(self) -> Result<(), Error>

Commits all operations in this transaction atomically

This method executes all operations in the transaction and updates the table metadata. The changes are atomic - either all operations succeed or none do. After commit, the transaction is consumed and the table is updated with the new metadata.

Returns

• Result<(), Error> - Ok(()) if the commit succeeds, Error if it fails

Errors

Returns an error if:

• Any operation fails to execute
• The catalog update fails
• Cleanup of old data files fails (for replace operations)

Examples

let result = table.new_transaction(None)
    .append(data_files)
    .update_properties(properties)
    .commit()
    .await?;