Struct opendal::operator_futures::OperatorFuture

pub struct OperatorFuture<I, O, F: Future<Output = Result<O>>> { /* private fields */ }

OperatorFuture is the future generated by Operator.

The future will consume all the input to generate a future.

NOTES

This struct is by design to keep in crate. We don’t want users to use this struct directly.

Implementations

impl<F: Future<Output = Result<Metadata>>> OperatorFuture<OpStat, Metadata, F>

pub fn if_match(self, v: &str) -> Self

Set the If-Match for this operation.

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match for this operation.

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

Set the If-Modified-Since for this operation.

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set the If-Unmodified-Since for this operation.

pub fn version(self, v: &str) -> Self

Set the version for this operation.

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpStat, Duration), PresignedRequest, F>

pub fn override_content_disposition(self, v: &str) -> Self

Sets the content-disposition header that should be sent back by the remote read operation.

pub fn override_cache_control(self, v: &str) -> Self

Sets the cache-control header that should be sent back by the remote read operation.

pub fn override_content_type(self, v: &str) -> Self

Sets the content-type header that should be sent back by the remote read operation.

pub fn if_match(self, v: &str) -> Self

Set the If-Match of the option

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match of the option

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpRead, Duration), PresignedRequest, F>

pub fn override_content_disposition(self, v: &str) -> Self

Sets the content-disposition header that should be sent back by the remote read operation.

pub fn override_cache_control(self, v: &str) -> Self

Sets the cache-control header that should be sent back by the remote read operation.

pub fn override_content_type(self, v: &str) -> Self

Sets the content-type header that should be sent back by the remote read operation.

pub fn if_match(self, v: &str) -> Self

Set the If-Match of the option

pub fn if_none_match(self, v: &str) -> Self

Set the If-None-Match of the option

impl<F: Future<Output = Result<PresignedRequest>>> OperatorFuture<(OpWrite, Duration), PresignedRequest, F>

pub fn content_type(self, v: &str) -> Self

Set the content type of option

pub fn content_disposition(self, v: &str) -> Self

Set the content disposition of option

pub fn cache_control(self, v: &str) -> Self

Set the content type of option

impl<F: Future<Output = Result<Buffer>>> OperatorFuture<(OpRead, OpReader), Buffer, F>

pub fn executor(self, executor: Executor) -> Self

Set the executor for this operation.

pub fn range(self, range: impl RangeBounds<u64>) -> Self

Set range for this read request.

If we have a file with size n.

• .. means read bytes in range [0, n) of file.
• 0..1024 and ..1024 means read bytes in range [0, 1024) of file
• 1024.. means read bytes in range [1024, n) of file

let bs = op.read_with("path/to/file").range(0..1024).await?;

pub fn concurrent(self, concurrent: usize) -> Self

Set concurrent for the reader.

OpenDAL by default to write file without concurrent. This is not efficient for cases when users read large chunks of data. By setting concurrent, opendal will read files concurrently on support storage services.

By setting concurrent, opendal will fetch chunks concurrently with the given chunk size.

let r = op.read_with("path/to/file").concurrent(8).await?;

pub fn chunk(self, chunk_size: usize) -> Self

OpenDAL will use services’ preferred chunk size by default. Users can set chunk based on their own needs.

This following example will make opendal read data in 4MiB chunks:

let r = op.read_with("path/to/file").chunk(4 * 1024 * 1024).await?;

pub fn version(self, v: &str) -> Self

Set version for this read request.

This feature can be used to retrieve the data of a specified version of the given path.

If the version doesn’t exist, an error with kind ErrorKind::NotFound will be returned.

let mut bs = op.read_with("path/to/file").version(version).await?;

pub fn if_match(self, v: &str) -> Self

Set if_match for this read request.

This feature can be used to check if the file’s ETag matches the given ETag.

If file exists and it’s etag doesn’t match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut metadata = op.read_with("path/to/file").if_match(etag).await?;

pub fn if_none_match(self, v: &str) -> Self

Set if_none_match for this read request.

This feature can be used to check if the file’s ETag doesn’t match the given ETag.

If file exists and it’s etag match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut metadata = op.read_with("path/to/file").if_none_match(etag).await?;

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

if_modified_since

Set if_modified_since for this read request.

This feature can be used to check if the file has been modified since the given timestamp.

If file exists and it hasn’t been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut metadata = op.read_with("path/to/file").if_modified_since(time).await?;

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set if_unmodified_since for this read request.

This feature can be used to check if the file hasn’t been modified since the given timestamp.

