### Example Usage of GetOptions

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Demonstrates creating GetOptions with a byte range and an ETag for conditional fetching. Useful for optimizing GET requests.

```rust
use object_store::GetOptions;

let opts = GetOptions::new()
    .with_range(Some(0..1000))
    .with_if_none_match(Some("abc123"));
```

--------------------------------

### Google Cloud Storage Configuration Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Example of configuring a Google Cloud Storage store using parse_url_opts with service account credentials.

```rust
let opts = vec![
    ("google_service_account", r#"{"type":"service_account","project_id":"..."}""#),
];
let (store, path) = parse_url_opts(&gcs_url, opts)?;
```

--------------------------------

### AWS S3 Configuration Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Example of configuring an AWS S3 store using parse_url_opts with specific credentials and region.

```rust
let opts = vec![
    ("aws_access_key_id", "AKIA...",),
    ("aws_secret_access_key", "wJalr...",),
    ("aws_region", "us-west-2",),
];
let (store, path) = parse_url_opts(&s3_url, opts)?;
```

--------------------------------

### Example Usage of GetResult to Load File Bytes

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Demonstrates how to retrieve an object using the `get` method and then load its entire content into memory as bytes using the `bytes()` method. Requires an `ObjectStore` instance.

```rust
use object_store::{ObjectStore, ObjectStoreExt, Path};

let result = store.get(&Path::from("file.txt")).await?;
let bytes = result.bytes().await?;
```

--------------------------------

### Example: Iterating PutPayload Chunks

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates iterating through the chunks of a PutPayload and printing each chunk.

```rust
use object_store::PutPayload;

let payload = PutPayload::from(b"data".to_vec());
for chunk in payload.iter() {
    println!("Chunk: {:?}", chunk);
}

```

--------------------------------

### ObjectStore Configuration Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Demonstrates a complete configuration workflow for the ObjectStore, including runtime backend selection and timeout configuration.

```rust
use anyhow::Result;
use object_store::ObjectStore;
use url::Url;

#[tokio::main]
async fn main() -> Result<()> {
    // Example: Runtime backend selection
    let url = Url::parse("s3://my-bucket/my-path")?;
    let store = object_store::parse_url(&url)?;

    // Example: Timeout configuration
    let mut client_options = object_store::ClientOptions::new();
    client_options = client_options.with_timeout(std::time::Duration::from_secs(10));
    let url_with_opts = Url::parse("s3://my-bucket/my-path")?;
    let store_with_opts = object_store::parse_url_opts(&url_with_opts, client_options)?;

    Ok(())
}

```

--------------------------------

### Example: PutPayload from Bytes

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Shows how to convert a Bytes object into a PutPayload using the `into()` method.

```rust
use bytes::Bytes;
use object_store::PutPayload;

let payload: PutPayload = Bytes::from("hello").into();

```

--------------------------------

### Example: PutPayload from String

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates creating a PutPayload from an owned `String` using the `PutPayload::from()` method.

```rust
use object_store::PutPayload;

let payload = PutPayload::from("hello".to_string());

```

--------------------------------

### Conditional Get with Caching Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Shows how to implement conditional GET requests with caching, likely using ETag or Last-Modified headers.

```rust
use object_store::ObjectStore;
use object_store::GetOptions;
use object_store::GetResult;

async fn conditional_get<T: ObjectStore>(store: &T, path: &str) -> Result<GetResult, object_store::Error> {
    let mut options = GetOptions::default();
    // Assuming ETag or Last-Modified headers are managed elsewhere
    // options.if_match = Some("some-etag");
    // options.if_modified_since = Some(timestamp);
    store.get_opts(path.into(), options).await
}

```

--------------------------------

### Example: PutPayload from Static Byte Slice

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates creating a PutPayload using the `from_static` method with a byte string literal.

```rust
use object_store::PutPayload;

let payload = PutPayload::from_static(b"hello");

```

--------------------------------

### Example: Convert PutPayload to Bytes

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates converting a PutPayload into a single Bytes object using the `into()` method.

```rust
use object_store::PutPayload;
use bytes::Bytes;

let payload = PutPayload::from(b"data".to_vec());
let bytes: Bytes = payload.into();

```

--------------------------------

### PutMode Example: Create and Update

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Demonstrates creating `PutOptions` for both create-only writes and conditional updates using `PutMode::Create` and `PutMode::Update`.

```rust
use object_store::{PutMode, PutOptions, UpdateVersion};

// Create-only write
let opts = PutOptions::from(PutMode::Create);

// Update with version check
let version = UpdateVersion { 
    e_tag: Some("abc123".to_string()), 
    version: None 
};
let opts = PutOptions::from(PutMode::Update(version));
```

--------------------------------

### Example: PutPayload Content Length

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Shows how to create a PutPayload from a vector and assert its total content length.

```rust
use object_store::PutPayload;

let payload = PutPayload::from(b"hello world".to_vec());
assert_eq!(payload.content_length(), 11);

```

--------------------------------

### Example: PutPayload from Vec<u8>

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates creating a PutPayload from a `Vec<u8>` using the `PutPayload::from()` method.

```rust
use object_store::PutPayload;

let payload = PutPayload::from(vec![1, 2, 3]);

```

--------------------------------

