docs: Add an example to scan an iceberg table (#545)

* docs: Add an example to scan an iceberg table

Signed-off-by: Xuanwo <[email protected]>

* Format toml

Signed-off-by: Xuanwo <[email protected]>

---------

Signed-off-by: Xuanwo <[email protected]>

Cargo.toml

@@ -18,15 +18,13 @@
 [workspace]
 resolver = "2"
 members = [
-    "crates/catalog/*",
-    "crates/examples",
-    "crates/iceberg",
-    "crates/integrations/*",
-    "crates/test_utils",
-]
-exclude = [
-    "bindings/python"
+  "crates/catalog/*",
+  "crates/examples",
+  "crates/iceberg",
+  "crates/integrations/*",
+  "crates/test_utils",
 ]
+exclude = ["bindings/python"]
 
 [workspace.package]
 version = "0.2.0"
@@ -65,6 +63,7 @@ futures = "0.3"
 iceberg = { version = "0.2.0", path = "./crates/iceberg" }
 iceberg-catalog-rest = { version = "0.2.0", path = "./crates/catalog/rest" }
 iceberg-catalog-hms = { version = "0.2.0", path = "./crates/catalog/hms" }
+iceberg-catalog-memory = { version = "0.2.0", path = "./crates/catalog/memory" }
 itertools = "0.13"
 log = "^0.4"
 mockito = "^1"

crates/catalog/sql/Cargo.toml

@@ -38,6 +38,12 @@ typed-builder = { workspace = true }
 iceberg_test_utils = { path = "../../test_utils", features = ["tests"] }
 itertools = { workspace = true }
 regex = "1.10.5"
-sqlx = { version = "0.8.0", features = ["tls-rustls", "runtime-tokio", "any", "sqlite", "migrate"], default-features = false }
+sqlx = { version = "0.8.0", features = [
+  "tls-rustls",
+  "runtime-tokio",
+  "any",
+  "sqlite",
+  "migrate",
+], default-features = false }
 tempfile = { workspace = true }
 tokio = { workspace = true }

crates/iceberg/Cargo.toml

@@ -81,6 +81,7 @@ uuid = { workspace = true }
 
 [dev-dependencies]
 ctor = { workspace = true }
+iceberg-catalog-memory = { workspace = true }
 iceberg_test_utils = { path = "../test_utils", features = ["tests"] }
 pretty_assertions = { workspace = true }
 tempfile = { workspace = true }

crates/iceberg/README.md

@@ -25,3 +25,35 @@
 This crate contains the official Native Rust implementation of [Apache Iceberg](https://rust.iceberg.apache.org/).
 
 See the [API documentation](https://docs.rs/iceberg/latest) for examples and the full API.
+
+## Usage
+
+```rust
+use futures::TryStreamExt;
+use iceberg::io::{FileIO, FileIOBuilder};
+use iceberg::{Catalog, Result, TableIdent};
+use iceberg_catalog_memory::MemoryCatalog;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Build your file IO.
+    let file_io = FileIOBuilder::new("memory").build()?;
+    // Connect to a catalog.
+    let catalog = MemoryCatalog::new(file_io, None);
+    // Load table from catalog.
+    let table = catalog
+        .load_table(&TableIdent::from_strs(["hello", "world"])?)
+        .await?;
+    // Build table scan.
+    let stream = table
+        .scan()
+        .select(["name", "id"])
+        .build()?
+        .to_arrow()
+        .await?;
+
+    // Consume this stream like arrow record batch stream.
+    let _data: Vec<_> = stream. try_collect().await?;
+    Ok(())
+}
+```

crates/iceberg/src/lib.rs

@@ -15,7 +15,41 @@
 // specific language governing permissions and limitations
 // under the License.
 
-//! Native Rust implementation of Apache Iceberg
+//! Apache Iceberg Official Native Rust Implementation
+//!
+//! # Examples
+//!
+//! ## Scan A Table
+//!
+//! ```rust, no_run
+//! use futures::TryStreamExt;
+//! use iceberg::io::{FileIO, FileIOBuilder};
+//! use iceberg::{Catalog, Result, TableIdent};
+//! use iceberg_catalog_memory::MemoryCatalog;
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     // Build your file IO.
+//!     let file_io = FileIOBuilder::new("memory").build()?;
+//!     // Connect to a catalog.
+//!     let catalog = MemoryCatalog::new(file_io, None);
+//!     // Load table from catalog.
+//!     let table = catalog
+//!         .load_table(&TableIdent::from_strs(["hello", "world"])?)
+//!         .await?;
+//!     // Build table scan.
+//!     let stream = table
+//!         .scan()
+//!         .select(["name", "id"])
+//!         .build()?
+//!         .to_arrow()
+//!         .await?;
+//!
+//!     // Consume this stream like arrow record batch stream.
+//!     let _data: Vec<_> = stream.try_collect().await?;
+//!     Ok(())
+//! }
+//! ```
 
 #![deny(missing_docs)]