If file exists and it has been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut metadata = op.read_with("path/to/file").if_unmodified_since(time).await?;

impl<F: Future<Output = Result<Reader>>> OperatorFuture<(OpRead, OpReader), Reader, F>

pub fn version(self, v: &str) -> Self

Set version for this reader.

This feature can be used to retrieve the data of a specified version of the given path.

If the version doesn’t exist, an error with kind ErrorKind::NotFound will be returned.

let mut r = op.reader_with("path/to/file").version(version).await?;

pub fn concurrent(self, concurrent: usize) -> Self

Set concurrent for the reader.

OpenDAL by default to write file without concurrent. This is not efficient for cases when users read large chunks of data. By setting concurrent, opendal will reading files concurrently on support storage services.

By setting concurrent, opendal will fetch chunks concurrently with the give chunk size.

let r = op.reader_with("path/to/file").concurrent(8).await?;

pub fn chunk(self, chunk_size: usize) -> Self

OpenDAL will use services’ preferred chunk size by default. Users can set chunk based on their own needs.

This following example will make opendal read data in 4MiB chunks:

let r = op
    .reader_with("path/to/file")
    .chunk(4 * 1024 * 1024)
    .await?;

pub fn gap(self, gap_size: usize) -> Self

Controls the optimization strategy for range reads in Reader::fetch.

When performing range reads, if the gap between two requested ranges is smaller than the configured gap size, OpenDAL will merge these ranges into a single read request and discard the unrequested data in between. This helps reduce the number of API calls to remote storage services.

This optimization is particularly useful when performing multiple small range reads that are close to each other, as it reduces the overhead of multiple network requests at the cost of transferring some additional data.

In this example, if two requested ranges are separated by less than 1MiB, they will be merged into a single read request:

let r = op
    .reader_with("path/to/file")
    .chunk(4 * 1024 * 1024)
    .gap(1024 * 1024)  // 1MiB gap
    .await?;

pub fn if_match(self, etag: &str) -> Self

Set if-match for this read request.

This feature can be used to check if the file’s ETag matches the given ETag.

If file exists and it’s etag doesn’t match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut r = op.reader_with("path/to/file").if_match(etag).await?;

pub fn if_none_match(self, etag: &str) -> Self

Set if-none-match for this read request.

This feature can be used to check if the file’s ETag doesn’t match the given ETag.

If file exists and it’s etag match, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
let mut r = op.reader_with("path/to/file").if_none_match(etag).await?;

pub fn if_modified_since(self, v: DateTime<Utc>) -> Self

Set if-modified-since for this read request.

This feature can be used to check if the file has been modified since the given timestamp.

If file exists and it hasn’t been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut r = op.reader_with("path/to/file").if_modified_since(time).await?;

pub fn if_unmodified_since(self, v: DateTime<Utc>) -> Self

Set if-unmodified-since for this read request.

This feature can be used to check if the file hasn’t been modified since the given timestamp.

If file exists and it has been modified since the specified time, an error with kind ErrorKind::ConditionNotMatch will be returned.

use opendal::Operator;
use chrono::DateTime;
use chrono::Utc;
let mut r = op.reader_with("path/to/file").if_unmodified_since(time).await?;

impl<F: Future<Output = Result<()>>> OperatorFuture<(OpWrite, OpWriter, Buffer), (), F>

pub fn executor(self, executor: Executor) -> Self

Set the executor for this operation.

pub fn append(self, v: bool) -> Self

Sets append mode for this write request.

Capability

Check Capability::write_can_append before using this feature.

Behavior

• By default, write operations overwrite existing files
• When append is set to true:
  • New data will be appended to the end of existing file
  • If file doesn’t exist, it will be created
• If not supported, will return an error

This operation allows adding data to existing files instead of overwriting them.

Example

use bytes::Bytes;

let _ = op.write_with("path/to/file", vec![0; 4096]).append(true).await?;

pub fn chunk(self, v: usize) -> Self

Sets chunk size for buffered writes.

Capability

Check Capability::write_multi_min_size and Capability::write_multi_max_size for size limits.

Behavior

• By default, OpenDAL sets optimal chunk size based on service capabilities
• When chunk size is set:
  • Data will be buffered until reaching chunk size
  • One API call will be made per chunk
  • Last chunk may be smaller than chunk size
• Important considerations:
  • Some services require minimum chunk sizes (e.g. S3’s EntityTooSmall error)
  • Smaller chunks increase API calls and costs
  • Larger chunks increase memory usage, but improve performance and reduce costs