### AmazonS3Builder Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Demonstrates how to build an Amazon S3 storage client using the builder pattern, showing both environment variable and explicit credential configurations.

```APIDOC
## AmazonS3Builder Example

### Description
Provides examples for constructing an `AmazonS3Builder` using environment variables or explicit credentials.

### Method 1: From environment variables
```rust
use object_store::aws::AmazonS3Builder;
use object_store::ObjectStore;

let store = AmazonS3Builder::from_env()
    .with_bucket_name("my-bucket")
    .build()?;
```

### Method 2: With explicit credentials
```rust
use object_store::aws::AmazonS3Builder;
use object_store::ObjectStore;

let store = AmazonS3Builder::new()
    .with_bucket_name("my-bucket")
    .with_region("us-west-2")
    .with_access_key_id("AKIA...")
    .with_secret_access_key("wJalr...")
    .build()?;

// Now use the store
let path = Path::from("data/file.txt");
store.put(&path, b"data".into()).await?;
```
```

--------------------------------

### Example: PutPayload from Iterator<u8>

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Shows how to create a PutPayload by collecting a range of `u8` values into it.

```rust
use object_store::PutPayload;

let payload: PutPayload = (0..10u8).collect();

```

--------------------------------

### Complete Configuration Workflow with S3

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

A comprehensive example demonstrating how to parse a URL with inline configuration for AWS S3, retrieve data, and print its size. This showcases a typical usage pattern.

```rust
use object_store::{parse_url_opts, ObjectStore, ObjectStoreExt, Path};
use url::Url;
use std::sync::Arc;

async fn example() -> Result<(), Box<dyn std::error::Error>> {
    // Parse URL with inline configuration
    let url = Url::parse("s3://my-bucket/data/part-001.parquet")?;
    let config = vec![
        ("aws_region", "eu-west-1"),
        ("aws_access_key_id", "AKIA..."),
        ("aws_secret_access_key", "wJalr..."),
    ];
    
    let (store, path) = parse_url_opts(&url, config)?;
    
    // Now use the store
    let data = store.get(&path).await?;
    let bytes = data.bytes().await?;
    
    println!("Downloaded {} bytes from {}", bytes.len(), path);
    Ok(())
}
```

--------------------------------

### Runtime Backend Selection

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

This example shows how to read data from any supported backend (S3, GCS, Azure, local, memory, HTTP) by dynamically parsing the URL. It uses environment variables to specify the data source.

```rust
use object_store::parse_url;
use url::Url;
use std::env;

async fn read_from_any_backend(
    url_string: &str,
) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    let url = Url::parse(url_string)?;
    let (store, path) = parse_url(&url)?;
    
    // Works with any backend: S3, GCS, Azure, local, memory, HTTP
    let data = store.get(&path).await?;
    Ok(data.bytes().await?.to_vec())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Can be s3://bucket/file, gs://bucket/file, file:///path, etc.
    let url = env::var("DATA_URL")?;
    let bytes = read_from_any_backend(&url).await?;
    println!("Read {} bytes", bytes.len());
    Ok(())
}
```

--------------------------------

### Create or Update Pattern Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Illustrates the 'create or update' pattern, where an object is created if it doesn't exist, or updated if it does.

```rust
use object_store::{ObjectStore, PutOptions, PutMode};

async fn create_or_update<T: ObjectStore>(store: &T, path: &str, data: Vec<u8>) -> Result<object_store::PutResult, object_store::Error> {
    let options = PutOptions {
        mode: PutMode::Overwrite,
        ..Default::default()
    };
    store.put_opts(path.into(), data.into(), options).await
}

```

--------------------------------

### Example: PutPayload as Reference to Byte Slices

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Shows how to obtain a slice of `Bytes` chunks from a PutPayload using `as_ref()` and checking its length.

```rust
use object_store::PutPayload;

let payload = PutPayload::from(b"test".to_vec());
let chunks = payload.as_ref();
assert_eq!(chunks.len(), 1);

```

--------------------------------

### Deprecate API Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Example of marking a Rust API as deprecated using the `#[deprecated]` attribute. Specify the version in which it was deprecated and provide a note suggesting the preferred alternative.

```rust
#[deprecated(since = "0.11.0", note = "Use `date_part` instead")]
```

--------------------------------

### Configure GET Operations with Conditional Headers

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Configuration options for GET operations, allowing for conditional requests based on ETag, modification dates, byte ranges, and versioning. Supports fetching metadata only.

```rust
#[derive(Debug, Default, Clone)]
pub struct GetOptions {
    pub if_match: Option<String>,
    pub if_none_match: Option<String>,
    pub if_modified_since: Option<DateTime<Utc>>,
    pub if_unmodified_since: Option<DateTime<Utc>>,
    pub range: Option<GetRange>,
    pub version: Option<String>,
    pub head: bool,
    pub extensions: Extensions,
}
```

--------------------------------

### Start Azurite Emulator

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Run the Azurite emulator locally for Azure integration testing. Ensure ports 10000, 10001, and 10002 are available.

```shell
podman run -p 10000:10000 -p 10001:10001 -p 10002:10002 mcr.microsoft.com/azure-storage/azurite
```

--------------------------------

### Basic Object Store Usage with In-Memory Backend

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/README.md

Demonstrates fundamental operations like writing, reading, and listing objects using the in-memory storage backend. This is useful for testing and examples.

