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 84d24eb Add doc example for multipart upload to
`GoogleCloudStorage::create_multipart` (#803)
84d24eb is described below
commit 84d24eb8efcec9448566de09e94d2d4b74b21ebe
Author: Andrew Lamb <[email protected]>
AuthorDate: Mon Jul 20 11:16:15 2026 -0400
Add doc example for multipart upload to
`GoogleCloudStorage::create_multipart` (#803)
* Add doc example for multipart upload to
GoogleCloudStorage::create_multipart
Add a runnable (`no_run`) example on the `MultipartStore` impl for
`GoogleCloudStorage` 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]>
* Update src/gcp/mod.rs
Co-authored-by: Kevin Liu <[email protected]>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: Kevin Liu <[email protected]>
---
src/gcp/mod.rs | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
diff --git a/src/gcp/mod.rs b/src/gcp/mod.rs
index 38a92c4..90e9129 100644
--- a/src/gcp/mod.rs
+++ b/src/gcp/mod.rs
@@ -230,6 +230,58 @@ impl ObjectStore for GoogleCloudStorage {
#[async_trait]
impl MultipartStore for GoogleCloudStorage {
+ /// 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::{gcp::GoogleCloudStorageBuilder,
multipart::MultipartStore, path::Path, PutPayload};
+ /// #
+ /// let gcs = GoogleCloudStorageBuilder::new()
+ /// .with_bucket_name("my-bucket")
+ /// .with_service_account_path("/path/to/service-account.json")
+ /// .build()?;
+ ///
+ /// let path = Path::from("data/large_file");
+ ///
+ /// // Start the upload, obtaining an id used to reference it in later
calls
+ /// let id = gcs.create_multipart(&path).await?;
+ ///
+ /// // Upload the individual parts. Every part except the last must be at
least
+ /// // 5 MiB.
+ /// let part0 = gcs
+ /// .put_part(&path, &id, 0, PutPayload::from(vec![0; 5 * 1024 *
1024]))
+ /// .await?;
+ /// let part1 = gcs
+ /// .put_part(&path, &id, 1, PutPayload::from("the final part"))
+ /// .await?;
+ ///
+ /// // Finalize the upload. The parts must be provided in `part_idx` order.
+ /// gcs.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 [Cloud Storage 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
+ /// [Cloud Storage multipart upload limits]:
https://docs.cloud.google.com/storage/docs/xml-api/post-object-complete
async fn create_multipart(&self, path: &Path) -> Result<MultipartId> {
self.client
.multipart_initiate(path, PutMultipartOptions::default())