Performance Impact

Setting appropriate chunk size can:

• Reduce number of API calls
• Improve overall throughput
• Lower operation costs
• Better utilize network bandwidth

Example

use bytes::Bytes;

// Set 8MiB chunk size - data will be sent in one API call at close
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .chunk(8 * 1024 * 1024)
    .await?;

pub fn concurrent(self, v: usize) -> Self

Sets concurrent write operations for this writer.

Behavior

• By default, OpenDAL writes files sequentially
• When concurrent is set:
  • Multiple write operations can execute in parallel
  • Write operations return immediately without waiting if tasks space are available
  • Close operation ensures all writes complete in order
  • Memory usage increases with concurrency level
• If not supported, falls back to sequential writes

This feature significantly improves performance when:

• Writing large files
• Network latency is high
• Storage service supports concurrent uploads like multipart uploads

Performance Impact

Setting appropriate concurrency can:

• Increase write throughput
• Reduce total write time
• Better utilize available bandwidth
• Trade memory for performance

Example

use bytes::Bytes;

// Enable concurrent writes with 8 parallel operations at 128B chunk.
let _ = op.write_with("path/to/file", vec![0; 4096]).chunk(128).concurrent(8).await?;

pub fn cache_control(self, v: &str) -> Self

Sets Cache-Control header for this write operation.

Capability

Check Capability::write_with_cache_control before using this feature.

Behavior

• If supported, sets Cache-Control as system metadata on the target file
• The value should follow HTTP Cache-Control header format
• If not supported, the value will be ignored

This operation allows controlling caching behavior for the written content.

Use Cases

• Setting browser cache duration
• Configuring CDN behavior
• Optimizing content delivery
• Managing cache invalidation

Example

use bytes::Bytes;

// Cache content for 7 days (604800 seconds)
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .cache_control("max-age=604800")
    .await?;

References

• MDN Cache-Control
• RFC 7234 Section 5.2

pub fn content_type(self, v: &str) -> Self

Sets Content-Type header for this write operation.

Capability

Check Capability::write_with_content_type before using this feature.

Behavior

• If supported, sets Content-Type as system metadata on the target file
• The value should follow MIME type format (e.g. “text/plain”, “image/jpeg”)
• If not supported, the value will be ignored

This operation allows specifying the media type of the content being written.

Example

use bytes::Bytes;

// Set content type for plain text file
let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_type("text/plain")
    .await?;

pub fn content_disposition(self, v: &str) -> Self

content_disposition

Sets Content-Disposition header for this write request.

Capability

Check Capability::write_with_content_disposition before using this feature.

Behavior

• If supported, sets Content-Disposition as system metadata on the target file
• The value should follow HTTP Content-Disposition header format
• Common values include:
  • inline - Content displayed within browser
  • attachment - Content downloaded as file
  • attachment; filename="example.jpg" - Downloaded with specified filename
• If not supported, the value will be ignored

This operation allows controlling how the content should be displayed or downloaded.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_disposition("attachment; filename=\"filename.jpg\"")
    .await?;

pub fn content_encoding(self, v: &str) -> Self

Sets Content-Encoding header for this write request.

Capability

Check Capability::write_with_content_encoding before using this feature.

Behavior

• If supported, sets Content-Encoding as system metadata on the target file
• The value should follow HTTP Content-Encoding header format
• Common values include:
  • gzip - Content encoded using gzip compression
  • deflate - Content encoded using deflate compression
  • br - Content encoded using Brotli compression
  • identity - No encoding applied (default value)
• If not supported, the value will be ignored

This operation allows specifying the encoding applied to the content being written.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .content_encoding("gzip")
    .await?;

pub fn if_match(self, s: &str) -> Self

Sets If-Match header for this write request.

Capability

Check Capability::write_with_if_match before using this feature.

Behavior

• If supported, the write operation will only succeed if the target’s ETag matches the specified value
• The value should be a valid ETag string
• Common values include:
  • A specific ETag value like "686897696a7c876b7e"
  • * - Matches any existing resource
• If not supported, the value will be ignored

This operation provides conditional write functionality based on ETag matching, helping prevent unintended overwrites in concurrent scenarios.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_match("\"686897696a7c876b7e\"")
    .await?;

pub fn if_none_match(self, s: &str) -> Self

Sets If-None-Match header for this write request.

Note: Certain services, like s3, support if_not_exists but not if_none_match. Use if_not_exists if you only want to check whether a file exists.