```rust
use object_store::{ObjectStore, ObjectStoreExt, Path};
use object_store::memory::InMemory;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create store (in-memory example; use S3, GCS, etc. in production)
    let store = InMemory::new();
    
    // Write data
    let path = Path::from("data/hello.txt");
    store.put(&path, b"hello world".into()).await?;
    
    // Read data
    let result = store.get(&path).await?;
    let bytes = result.bytes().await?;
    println!("{}", String::from_utf8(bytes.to_vec())?);
    
    // List objects
    use futures_util::TryStreamExt;
    let objects: Vec<_> = store.list(None)
        .try_collect()
        .await?;
    println!("Objects: {}", objects.len());
    
    Ok(())
}
```

--------------------------------

### Start MinIO Server with HTTPS

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Launches a MinIO server instance using Docker, configured with the generated self-signed certificate to enable HTTPS for SSE-C tests.

```shell
docker run -d \
  -p 9000:9000 \
  --name minio \
  -v ${HOME}/certs:/root/.minio/certs \
  -e "MINIO_ROOT_USER=minio" \
  -e "MINIO_ROOT_PASSWORD=minio123" \
  minio/minio server /data
```

--------------------------------

### Graceful Not-Found Handling Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Shows how to gracefully handle cases where an object is not found, preventing application crashes.

```rust
use object_store::ObjectStore;

async fn get_or_default<T: ObjectStore>(store: &T, path: &str) -> Result<Vec<u8>, object_store::Error> {
    match store.get(path.into()).await {
        Ok(object) => object.bytes().await,
        Err(object_store::Error::NotFound { .. }) => Ok(Vec::new()), // Return empty data if not found
        Err(e) => Err(e),
    }
}

```

--------------------------------

### Example: PutPayload from &'static str

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Shows converting a static string slice into a PutPayload using the `into()` method.

```rust
use object_store::PutPayload;

let payload: PutPayload = b"hello".as_ref().into();

```

--------------------------------

### Path::prefix_matches

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Determines if the path starts with a given prefix, returning a boolean value.

```APIDOC
## Path::prefix_matches

### Description
Check if this path starts with a prefix (boolean).

### Parameters
#### Path Parameters
- **prefix** (`&Path`) - Required - The prefix to match

### Returns
`bool`
```

--------------------------------

### AmazonS3Builder::new

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Creates a new AmazonS3Builder with default configuration. This is the starting point for building an S3 store.

```APIDOC
## AmazonS3Builder::new

### Description
Creates a new builder with default configuration.

### Method
`new()`

### Returns
`AmazonS3Builder`

### Example
```rust
use object_store::aws::AmazonS3Builder;

let builder = AmazonS3Builder::new();
```
```

--------------------------------

### Start Fake GCS Server

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Launch a fake Google Cloud Storage server locally for GCS integration testing. This server will listen on port 4443.

```shell
docker run -p 4443:4443 tustvold/fake-gcs-server -scheme http
```

--------------------------------

### Start LocalStack for S3 Integration Tests

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Launches LocalStack and EC2 metadata mock containers to simulate AWS services for integration testing.

```shell
LOCALSTACK_VERSION=sha256:a0b79cb2430f1818de2c66ce89d41bba40f5a1823410f5a7eaf3494b692eed97
podman run -d -p 4566:4566 localstack/localstack@$LOCALSTACK_VERSION
podman run -d -p 1338:1338 amazon/amazon-ec2-metadata-mock:v1.9.2 --imdsv2
```

--------------------------------

### Configure Azure Blob Storage with Options

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Example of configuring Azure Blob Storage using a vector of options. This is useful when providing credentials or specific settings directly in code.

```rust
let opts = vec![
    ("azure_storage_account", "myaccount"),
    ("azure_storage_account_key", "base64key..."),
];
let (store, path) = parse_url_opts(&azure_url, opts)?;
```

--------------------------------

### Boolean Prefix Match

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Checks if a path starts with a given prefix, returning a boolean value.

```rust
pub fn prefix_matches(&self, prefix: &Self) -> bool
```

--------------------------------

### Rust: Multipart Upload Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Performs a multipart upload for very large files. This involves initiating a multipart upload, writing chunks sequentially using WriteMultipart, and then finishing the upload.

```rust
use object_store::{ObjectStore, ObjectStoreExt, PutPayload, WriteMultipart, Path};
use bytes::Bytes;

async fn put_multipart(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::from("huge.bin");
    let upload = store.put_multipart(&path).await?;
    let mut writer = WriteMultipart::new(upload);
    
    for i in 0..10 {
        let chunk = vec![i as u8; 1024 * 1024]; // 1MB chunks
        writer.write(chunk.into()).await?;
    }
    
    writer.finish().await?;
    Ok(())
}
```

--------------------------------

### Handling NotSupported Errors

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

This example demonstrates how to catch 'NotSupported' errors, which are returned when an operation is not supported by the specific backend being used. It suggests using an alternative approach.

```rust
use object_store::Error;

match store.signed_url(method, &path, duration).await {
    Err(Error::NotSupported { source }) => {
        eprintln!("Not supported: {}", source);
        // Use alternative approach
    }
    _ => {}
}
```

--------------------------------

### Get Object Store from Registry

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Demonstrates retrieving a pre-configured, globally cached object store instance for a given URL using the `registry` module. This follows a singleton pattern per URL.

