This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs-object-store.git
The following commit(s) were added to refs/heads/main by this push:
new 7015e5e Add doc example for multipart upload to
AmazonS3::create_multipart (#801)
7015e5e is described below
commit 7015e5ed09fb1aa7e076f1c5b799f7ba6d5ed33c
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Jul 20 10:30:36 2026 -0400
Add doc example for multipart upload to AmazonS3::create_multipart (#801)
* Add doc example for multipart upload to AmazonS3::create_multipart
Add a runnable (`no_run`) example on the `MultipartStore` impl for
`AmazonS3` showing the full low-level flow: `create_multipart`,
`put_part` for each part, and `complete_multipart` to finalize.
Also link to the example from `MultipartStore::create_multipart` so it
is discoverable from the trait definition.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
* Fix double space in create_multipart doc link references
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
---
src/aws/mod.rs | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
src/multipart.rs | 11 +++++++++++
2 files changed, 65 insertions(+)
diff --git a/src/aws/mod.rs b/src/aws/mod.rs
index b02bd0e..5d30fbf 100644
--- a/src/aws/mod.rs
+++ b/src/aws/mod.rs
@@ -484,6 +484,60 @@ impl MultipartUpload for S3MultiPartUpload {
#[async_trait]
impl MultipartStore for AmazonS3 {
+ /// Create a new multipart upload, returning its [`MultipartId`].
+ ///
+ /// This is the low-level [`MultipartStore`] API, which gives direct
control
+ /// over individual parts. See [`ObjectStoreExt::put_multipart`] for a
+ /// higher-level API that handles parts automatically.
+ ///
+ /// # Example
+ ///
+ /// Create a multipart upload, upload two parts, and finalize it by calling
+ /// [`complete_multipart`]:
+ ///
+ /// ```no_run
+ /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+ /// # use object_store::{aws::AmazonS3Builder, multipart::MultipartStore,
path::Path, PutPayload};
+ /// #
+ /// let s3 = AmazonS3Builder::new()
+ /// .with_region("us-east-1")
+ /// .with_bucket_name("my-bucket")
+ /// .with_access_key_id("my-access-key-id")
+ /// .with_secret_access_key("my-secret-access-key")
+ /// .build()?;
+ ///
+ /// let path = Path::from("data/large_file");
+ ///
+ /// // Start the upload, obtaining an id used to reference it in later
calls
+ /// let id = s3.create_multipart(&path).await?;
+ ///
+ /// // Upload the individual parts. Every part except the last must be at
least
+ /// // 5 MiB.
+ /// let part0 = s3
+ /// .put_part(&path, &id, 0, PutPayload::from(vec![0; 5 * 1024 *
1024]))
+ /// .await?;
+ /// let part1 = s3
+ /// .put_part(&path, &id, 1, PutPayload::from("the final part"))
+ /// .await?;
+ ///
+ /// // Finalize the upload. The parts must be provided in `part_idx` order.
+ /// s3.complete_multipart(&path, &id, vec![part0, part1]).await?;
+ /// # Ok(())
+ /// # }
+ /// ```
+ ///
+ /// Every part except the last must be at least 5 MiB. Parts may be
uploaded
+ /// concurrently and in any order, provided each is given the correct
+ /// `part_idx`. See [Amazon S3 multipart upload limits] for the full set of
+ /// size and count constraints.
+ ///
+ /// To discard an upload instead of completing it, call
+ /// [`abort_multipart`] with the same `id`.
+ ///
+ /// [`ObjectStoreExt::put_multipart`]: crate::ObjectStoreExt::put_multipart
+ /// [`complete_multipart`]: MultipartStore::complete_multipart
+ /// [`abort_multipart`]: MultipartStore::abort_multipart
+ /// [Amazon S3 multipart upload limits]:
https://docs.aws.amazon.com/AmazonS3/latest/userguide/qfacts.html
async fn create_multipart(&self, path: &Path) -> Result<MultipartId> {
self.client
.create_multipart(path, PutMultipartOptions::default())
diff --git a/src/multipart.rs b/src/multipart.rs
index 90db576..6588b07 100644
--- a/src/multipart.rs
+++ b/src/multipart.rs
@@ -39,17 +39,28 @@ pub struct PartId {
/// backends, including [`LocalFileSystem`], and automatically handles
uploading fixed
/// size parts of sufficient size in parallel
///
+/// See [`AmazonS3::create_multipart`] for a full example of this API.
+///
/// [`ObjectStore::put_multipart_opts`]: crate::ObjectStore::put_multipart_opts
/// [`LocalFileSystem`]: crate::local::LocalFileSystem
+/// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart
#[async_trait]
pub trait MultipartStore: Send + Sync + 'static {
/// Creates a new multipart upload, returning the [`MultipartId`]
+ ///
+ /// See [`AmazonS3::create_multipart`] for a full example of this API.
+ ///
+ /// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart
async fn create_multipart(&self, path: &Path) -> Result<MultipartId>;
/// Creates a new multipart upload with the given options, returning the
[`MultipartId`]
///
/// This allows callers using the low-level multipart API to provide
object attributes,
/// tags, or implementation-specific extensions when initiating the upload.
+ ///
+ /// See [`AmazonS3::create_multipart`] for a full example of this API.
+ ///
+ /// [`AmazonS3::create_multipart`]: crate::aws::AmazonS3::create_multipart
async fn create_multipart_opts(
&self,
path: &Path,