Capability

Check Capability::write_with_if_none_match before using this feature.

Behavior

• If supported, the write operation will only succeed if the target’s ETag does not match the specified value
• The value should be a valid ETag string
• Common values include:
  • A specific ETag value like "686897696a7c876b7e"
  • * - Matches if the resource does not exist
• If not supported, the value will be ignored

This operation provides conditional write functionality based on ETag non-matching, useful for preventing overwriting existing resources or ensuring unique writes.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_none_match("\"686897696a7c876b7e\"")
    .await?;

pub fn if_not_exists(self, b: bool) -> Self

Sets the condition that write operation will succeed only if target does not exist.

Capability

Check Capability::write_with_if_not_exists before using this feature.

Behavior

• If supported, the write operation will only succeed if the target path does not exist
• Will return error if target already exists
• If not supported, the value will be ignored

This operation provides a way to ensure write operations only create new resources without overwriting existing ones, useful for implementing “create if not exists” logic.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .if_not_exists(true)
    .await?;

pub fn user_metadata( self, data: impl IntoIterator<Item = (String, String)>, ) -> Self

Sets user metadata for this write request.

Capability

Check Capability::write_with_user_metadata before using this feature.

Behavior

• If supported, the user metadata will be attached to the object during write
• Accepts key-value pairs where both key and value are strings
• Keys are case-insensitive in most services
• Services may have limitations for user metadata, for example:
  • Key length is typically limited (e.g., 1024 bytes)
  • Value length is typically limited (e.g., 4096 bytes)
  • Total metadata size might be limited
  • Some characters might be forbidden in keys
• If not supported, the metadata will be ignored

User metadata provides a way to attach custom metadata to objects during write operations. This metadata can be retrieved later when reading the object.

Example

use bytes::Bytes;

let _ = op
    .write_with("path/to/file", vec![0; 4096])
    .user_metadata([
        ("language".to_string(), "rust".to_string()),
        ("author".to_string(), "OpenDAL".to_string()),
    ])
    .await?;

impl<F: Future<Output = Result<Writer>>> OperatorFuture<(OpWrite, OpWriter), Writer, F>

pub fn executor(self, executor: Executor) -> Self

Set the executor for this operation.

pub fn append(self, v: bool) -> Self

Sets append mode for this write request.

Capability

Check Capability::write_can_append before using this feature.

Behavior

• By default, write operations overwrite existing files
• When append is set to true:
  • New data will be appended to the end of existing file
  • If file doesn’t exist, it will be created
• If not supported, will return an error

This operation allows adding data to existing files instead of overwriting them.

Example

use bytes::Bytes;

let mut w = op.writer_with("path/to/file").append(true).await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn chunk(self, v: usize) -> Self

Sets chunk size for buffered writes.

Capability

Check Capability::write_multi_min_size and Capability::write_multi_max_size for size limits.

Behavior

• By default, OpenDAL sets optimal chunk size based on service capabilities
• When chunk size is set:
  • Data will be buffered until reaching chunk size
  • One API call will be made per chunk
  • Last chunk may be smaller than chunk size
• Important considerations:
  • Some services require minimum chunk sizes (e.g. S3’s EntityTooSmall error)
  • Smaller chunks increase API calls and costs
  • Larger chunks increase memory usage, but improve performance and reduce costs

Performance Impact

Setting appropriate chunk size can:

• Reduce number of API calls
• Improve overall throughput
• Lower operation costs
• Better utilize network bandwidth

Example

use bytes::Bytes;

// Set 8MiB chunk size - data will be sent in one API call at close
let mut w = op
    .writer_with("path/to/file")
    .chunk(8 * 1024 * 1024)
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn concurrent(self, v: usize) -> Self

Sets concurrent write operations for this writer.

Behavior

• By default, OpenDAL writes files sequentially
• When concurrent is set:
  • Multiple write operations can execute in parallel
  • Write operations return immediately without waiting if tasks space are available
  • Close operation ensures all writes complete in order
  • Memory usage increases with concurrency level
• If not supported, falls back to sequential writes

This feature significantly improves performance when:

• Writing large files
• Network latency is high
• Storage service supports concurrent uploads like multipart uploads

Performance Impact

Setting appropriate concurrency can:

• Increase write throughput
• Reduce total write time
• Better utilize available bandwidth
• Trade memory for performance

Example

use bytes::Bytes;

// Enable concurrent writes with 8 parallel operations
let mut w = op.writer_with("path/to/file").concurrent(8).await?;

