Struct ReadOptions 

pub struct ReadOptions {

    pub range: BytesRange,
    pub version: Option<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_modified_since: Option<Timestamp>,
    pub if_unmodified_since: Option<Timestamp>,
    pub content_length_hint: Option<u64>,
    pub concurrent: usize,
    pub chunk: Option<usize>,
    pub gap: Option<usize>,
    pub override_content_type: Option<String>,
    pub override_cache_control: Option<String>,
    pub override_content_disposition: Option<String>,
}

Options for read operations.

Each condition checks the file being read, and every condition must hold for the read to proceed. A missing file fails the read with crate::ErrorKind::NotFound no matter which conditions are set. An existing file that fails a condition returns crate::ErrorKind::ConditionNotMatch, and a condition the service does not advertise through its capability returns crate::ErrorKind::Unsupported; OpenDAL never silently drops a condition.

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

Fields

range: BytesRange

Set range for this operation.

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
• BytesRange::suffix(1024) means read the last min(1024, n) bytes of file

The type implements From<RangeBounds<u64>>, so users can use (1024..).into() instead.

version: Option<String>

Read the given version of the file instead of the current one.

This selects which stored version the read returns; it is not a condition on the file. A version that does not exist returns crate::ErrorKind::NotFound.

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

if_match: Option<String>

Read only when the file has this exact ETag.

The condition succeeds when the file exists and its ETag equals this value. A file with a different ETag returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound. 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::read_with_if_match.

if_none_match: Option<String>

Read only when the file does not have this ETag.

With a concrete ETag value, the condition succeeds when the file exists with a different ETag. A file whose ETag equals this value returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound. 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::read_with_if_none_match.

if_version_match: Option<String>

Read only when the file has this exact version.

The condition succeeds when the file exists and its version equals this value. A file with a different version returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound.

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

if_version_not_match: Option<String>

Read only when the file does not have this version.

The condition succeeds when the file exists with a different version. A file whose version equals this value returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound.

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

if_modified_since: Option<Timestamp>

Read only when the file was modified after this timestamp.

The condition succeeds when the file exists and was modified after this time. A file not modified since this time returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound.

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

if_unmodified_since: Option<Timestamp>

Read only when the file was not modified after this timestamp.

The condition succeeds when the file exists and was not modified after this time. A file modified after this time returns crate::ErrorKind::ConditionNotMatch; a missing file returns crate::ErrorKind::NotFound.

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

content_length_hint: Option<u64>

Known content length of the object.

This is an execution hint that allows OpenDAL to avoid extra metadata requests while planning reads. It must not be used as an object identity or consistency condition.

concurrent: usize

Set concurrent for the operation.

OpenDAL by default to read 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.

Refer to the performance guide for more details.

chunk: Option<usize>

Set chunk for the operation.

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

Refer to the performance guide for more details.

gap: Option<usize>

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

When performing range reads, if the gap between two requested ranges is less than or equal to 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.

Set to 0 to disable merging ranges separated by a gap. Overlapping or adjacent ranges are still merged.

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.

Refer to the performance guide for more details.

override_content_type: Option<String>

Specify the content-type header that should be sent back by the operation.

This option is only meaningful when used along with presign.

override_cache_control: Option<String>

Specify the cache-control header that should be sent back by the operation.

This option is only meaningful when used along with presign.

override_content_disposition: Option<String>

Specify the content-disposition header that should be sent back by the operation.

This option is only meaningful when used along with presign.

Trait Implementations

impl Clone for ReadOptions

fn clone(&self) -> ReadOptions

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ReadOptions

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

Formats the value using the given formatter.

impl Default for ReadOptions

fn default() -> ReadOptions

Returns the “default value” for a type.

impl Eq for ReadOptions

impl From<ReadOptions> for (BytesRange, OpRead, OpReader)

fn from(value: ReadOptions) -> Self

Converts to this type from the input type.

impl PartialEq for ReadOptions

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for ReadOptions