kevinjqliu commented on code in PR #803:
URL:
https://github.com/apache/arrow-rs-object-store/pull/803#discussion_r3607651026
##########
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://cloud.google.com/storage/docs/multipart-uploads
Review Comment:
```suggestion
/// [Cloud Storage multipart upload limits]:
https://docs.cloud.google.com/storage/docs/xml-api/post-object-complete
```
nit i find this page to be more useful:
https://docs.cloud.google.com/storage/docs/xml-api/post-object-complete
it explicitly states the limitation about 5mib
> If one of the parts specified in the request is less than 5 MiB and is not
the final part in the upload, you get a [400 Bad
Request](https://docs.cloud.google.com/storage/docs/xml-api/reference-status)
status code and the body of the error response has InvalidArgument in the Code
element.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
