Struct Table 

pub struct Table { /* private fields */ }

An exact immutable table version.

Writing a table produces its next version without publishing it: nothing changes in the Catalog until a Commit stages the new version and publishes.

Implementations

impl Table

pub async fn write_blob( &self, media_type: &str, max_bytes: u64, input: BlobStream, ) -> Result<Blob, Error>

Stream a dedicated payload into this Table’s storage before publishing its row.

Enforces max_bytes while consuming the stream. Failure returns no reference; cancellation aborts an active upload when possible. A process crash may leave an unreferenced object for retention cleanup. This does not publish a row.

pub async fn stat_blob(&self, blob: &Blob) -> Result<BlobStat, Error>

What storage holds for an owned payload, without reading its bytes.

pub async fn read_blob( &self, blob: &Blob, range: Option<Range<u64>>, ) -> Result<BlobStream, Error>

Stream an owned payload or range using this client’s current read authorization. A complete read verifies its digest; a range verifies its returned length.

impl Table

pub async fn plan_changes( &self, since: &Table, columns: Option<Vec<String>>, ) -> Result<ChangePlan, Error>

How this version changed since since, from version metadata only: for each fragment, whether since has it at the same positions, with the row IDs patched and deleted since, or whether it was added since, with the row IDs appended since and those a rewrite carried over. columns names the columns whose changes count; all when absent. since must be this version or one of its ancestors.

pub async fn changes_since( &self, since: &Table, options: ChangeOptions, ) -> Result<Scan, Error>

The rows that changed since since, with their ChangeKind and row ID, as one scan.

A row a rewrite carried without changing it is not reported; across an overwrite of the whole table every old row is deleted and every new row inserted. The filter applies to each image, and an update is reported when either image matches. Before images are read from since with the same columns and must have this version’s names and types there. The scan has no splits to read by work item.

impl Table

pub async fn column_writer( &self, fields: SchemaRef, ) -> Result<ColumnWrite, Error>

Begin writing values for new nullable fields of this table, which join its schema in its next version. Rows the write gives no values read NULL, so values may follow over several versions.

pub async fn add_columns( &self, columns: Vec<NamedExpression>, ) -> Result<Table, Error>

Write the next version of this table with a new nullable column for each of columns, filled for every row with the expression’s value over that row.

Each fragment is read in stored order with the expressions as its projection and written whole, several fragments at once.

impl Table

pub async fn merge_rows( &self, source: impl IntoArrowStream, on: &[&str], actions: MergeActions, ) -> Result<MergedRows, Error>

Write the next version of this table with source merged into it by the on columns, as actions say: one version with every patch, deletion and appended row.

The source is held in memory, so a merge suits batches of upserts; join larger sources in DataFusion. Duplicate source keys are an error, and null keys match nothing. One source row may match several table rows and updates all of them. A matched row whose values are unchanged is not written. Unless unmatched table rows are deleted, the table scan is pruned by the bounds of the source’s integer and string keys. When nothing changes, nothing is written and the result holds this table.

impl Table

pub fn identity(&self) -> TableIdentity

Exact immutable identity selected by this handle.

pub fn resolved_address(&self) -> Option<&ResourceAddress>

Canonical path@v<version> provenance, when opened through a resource path. Tables opened by IDs, and versions written from a table, have no resource path.

pub async fn maintain(&self, run: Run) -> Result<Option<TaskHandle>, Error>

Submit maintenance of this table’s latest version on the branch it was opened from.

Maintenance compacts and reclusters, publishing each step as a new version; its result lists them. Returns None when maintenance of this table and branch is already waiting to run.

pub async fn scan(&self, options: ScanOptions) -> Result<Scan, Error>

Open a scan with fixed projection, predicate, schema, and execution binding.

Metadata is resolved once. Batches are read when its streams are polled.

pub async fn append(&self, input: impl IntoArrowStream) -> Result<Table, Error>

Write the next version of this table: its rows followed by input.

pub async fn overwrite( &self, input: impl IntoArrowStream, ) -> Result<Table, Error>

Write the next version of this table with only the rows of input.

pub async fn delete_rows( &self, filter: Option<Expression>, ) -> Result<DeletedRows, Error>

Write the next version of this table without the visible rows matching filter, or without any rows when there is no filter.

Retained rows keep their stable row IDs. When no row matches, nothing is written and the result holds this table. Unsupported predicates fail before anything is written.

pub async fn recover_write( &self, receipt: PreparedWriteReceipt, ) -> Result<Table, Error>

Register a version of this table that a write prepared but whose registration outcome was unknown (Error::RegistrationUnknown), without uploading its rows again.

impl Table

pub async fn schema(&self) -> Result<SchemaRef, Error>

This version’s Arrow schema. It plans a scan but reads no rows.

pub async fn alter_schema( &self, changes: impl IntoIterator<Item = SchemaChange>, ) -> Result<Table, Error>

Write the next version of this table with changes applied to its schema, in order, without writing data files. Every change is checked against this version before anything is written; with no changes the result is this table.

pub async fn patch_rows( &self, filter: Option<Expression>, set: Vec<NamedExpression>, ) -> Result<UpdatedRows, Error>

Write the next version of this table with the values of set in the visible rows that match filter, or in every row without a filter, recorded as patches beside the data.

Each assignment names an existing column and must evaluate to its stored type; nothing is cast. Rows keep their row IDs. When no row matches, nothing is written and the result holds this table.

impl Table

pub async fn writer(&self) -> Result<TableWrite, Error>

Begin the next version of this table: its rows, edited by the patches and deletions the write takes, followed by every appended row.

Trait Implementations

impl Clone for Table

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Table

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.