From fc66d2bab02b6a6fcb17159f7dc4dc43c9289996 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Wed, 22 May 2024 08:27:49 -0400 Subject: [PATCH] Minor: Improve ObjectStoreUrl docs + examples --- datafusion/execution/src/object_store.rs | 29 ++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/datafusion/execution/src/object_store.rs b/datafusion/execution/src/object_store.rs index c0c58a87dcc66..d9d6c414b91f6 100644 --- a/datafusion/execution/src/object_store.rs +++ b/datafusion/execution/src/object_store.rs @@ -27,7 +27,12 @@ use object_store::ObjectStore; use std::sync::Arc; use url::Url; -/// A parsed URL identifying a particular [`ObjectStore`] +/// A parsed URL identifying a particular [`ObjectStore`] instance +/// +/// For example: +/// * `file://` for local file system +/// * `s3://bucket` for AWS S3 bucket +/// * `oss://bucket` for Aliyun OSS bucket #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct ObjectStoreUrl { url: Url, @@ -35,6 +40,19 @@ pub struct ObjectStoreUrl { impl ObjectStoreUrl { /// Parse an [`ObjectStoreUrl`] from a string + /// + /// # Example + /// ``` + /// # use url::Url; + /// # use datafusion_execution::object_store::ObjectStoreUrl; + /// let object_store_url = ObjectStoreUrl::parse("s3://bucket").unwrap(); + /// assert_eq!(object_store_url.as_str(), "s3://bucket/"); + /// // can also access the underlying `Url` + /// let url: &Url = object_store_url.as_ref(); + /// assert_eq!(url.scheme(), "s3"); + /// assert_eq!(url.host_str(), Some("bucket")); + /// assert_eq!(url.path(), "/"); + /// ``` pub fn parse(s: impl AsRef) -> Result { let mut parsed = Url::parse(s.as_ref()).map_err(|e| DataFusionError::External(Box::new(e)))?; @@ -51,7 +69,14 @@ impl ObjectStoreUrl { Ok(Self { url: parsed }) } - /// An [`ObjectStoreUrl`] for the local filesystem + /// An [`ObjectStoreUrl`] for the local filesystem (`file://`) + /// + /// # Example + /// ``` + /// # use datafusion_execution::object_store::ObjectStoreUrl; + /// let local_fs = ObjectStoreUrl::parse("file://").unwrap(); + /// assert_eq!(local_fs, ObjectStoreUrl::local_filesystem()) + /// ``` pub fn local_filesystem() -> Self { Self::parse("file://").unwrap() }