From 6c035cab535c3685b28c245d57203d13dc43bda9 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 19 Nov 2025 01:18:00 -0500 Subject: [PATCH 1/2] docs: Clarify functionality of `SnapshotProduceOperation` --- crates/iceberg/src/transaction/snapshot.rs | 40 ++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/crates/iceberg/src/transaction/snapshot.rs b/crates/iceberg/src/transaction/snapshot.rs index 6b3d0e4ff4..3a51daecbb 100644 --- a/crates/iceberg/src/transaction/snapshot.rs +++ b/crates/iceberg/src/transaction/snapshot.rs @@ -34,13 +34,53 @@ use crate::{Error, ErrorKind, TableRequirement, TableUpdate}; const META_ROOT_PATH: &str = "metadata"; +/// A trait that defines how different table operations produce new snapshots. +/// +/// `SnapshotProduceOperation` is used by [`SnapshotProducer`] to customize snapshot creation +/// based on the type of operation being performed (e.g., `Append`, `Overwrite`, `Delete`, etc.). +/// Each operation type implements this trait to specify: +/// - Which operation type to record in the snapshot summary +/// - Which existing manifest files should be included in the new snapshot +/// - Which manifest entries should be marked as deleted +/// +/// # When it accomplishes +/// +/// This trait is used during the snapshot creation process in [`SnapshotProducer::commit()`]: +/// +/// 1. **Operation Type Recording**: The `operation()` method determines which operation type +/// (e.g., `Operation::Append`, `Operation::Overwrite`) is recorded in the snapshot summary. +/// This metadata helps track what kind of change was made to the table. +/// +/// 2. **Manifest File Selection**: The `existing_manifest()` method determines which existing +/// manifest files from the current snapshot should be carried forward to the new snapshot. +/// For example: +/// - An `Append` operation typically includes all existing manifests plus new ones +/// - An `Overwrite` operation might exclude manifests for partitions being overwritten +/// +/// 3. **Delete Entry Processing**: The `delete_entries()` method is intended for future delete +/// operations to specify which manifest entries should be marked as deleted. pub(crate) trait SnapshotProduceOperation: Send + Sync { + /// Returns the operation type that will be recorded in the snapshot summary. + /// + /// This determines what kind of operation is being performed (e.g., `Append`, `Overwrite`), + /// which is stored in the snapshot metadata for tracking and auditing purposes. fn operation(&self) -> Operation; + + /// Returns manifest entries that should be marked as deleted in the new snapshot. #[allow(unused)] fn delete_entries( &self, snapshot_produce: &SnapshotProducer, ) -> impl Future>> + Send; + + /// Returns existing manifest files that should be included in the new snapshot. + /// + /// This method determines which manifest files from the current snapshot should be + /// carried forward to the new snapshot. The selection depends on the operation type: + /// + /// - **Append operations**: Typically include all existing manifests + /// - **Overwrite operations**: May exclude manifests for partitions being overwritten + /// - **Delete operations**: May exclude manifests for partitions being deleted fn existing_manifest( &self, snapshot_produce: &SnapshotProducer<'_>, From 4af1be5626495940a29e7d092c7c5a2396962610 Mon Sep 17 00:00:00 2001 From: Jonathan Date: Wed, 19 Nov 2025 01:21:32 -0500 Subject: [PATCH 2/2] fmt --- crates/iceberg/src/transaction/snapshot.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/iceberg/src/transaction/snapshot.rs b/crates/iceberg/src/transaction/snapshot.rs index 3a51daecbb..d59828ce31 100644 --- a/crates/iceberg/src/transaction/snapshot.rs +++ b/crates/iceberg/src/transaction/snapshot.rs @@ -57,7 +57,7 @@ const META_ROOT_PATH: &str = "metadata"; /// - An `Append` operation typically includes all existing manifests plus new ones /// - An `Overwrite` operation might exclude manifests for partitions being overwritten /// -/// 3. **Delete Entry Processing**: The `delete_entries()` method is intended for future delete +/// 3. **Delete Entry Processing**: The `delete_entries()` method is intended for future delete /// operations to specify which manifest entries should be marked as deleted. pub(crate) trait SnapshotProduceOperation: Send + Sync { /// Returns the operation type that will be recorded in the snapshot summary.