This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
The following commit(s) were added to refs/heads/main by this push:
new c3549836 doc: improve FileIO doc (#642)
c3549836 is described below
commit c3549836796f93aa3ad22276af788aa3d92533a1
Author: xxchan <[email protected]>
AuthorDate: Mon Sep 23 14:50:18 2024 +0800
doc: improve FileIO doc (#642)
Signed-off-by: xxchan <[email protected]>
---
crates/iceberg/src/io/file_io.rs | 16 +++++++++++++---
crates/iceberg/src/io/storage.rs | 1 +
2 files changed, 14 insertions(+), 3 deletions(-)
diff --git a/crates/iceberg/src/io/file_io.rs b/crates/iceberg/src/io/file_io.rs
index 9af39827..3a54b1b0 100644
--- a/crates/iceberg/src/io/file_io.rs
+++ b/crates/iceberg/src/io/file_io.rs
@@ -32,16 +32,25 @@ use crate::{Error, ErrorKind, Result};
///
/// All path passed to `FileIO` must be absolute path starting with scheme
string used to construct `FileIO`.
/// For example, if you construct `FileIO` with `s3a` scheme, then all path
passed to `FileIO` must start with `s3a://`.
+///
+/// Supported storages:
+///
+/// | Storage | Feature Flag | Schemes |
+/// |--------------------|-------------------|------------|
+/// | Local file system | `storage-fs` | `file` |
+/// | Memory | `storage-memory` | `memory` |
+/// | S3 | `storage-s3` | `s3`, `s3a`|
+/// | GCS | `storage-gcs` | `gs` |
#[derive(Clone, Debug)]
pub struct FileIO {
inner: Arc<Storage>,
}
impl FileIO {
- /// Try to infer file io scheme from path.
+ /// Try to infer file io scheme from path. See [`FileIO`] for supported
schemes.
///
- /// If it's a valid url, for example http://example.org, url scheme will
be used.
- /// If it's not a valid url, will try to detect if it's a file path.
+ /// - If it's a valid url, for example `s3://bucket/a`, url scheme will be
used, and the rest of the url will be ignored.
+ /// - If it's not a valid url, will try to detect if it's a file path.
///
/// Otherwise will return parsing error.
pub fn from_path(path: impl AsRef<str>) -> crate::Result<FileIOBuilder> {
@@ -111,6 +120,7 @@ pub struct FileIOBuilder {
impl FileIOBuilder {
/// Creates a new builder with scheme.
+ /// See [`FileIO`] for supported schemes.
pub fn new(scheme_str: impl ToString) -> Self {
Self {
scheme_str: Some(scheme_str.to_string()),
diff --git a/crates/iceberg/src/io/storage.rs b/crates/iceberg/src/io/storage.rs
index 682b1d33..89010444 100644
--- a/crates/iceberg/src/io/storage.rs
+++ b/crates/iceberg/src/io/storage.rs
@@ -69,6 +69,7 @@ impl Storage {
Scheme::Gcs => Ok(Self::Gcs {
config: super::gcs_config_parse(props)?.into(),
}),
+ // Update doc on [`FileIO`] when adding new schemes.
_ => Err(Error::new(
ErrorKind::FeatureUnsupported,
format!("Constructing file io from scheme: {scheme} not
supported now",),