```rust
pub mod registry {
    pub fn get_object_store(url: &Url) -> Result<Arc<dyn ObjectStore>>;
}
```

--------------------------------

### Create New AWS S3 Builder

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Instantiate a new AmazonS3Builder with default settings. This is the starting point for configuring an S3 store.

```rust
use object_store::aws::AmazonS3Builder;

let builder = AmazonS3Builder::new();
```

--------------------------------

### GetOptions

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Configuration for GET operations, allowing for conditional requests using headers like If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since, and byte range fetching.

```APIDOC
## GetOptions

### Description
Configuration for GET operations with conditional headers.

### Fields
- **if_match** (`Option<String>`) - Required/Optional: None - Return only if etag matches (RFC 9110)
- **if_none_match** (`Option<String>`) - Required/Optional: None - Return 304 NotModified if etag matches
- **if_modified_since** (`Option<DateTime<Utc>>`) - Required/Optional: None - Return only if modified after this date
- **if_unmodified_since** (`Option<DateTime<Utc>>`) - Required/Optional: None - Return error if modified after this date
- **range** (`Option<GetRange>`) - Required/Optional: None - Fetch only this byte range
- **version** (`Option<String>`) - Required/Optional: None - Request specific object version
- **head** (`bool`) - Required/Optional: false - Fetch metadata only (no body)
- **extensions** (`Extensions`) - Required/Optional: Empty - Implementation-specific context (tracing, etc.)

### Methods
- `new() -> Self` – Create default options
- `with_if_match(etag: Option<impl Into<String>>) -> Self` – Set if_match
- `with_if_none_match(etag: Option<impl Into<String>>) -> Self` – Set if_none_match
- `with_if_modified_since(dt: Option<impl Into<DateTime<Utc>>>) -> Self` – Set if_modified_since
- `with_if_unmodified_since(dt: Option<impl Into<DateTime<Utc>>>) -> Self` – Set if_unmodified_since
- `with_range(range: Option<impl Into<GetRange>>) -> Self` – Set byte range
- `with_version(version: Option<impl Into<String>>) -> Self` – Set version
- `with_head(head: impl Into<bool>) -> Self` – Set head flag
- `with_extensions(extensions: Extensions) -> Self` – Set extensions
- `check_preconditions(&self, meta: &ObjectMeta) -> Result<()>` – Validate conditions against metadata

### Example
```rust
use object_store::GetOptions;

let opts = GetOptions::new()
    .with_range(Some(0..1000))
    .with_if_none_match(Some("abc123"));
```
```

--------------------------------

### Configure GCP Integration Test Environment

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Create a test bucket in the fake GCS server and configure the necessary JSON file for authentication. This setup is required before running GCS integration tests.

```shell
curl -v -X POST --data-binary '{"name":"test-bucket"}' -H "Content-Type: application/json" "http://localhost:4443/storage/v1/b"
echo '{"gcs_base_url": "http://localhost:4443", "disable_oauth": true, "client_email": "", "private_key": ""}' > /tmp/gcs.json
```

--------------------------------

### Example Usage of GetRange

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Illustrates creating GetRange variants for fetching a specific byte range (0-999) and the last 512 bytes of an object.

```rust
use object_store::GetRange;

// Fetch bytes 0-999
let range = GetRange::Bounded(0..1000);

// Fetch last 512 bytes
let suffix = GetRange::Suffix(512);
```

--------------------------------

### Optimistic Locking for Updates Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Demonstrates optimistic locking for updates, typically involving checking an ETag or version before modifying an object.

```rust
use object_store::{ObjectStore, PutOptions, PutMode, UpdateVersion};

async fn optimistic_update<T: ObjectStore>(store: &T, path: &str, data: Vec<u8>, version: &str) -> Result<object_store::PutResult, object_store::Error> {
    let options = PutOptions {
        mode: PutMode::Update(UpdateVersion::Exact(version.to_string())),
        ..Default::default()
    };
    store.put_opts(path.into(), data.into(), options).await
}

```

--------------------------------

### Parse URL for HTTP/WebDAV Store

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Example of parsing a URL for an HTTP or WebDAV store. This requires the 'http' feature to be enabled and allows configuring connection timeouts and retries.

```rust
let url = Url::parse("https://example.com/files")?;
let (store, path) = parse_url(&url)?;
```

--------------------------------

### Create S3 Buckets and DynamoDB Table with AWS CLI

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Creates two S3 buckets and a DynamoDB table using the AWS CLI, targeting the LocalStack endpoint. Ensure the AWS CLI is installed or use a container.

```shell
aws s3 mb s3://test-bucket --endpoint-url=http://localhost:4566
aws --endpoint-url=http://localhost:4566 s3 mb s3://test-bucket-for-spawn
aws --endpoint-url=http://localhost:4566 dynamodb create-table --table-name test-table --key-schema AttributeName=path,KeyType=HASH AttributeName=etag,KeyType=RANGE --attribute-definitions AttributeName=path,AttributeType=S AttributeName=etag,AttributeType=S --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5
```

--------------------------------

### Error Matching Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

Illustrates how to catch and handle specific error variants from the object_store::Error enum using a match statement.

