Struct WriteOptions 

pub struct WriteOptions {

    pub append: bool,
    pub cache_control: Option<String>,
    pub content_type: Option<String>,
    pub content_disposition: Option<String>,
    pub content_encoding: Option<String>,
    pub user_metadata: Option<HashMap<String, String>>,
    pub if_match: Option<String>,
    pub if_none_match: Option<String>,
    pub if_version_match: Option<String>,
    pub if_version_not_match: Option<String>,
    pub if_not_exists: bool,
    pub if_not_changed: Option<Metadata>,
    pub concurrent: usize,
    pub chunk: Option<usize>,
}

Options for write operations.

Each condition checks the file currently stored at the write path, and the service evaluates it atomically with the write’s visible commit:

• A false condition fails the write with crate::ErrorKind::ConditionNotMatch and leaves the previously visible file unchanged. Depending on the service, the error may surface when the write starts, while writing, or when closing the writer.
• A condition the service does not advertise through its capability fails the write with crate::ErrorKind::Unsupported; OpenDAL never silently drops a condition. A service that cannot preserve a combination of conditions also returns Unsupported.
• A service-side conflict unrelated to these conditions surfaces as crate::ErrorKind::Conflict.

See the conditional operation specification for the complete cross-operation contract.

Fields

append: bool

Sets append mode for this operation.

Capability

Check crate::Capability::write_can_append before using this option.

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.

cache_control: Option<String>

Sets Cache-Control header for this write operation.

Capability

Check crate::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

References

• MDN Cache-Control
• RFC 7234 Section 5.2

content_type: Option<String>

Sets Content-Type header for this write operation.

Capability

Check crate::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.

content_disposition: Option<String>

Sets Content-Disposition header for this write request.

Capability

Check crate::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.

content_encoding: Option<String>

Sets Content-Encoding header for this write request.

Capability

Check crate::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.

user_metadata: Option<HashMap<String, String>>

Sets user metadata for this write request.

Capability

Check crate::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.

if_match: Option<String>

Write only when the file at the write path has this exact ETag.

The condition succeeds when the file exists and its ETag equals this value. A file with a different ETag, or a missing file, fails the write with crate::ErrorKind::ConditionNotMatch. Only concrete ETag values are portable; a wildcard such as "*" has no portable meaning here.

The operation returns crate::ErrorKind::Unsupported when the service does not advertise crate::Capability::write_with_if_match.

if_none_match: Option<String>

Write only when the file at the write path does not have this ETag.

With a concrete ETag value, the condition succeeds when the file has a different ETag or does not exist; the write then replaces or creates the file. A file whose ETag equals this value fails the write with crate::ErrorKind::ConditionNotMatch. Only concrete ETag values are portable; a wildcard such as "*" has no portable meaning here.

The operation returns crate::ErrorKind::Unsupported when the service does not advertise crate::Capability::write_with_if_none_match. Some services, such as s3, support if_not_exists but not if_none_match; use WriteOptions::if_not_exists when you only need to guard against an existing file.

if_version_match: Option<String>

Write only when the file at the write path has this exact version.

The condition succeeds when the file exists and its version equals this value. A file with a different version, or a missing file, fails the write with crate::ErrorKind::ConditionNotMatch.

The operation returns crate::ErrorKind::Unsupported when the service does not advertise crate::Capability::write_with_if_version_match.

if_version_not_match: Option<String>

Write only when the file at the write path does not have this version.

The condition succeeds when the file exists with a different version. A file whose version equals this value fails the write with crate::ErrorKind::ConditionNotMatch. When no file exists at the write path, no portable behavior is defined.

The operation returns crate::ErrorKind::Unsupported when the service does not advertise crate::Capability::write_with_if_version_not_match.

if_not_exists: bool

Write only when no file exists at the write path.

The condition succeeds when the path is empty, so the write creates the file. An existing file fails the write with crate::ErrorKind::ConditionNotMatch.

The operation returns crate::ErrorKind::Unsupported when the service does not advertise crate::Capability::write_with_if_not_exists.

if_not_changed: Option<Metadata>

Write only when the file at the write path still has the identity recorded in this metadata.

Pass metadata previously returned by OpenDAL for the same path. OpenDAL derives a version match when the service supports version conditions and the metadata contains a version. Otherwise it derives an ETag match when possible. A changed or missing file fails the write with crate::ErrorKind::ConditionNotMatch, as does combining this option with a conflicting if_match or if_version_match value.

The operation returns crate::ErrorKind::Unsupported when the service does not support the derived primitive condition, and crate::ErrorKind::ConfigInvalid when the metadata contains neither a version nor an ETag.

concurrent: usize

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

chunk: Option<usize>

Sets chunk size for buffered writes.

Capability

Check crate::Capability::write_multi_min_size and crate::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

Trait Implementations

impl Clone for WriteOptions

fn clone(&self) -> WriteOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for WriteOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for WriteOptions

fn default() -> WriteOptions

Returns the “default value” for a type.

impl PartialEq for WriteOptions

fn eq(&self, other: &WriteOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for WriteOptions

impl StructuralPartialEq for WriteOptions