// First write starts immediately
w.write(vec![0; 4096]).await?;

// Second write runs concurrently with first
w.write(vec![1; 4096]).await?;

// Ensures all writes complete successfully and in order
w.close().await?;

pub fn cache_control(self, v: &str) -> Self

Sets Cache-Control header for this write operation.

Capability

Check Capability::write_with_cache_control before using this feature.

Behavior

• If supported, sets Cache-Control as system metadata on the target file
• The value should follow HTTP Cache-Control header format
• If not supported, the value will be ignored

This operation allows controlling caching behavior for the written content.

Use Cases

• Setting browser cache duration
• Configuring CDN behavior
• Optimizing content delivery
• Managing cache invalidation

Example

use bytes::Bytes;

// Cache content for 7 days (604800 seconds)
let mut w = op
    .writer_with("path/to/file")
    .cache_control("max-age=604800")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

References

• MDN Cache-Control
• RFC 7234 Section 5.2

pub fn content_type(self, v: &str) -> Self

Sets Content-Type header for this write operation.

Capability

Check Capability::write_with_content_type before using this feature.

Behavior

• If supported, sets Content-Type as system metadata on the target file
• The value should follow MIME type format (e.g. “text/plain”, “image/jpeg”)
• If not supported, the value will be ignored

This operation allows specifying the media type of the content being written.

Example

use bytes::Bytes;

// Set content type for plain text file
let mut w = op
    .writer_with("path/to/file")
    .content_type("text/plain")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn content_disposition(self, v: &str) -> Self

content_disposition

Sets Content-Disposition header for this write request.

Capability

Check Capability::write_with_content_disposition before using this feature.

Behavior

• If supported, sets Content-Disposition as system metadata on the target file
• The value should follow HTTP Content-Disposition header format
• Common values include:
  • inline - Content displayed within browser
  • attachment - Content downloaded as file
  • attachment; filename="example.jpg" - Downloaded with specified filename
• If not supported, the value will be ignored