```rust
use object_store::Error;

fn handle_error(err: Error) {
    match err {
        Error::NotFound { .. } => {
            println!("Object not found.");
        }
        Error::PermissionDenied { .. } => {
            println!("Permission denied.");
        }
        _ => {
            println!("An unexpected error occurred.");
        }
    }
}

```

--------------------------------

### Rust: Large Streaming Data Upload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Handles uploading large amounts of data by streaming it through PutPayloadMut. This example configures a block size and extends the payload iteratively before freezing and uploading.

```rust
use object_store::{ObjectStore, ObjectStoreExt, PutPayloadMut, Path};

async fn put_streaming(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let mut builder = PutPayloadMut::new()
        .with_block_size(64 * 1024); // 64KB blocks
    
    // Generate data
    for chunk in 0..100 {
        let data = vec![chunk as u8; 10240];
        builder.extend_from_slice(&data);
    }
    
    let payload = builder.freeze();
    let path = Path::from("large.bin");
    store.put(&path, payload).await?;
    Ok(())
}
```

--------------------------------

### Conditional Update Example

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Illustrates a robust conditional update pattern for an object store. It repeatedly fetches the object's current version and ETag, then attempts to update it, retrying on `Precondition` errors due to optimistic locking.

```rust
use object_store::{ObjectStore, ObjectStoreExt, PutMode, PutOptions, Path};

async fn conditional_update(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::from("counter.txt");
    
    loop {
        // Get current version
        let result = store.get(&path).await?;
        let version = result.meta.version.clone();
        let etag = result.meta.e_tag.clone();
        
        // Update data
        let new_data = b"updated";
        
        // Try to commit
        match store.put_opts(
            &path,
            new_data.into(),
            PutMode::Update(UpdateVersion { e_tag: etag, version }).into()
        ).await {
            Ok(_) => break,
            Err(object_store::Error::Precondition { .. }) => continue, // Retry
            Err(e) => return Err(e.into()),
        }
    }
    Ok(())
}
```

--------------------------------

### Path::prefix_match

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Checks if the path starts with a given prefix and returns an iterator over the remaining segments if it does. Returns `None` if the path does not start with the prefix.

```APIDOC
## Path::prefix_match

### Description
Check if this path starts with a prefix and get remaining segments.

### Parameters
#### Path Parameters
- **prefix** (`&Path`) - Required - The prefix to match

### Returns
`Option<impl Iterator<Item = PathPart>>` – None if no match

### Example
```rust
use object_store::path::Path;

let p = Path::from("foo/bar/baz");
let prefix = Path::from("foo");
let remaining: Vec<_> = p.prefix_match(&prefix)
    .unwrap()
    .map(|s| s.as_ref())
    .collect();
assert_eq!(remaining, vec!["bar", "baz"]);
```
```

--------------------------------

### Prefix Match and Remaining Segments

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Checks if a path starts with a given prefix and returns an iterator over the remaining path segments if it matches. Returns None if the path does not start with the prefix.

```rust
use object_store::path::Path;

let p = Path::from("foo/bar/baz");
let prefix = Path::from("foo");
let remaining: Vec<_> = p.prefix_match(&prefix)
    .unwrap()
    .map(|s| s.as_ref())
    .collect();
assert_eq!(remaining, vec!["bar", "baz"]);
```

--------------------------------

### Define Byte Range Specification for GET Requests

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

An enum to specify byte ranges for GET requests, supporting both bounded ranges and fetching a suffix of the object. Used to retrieve partial object data.

```rust
pub enum GetRange {
    Bounded(Range<u64>),
    Suffix(u64),
}
```

--------------------------------

### Define Result Structure for GET Operations

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

The result of a GET operation, containing the data payload, object metadata, the byte range of the data returned, and additional attributes. Supports collecting the payload to bytes or streaming it.

```rust
#[derive(Debug)]
pub struct GetResult {
    pub payload: GetResultPayload,
    pub meta: ObjectMeta,
    pub range: Range<u64>,
    pub attributes: Attributes,
}
```

--------------------------------

### Handling Precondition Error for GET

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

Catch the Error::Precondition variant when a GET request's conditional headers (like If-Match or If-Unmodified-Since) fail. This indicates the object's state does not meet the specified condition.

```rust
use object_store::{Error, GetOptions, PutMode, UpdateVersion};

// For GET
let opts = GetOptions::new().with_if_match(Some("abc123"));
match store.get_opts(&path, opts).await {
    Err(Error::Precondition { path, .. }) => {
        println!("Precondition failed for {}", path);
        // Etag mismatch - object was modified
    }
    _ => {} 
}
```

--------------------------------

### Create Local Filesystem Store

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Use LocalFileSystem::new_with_prefix to create a filesystem store at a specified directory.

```rust
use object_store::local::LocalFileSystem;
use std::path::Path;

let store = LocalFileSystem::new_with_prefix("/var/data")?;
```

--------------------------------

### Initiate and Write Multipart Upload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/multipart-upload.md

Demonstrates how to initiate a multipart upload for a large file and write data in chunks using the `WriteMultipart` adapter. This is useful when the total file size is unknown or exceeds memory limits.

```rust
use object_store::{ObjectStore, ObjectStoreExt, WriteMultipart, Path};

async fn multipart_example(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::from("large-file.bin");
    let upload = store.put_multipart(&path).await?;
    let mut writer = WriteMultipart::new(upload);
    
    // Upload in chunks
    writer.write(b"chunk1").await?;
    writer.write(b"chunk2").await?;
    writer.write(b"chunk3").await?;
    
    writer.finish().await?;
    Ok(())
}
```

