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_not_exists: bool,
    pub concurrent: usize,
    pub chunk: Option<usize>,
}

Options for write operations.

Fields

append: bool

Sets append mode for this operation.

Capability

Check [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 [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 [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 [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 [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 [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>

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.

if_none_match: Option<String>

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.

if_not_exists: bool

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.

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 [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

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

Formats the value using the given formatter.

impl Default for WriteOptions

fn default() -> WriteOptions

Returns the “default value” for a type.

impl From<WriteOptions> for (OpWrite, OpWriter)

fn from(value: WriteOptions) -> Self

Converts to this type from the input 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