This operation allows controlling how the content should be displayed or downloaded.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .content_disposition("attachment; filename=\"filename.jpg\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn content_encoding(self, v: &str) -> Self

Sets Content-Encoding header for this write request.

Capability

Check Capability::write_with_content_encoding before using this feature.

Behavior

• If supported, sets Content-Encoding as system metadata on the target file
• The value should follow HTTP Content-Encoding header format
• Common values include:
  • gzip - Content encoded using gzip compression
  • deflate - Content encoded using deflate compression
  • br - Content encoded using Brotli compression
  • identity - No encoding applied (default value)
• If not supported, the value will be ignored

This operation allows specifying the encoding applied to the content being written.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .content_encoding("gzip")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_match(self, s: &str) -> Self

Sets If-Match header for this write request.

Capability

Check Capability::write_with_if_match before using this feature.

Behavior

• If supported, the write operation will only succeed if the target’s ETag matches the specified value
• The value should be a valid ETag string
• Common values include:
  • A specific ETag value like "686897696a7c876b7e"
  • * - Matches any existing resource
• If not supported, the value will be ignored

This operation provides conditional write functionality based on ETag matching, helping prevent unintended overwrites in concurrent scenarios.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_match("\"686897696a7c876b7e\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_none_match(self, s: &str) -> Self

Sets If-None-Match header for this write request.

Note: Certain services, like s3, support if_not_exists but not if_none_match. Use if_not_exists if you only want to check whether a file exists.

Capability

Check Capability::write_with_if_none_match before using this feature.

Behavior

• If supported, the write operation will only succeed if the target’s ETag does not match the specified value
• The value should be a valid ETag string
• Common values include:
  • A specific ETag value like "686897696a7c876b7e"
  • * - Matches if the resource does not exist
• If not supported, the value will be ignored

This operation provides conditional write functionality based on ETag non-matching, useful for preventing overwriting existing resources or ensuring unique writes.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_none_match("\"686897696a7c876b7e\"")
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn if_not_exists(self, b: bool) -> Self

Sets the condition that write operation will succeed only if target does not exist.

Capability

Check Capability::write_with_if_not_exists before using this feature.

Behavior

• If supported, the write operation will only succeed if the target path does not exist
• Will return error if target already exists
• If not supported, the value will be ignored

This operation provides a way to ensure write operations only create new resources without overwriting existing ones, useful for implementing “create if not exists” logic.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .if_not_exists(true)
    .await?;
w.write(vec![0; 4096]).await?;
w.write(vec![1; 4096]).await?;
w.close().await?;

pub fn user_metadata( self, data: impl IntoIterator<Item = (String, String)>, ) -> Self

Sets user metadata for this write request.

Capability

Check Capability::write_with_user_metadata before using this feature.

Behavior

• If supported, the user metadata will be attached to the object during write
• Accepts key-value pairs where both key and value are strings
• Keys are case-insensitive in most services
• Services may have limitations for user metadata, for example:
  • Key length is typically limited (e.g., 1024 bytes)
  • Value length is typically limited (e.g., 4096 bytes)
  • Total metadata size might be limited
  • Some characters might be forbidden in keys
• If not supported, the metadata will be ignored

User metadata provides a way to attach custom metadata to objects during write operations. This metadata can be retrieved later when reading the object.

Example

use bytes::Bytes;

let mut w = op
    .writer_with("path/to/file")
    .user_metadata([
        ("content-type".to_string(), "text/plain".to_string()),
        ("author".to_string(), "OpenDAL".to_string()),
    ])
    .await?;
w.write(vec![0; 4096]).await?;
w.close().await?;

impl<F: Future<Output = Result<()>>> OperatorFuture<OpDelete, (), F>

pub fn version(self, v: &str) -> Self

Change the version of this delete operation.

impl<F: Future<Output = Result<Vec<Entry>>>> OperatorFuture<OpList, Vec<Entry>, F>

pub fn limit(self, v: usize) -> Self

The limit passed to underlying service to specify the max results that could return per-request.

Users could use this to control the memory usage of list operation.

pub fn start_after(self, v: &str) -> Self

The start_after passes to underlying service to specify the specified key to start listing from.

pub fn recursive(self, v: bool) -> Self

The recursive is used to control whether the list operation is recursive.

• If false, list operation will only list the entries under the given path.
• If true, list operation will list all entries that starts with given path.

Default to false.

pub fn version(self, v: bool) -> Self

👎Deprecated since 0.51.1: use versions instead

The version is used to control whether the object versions should be returned.

• If false, list operation will not return with object versions
• If true, list operation will return with object versions if object versioning is supported by the underlying service

Default to false

pub fn versions(self, v: bool) -> Self

Controls whether the list operation should return file versions.

This function allows you to specify if the list operation, when executed, should include information about different versions of files, if versioning is supported and enabled.

If true, subsequent list operations will include version information for each file. If false, version information will be omitted from the list results.

Default to false

pub fn deleted(self, v: bool) -> Self

Controls whether the list operation should include deleted files (or versions).

This function allows you to specify if the list operation, when executed, should include entries for files or versions that have been marked as deleted. This is particularly relevant in object storage systems that support soft deletion or versioning.

If true, subsequent list operations will include deleted files or versions. If false, deleted files or versions will be excluded from the list results.

impl<F: Future<Output = Result<Lister>>> OperatorFuture<OpList, Lister, F>

pub fn limit(self, v: usize) -> Self

The limit passed to underlying service to specify the max results that could return per-request.

Users could use this to control the memory usage of list operation.

pub fn start_after(self, v: &str) -> Self

The start_after passes to underlying service to specify the specified key to start listing from.

pub fn recursive(self, v: bool) -> Self

The recursive is used to control whether the list operation is recursive.

• If false, list operation will only list the entries under the given path.
• If true, list operation will list all entries that starts with given path.

Default to false.

pub fn version(self, v: bool) -> Self

👎Deprecated since 0.51.1: use versions instead

The version is used to control whether the object versions should be returned.

• If false, list operation will not return with object versions
• If true, list operation will return with object versions if object versioning is supported by the underlying service

Default to false

pub fn versions(self, v: bool) -> Self

Controls whether the list operation should return file versions.

This function allows you to specify if the list operation, when executed, should include information about different versions of files, if versioning is supported and enabled.

If true, subsequent list operations will include version information for each file. If false, version information will be omitted from the list results.

Default to false

pub fn deleted(self, v: bool) -> Self

Controls whether the list operation should include deleted files (or versions).

This function allows you to specify if the list operation, when executed, should include entries for files or versions that have been marked as deleted. This is particularly relevant in object storage systems that support soft deletion or versioning.

If true, subsequent list operations will include deleted files or versions. If false, deleted files or versions will be excluded from the list results.

Trait Implementations

impl<I, O, F> IntoFuture for OperatorFuture<I, O, F>

where F: Future<Output = Result<O>>,

type Output = Result<O, Error>

The output that the future will produce on completion.

type IntoFuture = F

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.