--------------------------------

### Parse URL for Local Filesystem Store

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Demonstrates how to create an object store instance for the local filesystem using a file path. Requires the 'fs' feature to be enabled.

```rust
let url = Url::from_file_path("/var/data")?;
let (store, path) = parse_url(&url)?;
```

--------------------------------

### GetRange

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

Defines how to specify a byte range for GET requests, supporting bounded ranges and suffixes.

```APIDOC
## GetRange

### Description
Byte range specification for GET requests.

### Variants
- `Bounded(Range<u64>)` - Fetch bytes from start to end (end-exclusive)
- `Suffix(u64)` - Fetch last N bytes

### Example
```rust
use object_store::GetRange;

// Fetch bytes 0-999
let range = GetRange::Bounded(0..1000);

// Fetch last 512 bytes
let suffix = GetRange::Suffix(512);
```
```

--------------------------------

### Configuration Parsing Functions

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/MANIFEST.md

This snippet illustrates the configuration parsing functions, specifically parse_url() and parse_url_opts(). It shows how parse_url() uses a Url to return an ObjectStore and Path, and how parse_url_opts() uses ClientOptions.

```rust
Configuration
  ├─ parse_url() → uses Url → returns (Arc<dyn ObjectStore>, Path)
  └─ parse_url_opts() → uses ClientOptions
```

--------------------------------

### Get String Representation

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Provides the string representation of a Path object via the AsRef<str> trait.

```rust
let p = Path::from("foo/bar");
assert_eq!(p.as_ref(), "foo/bar");
```

--------------------------------

### Get Filename from Path

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Extracts the filename, which is the last segment of the Path. Returns None if the Path is the root.

```rust
use object_store::path::Path;

let p = Path::from("foo/bar/baz.txt");
assert_eq!(p.filename(), Some("baz.txt"));
assert_eq!(Path::ROOT.filename(), None);
```

--------------------------------

### Create Azure Test Bucket

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Create a test bucket in the Azurite emulator using the Azure CLI. This command requires the emulator to be running.

```shell
podman run --net=host mcr.microsoft.com/azure-cli az storage container create -n test-bucket --connection-string 'DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;QueueEndpoint=http://127.0.0.1:10001/devstoreaccount1;'
```

--------------------------------

### HttpBuilder with_url and build

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Configure and build an HTTP object store client by setting the base URL.

```rust
use object_store::http::HttpBuilder;
use url::Url;

let store = HttpBuilder::new()
    .with_url(Url::parse("https://example.com/files/")?)
    .build()?;

```

--------------------------------

### Get File Extension

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Retrieves the file extension from the last segment of a path. Returns None if no extension is present.

```rust
use object_store::path::Path;

let p = Path::from("foo/bar/baz.txt");
assert_eq!(p.extension(), Some("txt"));

let p = Path::from("foo/bar");
assert_eq!(p.extension(), None);
```

--------------------------------

### Root Path Constant

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Represents the root of the object storage, equivalent to an empty path or a path starting with a single slash.

```rust
pub const ROOT: Path;
```

--------------------------------

### Create ClientOptions from Iterator

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Illustrates creating `ClientOptions` from an iterator of key-value pairs. This is a flexible way to provide configuration for various backends.

```rust
pub fn from_iter<I: IntoIterator<Item = (impl Into<ClientConfigKey>, String)>>(
    iter: I,
) -> Result<Self>
```

--------------------------------

### Catching UnknownConfigurationKey Errors in Rust

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

Illustrates how to handle the UnknownConfigurationKey error during configuration parsing. It suggests consulting the documentation for valid keys specific to the backend store.

```rust
use object_store::Error;

match parse_url_opts(&url, options).await {
    Err(Error::UnknownConfigurationKey { store, key }) => {
        eprintln!("Unknown config key '{}' for store '{}'", key, store);
        eprintln!("Check documentation for valid keys");
    }
    _ => {}
}
```

--------------------------------

### Initiate a multipart upload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/objectstore-core.md

Use `put_multipart_opts` to initiate a multipart upload for large or streaming data. This is ideal for writing data that cannot fit into a single memory buffer or needs to be streamed.

```rust
use object_store::{ObjectStore, ObjectStoreExt, WriteMultipart, Path};

async fn example(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::from("data/large.bin");
    let upload = store.put_multipart(&path).await?;
    let mut writer = WriteMultipart::new(upload);
    writer.write(b"chunk1").await?;
    writer.write(b"chunk2").await?;
    writer.finish().await?;
    Ok(())
}
```

--------------------------------

### GetResult

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/types.md

The result of a GET operation, containing the data payload, object metadata, the byte range of the data returned, and additional attributes.

```APIDOC
## GetResult

### Description
Result of a GET operation including metadata and data stream.

### Fields
- **payload** (`GetResultPayload`) - File or stream handle for the data
- **meta** (`ObjectMeta`) - Object metadata
- **range** (`Range<u64>`) - Byte range of data returned
- **attributes** (`Attributes`) - Additional object attributes

### Methods
- `async bytes(self) -> Result<Bytes>` – Collect entire payload to memory
- `into_stream(self) -> BoxStream<'static, Result<Bytes>>` – Convert to streaming chunks

### Example
```rust
use object_store::{ObjectStore, ObjectStoreExt, Path};

let result = store.get(&Path::from("file.txt")).await?;
let bytes = result.bytes().await?; // Load entire file
```
```

--------------------------------

### Build Google Cloud Storage

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Use GoogleCloudStorageBuilder to create a GCS store. Configure with bucket name and service account path.

```rust
use object_store::gcp::GoogleCloudStorageBuilder;

let store = GoogleCloudStorageBuilder::new()
    .with_bucket_name("my-bucket")
    .with_service_account_path("/path/to/service-account.json")
    .build()?;
```

--------------------------------

### LocalFileSystem

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Builder for creating a Local Filesystem client. Allows specifying a base directory.

```APIDOC
## LocalFileSystem::new

### Description
Create a Local Filesystem client rooted at the current directory.

### Method
`new()`

### Returns
`LocalFileSystem` - A new `LocalFileSystem` instance.

## LocalFileSystem::new_with_prefix

### Description
Create a Local Filesystem client rooted at a specified directory.

### Method
`new_with_prefix(prefix: impl AsRef<Path>) -> Result<Self>`

### Parameters
- **prefix** (impl AsRef<Path>) - Required - Base directory path

### Returns
`Result<LocalFileSystem>` - A `LocalFileSystem` instance on success, or an error.

### Request Example
```rust
use object_store::local::LocalFileSystem;
use std::path::Path;

let store = LocalFileSystem::new_with_prefix("/var/data")?;
```
```

--------------------------------

### Implement AsRef<[Bytes]> for PutPayload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Provides a way to get a slice of the `Bytes` chunks contained within a PutPayload without taking ownership.

```rust
impl AsRef<[Bytes]> for PutPayload

```

--------------------------------

### Parse URL for In-Memory Store

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Shows how to create an in-memory object store instance. This is useful for testing or temporary storage.

```rust
let url = Url::parse("memory:///")?;
let (store, path) = parse_url(&url)?;
```

--------------------------------

### Get Parent Path

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Returns a new Path representing the parent directory of the current Path. Returns None if the current Path is the root.

```rust
use object_store::path::Path;

let p = Path::from("foo/bar/baz");
assert_eq!(p.parent().unwrap().as_ref(), "foo/bar");
assert_eq!(Path::ROOT.parent(), None);
```

--------------------------------

### Build AWS S3 Store from Environment with Specifics

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Construct an AmazonS3 store by first loading configuration from the environment, then overriding or specifying the bucket name and region. This is a typical way to create a functional S3 client.

```rust
use object_store::aws::AmazonS3Builder;

let store = AmazonS3Builder::from_env()
    .with_bucket_name("my-bucket")
    .with_region("us-east-1")
    .build()?;
```

--------------------------------

### Create and Push Git Tag

Source: https://github.com/apache/arrow-rs-object-store/blob/main/dev/release/README.md

Fetch the latest changes from the Apache repository and create a Git tag for the release version. Push the tag to the Apache remote repository.

```bash
git fetch apache
git tag <version> apache/main
# push tag to apache
git push apache <version>
```

--------------------------------

### Get Object Metadata

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/objectstore-core.md

Retrieve metadata for an object without downloading its content. Use this when you only need information like size or last modified date.

```rust
async fn head(
    &self,
    location: &Path,
) -> Result<ObjectMeta>

```

--------------------------------

### Rust: Simple Object Store Put Operation

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Demonstrates a basic object store PUT operation using Bytes. Ensure the ObjectStore and Path are correctly set up before calling.

```rust
use object_store::{ObjectStore, ObjectStoreExt, PutPayload, Path};
use bytes::Bytes;

async fn put_simple(store: &dyn ObjectStore) -> Result<(), Box<dyn std::error::Error>> {
    let path = Path::from("data.txt");
    let data = Bytes::from("hello world");
    store.put(&path, data.into()).await?;
    Ok(())
}
```

--------------------------------

### Run All Tests

Source: https://github.com/apache/arrow-rs-object-store/blob/main/CONTRIBUTING.md

Execute all tests in the project using Cargo.

```shell
cargo test
```

--------------------------------

### Get Total Content Length of PutPayload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/payload.md

Calculates the total byte length of all chunks within a PutPayload. This operation has O(n) complexity, where n is the number of chunks.

```rust
pub fn content_length(&self) -> usize

```

--------------------------------

### Build for Wasm Target

Source: https://github.com/apache/arrow-rs-object-store/blob/main/README.md

Use this command to build the object_store crate for the `wasm32-unknown-unknown` target. Note that cloud storage features are not supported for this target.

```bash
cargo build -p object_store --target wasm32-unknown-unknown
```

--------------------------------

### get

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/objectstore-core.md

Retrieve the entire content of an object at the specified location. This method fetches the complete object data without any conditions or range specifications, returning the result as `GetResult`.

```APIDOC
## get

### Description
Retrieve entire object without conditions or ranges.

### Method
`async fn get(&self, location: &Path) -> Result<GetResult>`

### Parameters
#### Path Parameters
- **location** (`&Path`) - Required - Object path
```

--------------------------------

### From<&str>

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/path.md

Creates a Path object by percent-encoding a string slice.

```APIDOC
## From<&str>

### Description
Create a Path by percent-encoding a string.

### Example
```rust
let p = Path::from("foo/bar");
```
```

--------------------------------

### Handling Invalid Paths

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

This example shows how to catch 'InvalidPath' errors, which occur when a provided path does not meet the object_store's validation requirements. It logs the specific path error.

```rust
use object_store::{Error, path};

match path::Path::parse(user_input) {
    Ok(p) => { /* use path */ } 
    Err(path_err) => {
        eprintln!("Invalid path: {:?}", path_err);
    }
}

// Or catch the Error variant
match store.get(&path).await {
    Err(Error::InvalidPath { source }) => {
        eprintln!("Path error: {}", source);
    }
    _ => {}
}
```

--------------------------------

### Create AWS S3 Builder from Environment

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Initialize an AmazonS3Builder using credentials and configuration found in environment variables. This builder can then be used to construct an S3 store.

```rust
use object_store::aws::AmazonS3Builder;

let builder = AmazonS3Builder::from_env();
let store = builder
    .with_bucket_name("my-bucket")
    .build()?;
```

--------------------------------

### Parse URL to create ObjectStore and Path

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/configuration.md

Parses a URL to create an ObjectStore and extract the object path. Supported schemes include s3, gs, abfs, file, memory, http, and https.

```rust
use url::Url;
use object_store::parse_url;

let url = Url::parse("s3://my-bucket/data/file.parquet")?;
let (store, path) = parse_url(&url)?;
// store: Arc<dyn ObjectStore>
// path: Path::from("data/file.parquet")
```

--------------------------------

### AmazonS3Builder from environment variables

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/storage-builders.md

Build an Amazon S3 object store client using credentials and bucket name from environment variables.

```rust
use object_store::aws::AmazonS3Builder;
use object_store::ObjectStore;

let store = AmazonS3Builder::from_env()
    .with_bucket_name("my-bucket")
    .build()?;

```

--------------------------------

### Rust: Conditional Get with Caching

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

Implements a pattern for fetching data from an object store, utilizing caching with ETags. It checks for `NotModified` errors to return cached data efficiently.

```rust
use object_store::{Error, GetOptions, ObjectStoreExt, Path};

async fn get_with_cache(
    store: &dyn ObjectStore,
    path: &Path,
    cached: Option<(String, Bytes)>, // (etag, data)
) -> Result<Bytes, Box<dyn std::error::Error>> {
    if let Some((etag, data)) = cached {
        let opts = GetOptions::new().with_if_none_match(Some(etag));
        match store.get_opts(path, opts).await {
            Ok(result) => Ok(result.bytes().await?),
            Err(Error::NotModified { .. }) => Ok(data),
            Err(e) => Err(e.into()),
        }
    } else {
        Ok(store.get(path).await?.bytes().await?)
    }
}
```

--------------------------------

### S3 Object Store Configuration and Usage

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/README.md

Shows how to configure and use the Amazon S3 backend for object storage operations. It assumes AWS credentials and bucket name are configured via environment variables.

```rust
use object_store::aws::AmazonS3Builder;
use object_store::ObjectStoreExt;
use object_store::Path;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let store = AmazonS3Builder::from_env()
        .with_bucket_name("my-bucket")
        .build()?;
    
    let path = Path::from("data/file.txt");
    store.put(&path, b"data".into()).await?;
    Ok(())
}
```

--------------------------------

### Verify Release Candidate Script

Source: https://github.com/apache/arrow-rs-object-store/blob/main/dev/release/README.md

Use this script to automate the verification of a release candidate tarball. Provide the version and release candidate number as arguments.

```shell
./dev/release/verify-release-candidate.sh 0.11.0 1
```

--------------------------------

### Catching Unauthenticated Errors in Rust

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/errors.md

Shows how to catch and handle the Unauthenticated error during operations like `get`. It advises checking credential configurations and mentions the possibility of triggering a re-authentication flow.

```rust
use object_store::Error;

match store.get(&path).await {
    Err(Error::Unauthenticated { path, .. }) => {
        eprintln!("Authentication failed for path: {}", path);
        eprintln!("Check credentials configuration");
        // Could trigger re-authentication flow
    }
    _ => {}
}
```

--------------------------------

### Simple Streaming Upload

Source: https://github.com/apache/arrow-rs-object-store/blob/main/_autodocs/api-reference/multipart-upload.md

Upload a file by streaming its content in chunks. Requires opening a local file and initiating a multipart upload.

```rust
use object_store::{ObjectStore, ObjectStoreExt, WriteMultipart, Path};
use tokio::fs::File;
use tokio::io::AsyncReadExt;

async fn upload_file(
    store: &dyn ObjectStore,
    local_path: &str,
    remote_path: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    let mut file = File::open(local_path).await?;
    let path = Path::from(remote_path);
    let upload = store.put_multipart(&path).await?;
    let mut writer = WriteMultipart::new(upload);
    
    // Stream in 1MB chunks
    let mut buffer = vec![0u8; 1024 * 1024];
    loop {
        let bytes_read = file.read(&mut buffer).await?;
        if bytes_read == 0 {
            break;
        }
        writer.write(&buffer[..bytes_read]).await?;
    }
    
    writer.finish().await?;
    println!("Upload complete");
    Ok(())
}
```