Address PR review feedback

- Change catalog name from "iceberg" to "my_catalog" to clarify it has no special meaning
- Move external table code to separate example file
- Remove sections not suited for end-users: External Tables, Table Provider Types, Creating Partitioned Tables (Rust API), Query Optimization
- Add clarification that table properties must be set via Iceberg catalog API

Author: xbattlax

crates/examples/Cargo.toml

@@ -50,6 +50,10 @@ required-features = ["storage-oss"]
 name = "datafusion-integration"
 path = "src/datafusion_integration.rs"
 
+[[example]]
+name = "datafusion-external-table"
+path = "src/datafusion_external_table.rs"
+
 [features]
 default = []
 storage-oss = ["iceberg/storage-oss"]

crates/examples/src/datafusion_external_table.rs

@@ -0,0 +1,80 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Example demonstrating external Iceberg table access via DataFusion.
+//!
+//! This example shows how to use `IcebergTableProviderFactory` to read
+//! existing Iceberg tables via `CREATE EXTERNAL TABLE` syntax.
+//!
+//! Note: External tables are read-only. For write operations, use
+//! `IcebergCatalogProvider` instead (see `datafusion_integration.rs`).
+
+use std::sync::Arc;
+
+use datafusion::execution::context::SessionContext;
+use datafusion::execution::session_state::SessionStateBuilder;
+use iceberg_datafusion::IcebergTableProviderFactory;
+
+// ANCHOR: external_table_setup
+/// Set up a DataFusion session with IcebergTableProviderFactory registered.
+///
+/// This allows reading existing Iceberg tables via `CREATE EXTERNAL TABLE` syntax.
+fn setup_external_table_support() -> SessionContext {
+    // Create a session state with the Iceberg table factory registered
+    let mut state = SessionStateBuilder::new().with_default_features().build();
+
+    // Register the IcebergTableProviderFactory to handle "ICEBERG" file type
+    state.table_factories_mut().insert(
+        "ICEBERG".to_string(),
+        Arc::new(IcebergTableProviderFactory::new()),
+    );
+
+    SessionContext::new_with_state(state)
+}
+// ANCHOR_END: external_table_setup
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let ctx = setup_external_table_support();
+
+    // ANCHOR: external_table_query
+    // Example SQL for creating and querying an external Iceberg table:
+    //
+    // CREATE EXTERNAL TABLE my_table
+    // STORED AS ICEBERG
+    // LOCATION '/path/to/iceberg/metadata/v1.metadata.json';
+    //
+    // SELECT * FROM my_table WHERE column > 100;
+    // ANCHOR_END: external_table_query
+
+    println!("External table support configured.");
+    println!("Use CREATE EXTERNAL TABLE ... STORED AS ICEBERG to read existing tables.");
+    println!();
+    println!("Example:");
+    println!("  CREATE EXTERNAL TABLE my_table");
+    println!("  STORED AS ICEBERG");
+    println!("  LOCATION '/path/to/iceberg/metadata/v1.metadata.json';");
+
+    // This example requires an actual Iceberg table to query.
+    // For a complete working example with table creation, see datafusion_integration.rs
+
+    // Verify the session is configured correctly
+    let tables = ctx.catalog_names();
+    println!("\nRegistered catalogs: {tables:?}");
+
+    Ok(())
+}

crates/examples/src/datafusion_integration.rs

@@ -27,10 +27,9 @@ use std::collections::HashMap;
 use std::sync::Arc;
 
 use datafusion::execution::context::SessionContext;
-use datafusion::execution::session_state::SessionStateBuilder;
 use iceberg::memory::{MEMORY_CATALOG_WAREHOUSE, MemoryCatalogBuilder};
 use iceberg::{Catalog, CatalogBuilder, NamespaceIdent};
-use iceberg_datafusion::{IcebergCatalogProvider, IcebergTableProviderFactory};
+use iceberg_datafusion::IcebergCatalogProvider;
 use tempfile::TempDir;
 
 #[tokio::main]
@@ -59,13 +58,13 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         Arc::new(IcebergCatalogProvider::try_new(Arc::new(iceberg_catalog)).await?);
 
     let ctx = SessionContext::new();
-    ctx.register_catalog("iceberg", catalog_provider);
+    ctx.register_catalog("my_catalog", catalog_provider);
     // ANCHOR_END: catalog_setup
 
     // ANCHOR: create_table
     // Create a table using SQL
     ctx.sql(
-        "CREATE TABLE iceberg.demo.users (
+        "CREATE TABLE my_catalog.demo.users (
             id INT NOT NULL,
             name STRING NOT NULL,
             email STRING
@@ -80,7 +79,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Insert data into the table
     let result = ctx
         .sql(
-            "INSERT INTO iceberg.demo.users VALUES
+            "INSERT INTO my_catalog.demo.users VALUES
             (1, 'Alice', 'alice@example.com'),
             (2, 'Bob', 'bob@example.com'),
             (3, 'Charlie', NULL)",
@@ -97,15 +96,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Query the data with filtering
     println!("\nQuerying users with email:");
     let df = ctx
-        .sql("SELECT id, name, email FROM iceberg.demo.users WHERE email IS NOT NULL")
+        .sql("SELECT id, name, email FROM my_catalog.demo.users WHERE email IS NOT NULL")
         .await?;
 
     df.show().await?;
 
     // Query with projection (only specific columns)
     println!("\nQuerying only names:");
     let df = ctx
-        .sql("SELECT name FROM iceberg.demo.users ORDER BY id")
+        .sql("SELECT name FROM my_catalog.demo.users ORDER BY id")
         .await?;
 
     df.show().await?;
@@ -115,15 +114,15 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Query the snapshots metadata table
     println!("\nTable snapshots:");
     let df = ctx
-        .sql("SELECT snapshot_id, operation FROM iceberg.demo.users$snapshots")
+        .sql("SELECT snapshot_id, operation FROM my_catalog.demo.users$snapshots")
         .await?;
 
     df.show().await?;
 
     // Query the manifests metadata table
     println!("\nTable manifests:");
     let df = ctx
-        .sql("SELECT path, added_data_files_count FROM iceberg.demo.users$manifests")
+        .sql("SELECT path, added_data_files_count FROM my_catalog.demo.users$manifests")
         .await?;
 
     df.show().await?;
@@ -133,38 +132,3 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     Ok(())
 }
-
-// ANCHOR: external_table_setup
-/// Example of setting up IcebergTableProviderFactory for external tables.
-///
-/// This allows reading existing Iceberg tables via `CREATE EXTERNAL TABLE` syntax.
-#[allow(dead_code)]
-async fn setup_external_table_support() -> SessionContext {
-    // Create a session state with the Iceberg table factory registered
-    let mut state = SessionStateBuilder::new().with_default_features().build();
-
-    // Register the IcebergTableProviderFactory to handle "ICEBERG" file type
-    state.table_factories_mut().insert(
-        "ICEBERG".to_string(),
-        Arc::new(IcebergTableProviderFactory::new()),
-    );
-
-    SessionContext::new_with_state(state)
-}
-// ANCHOR_END: external_table_setup
-
-// ANCHOR: external_table_query
-/// Example SQL for creating and querying an external Iceberg table.
-///
-/// ```sql
-/// -- Create an external table from an existing Iceberg metadata file
-/// CREATE EXTERNAL TABLE my_table
-/// STORED AS ICEBERG
-/// LOCATION '/path/to/iceberg/metadata/v1.metadata.json';
-///
-/// -- Query the external table
-/// SELECT * FROM my_table WHERE column > 100;
-/// ```
-#[allow(dead_code)]
-fn external_table_sql_example() {}
-// ANCHOR_END: external_table_query

website/src/datafusion.md

@@ -24,7 +24,6 @@ The `iceberg-datafusion` crate provides integration between Apache Iceberg and [
 ## Features
 
 - **SQL DDL/DML**: `CREATE TABLE`, `INSERT INTO`, `SELECT`
-- **Query Optimization**: Projection, filter, and LIMIT pushdown
 - **Metadata Tables**: Query snapshots and manifests
 - **Partitioned Tables**: Automatic partition routing for writes
 
@@ -100,63 +99,8 @@ Available metadata tables:
 - `table$snapshots` - Table snapshot history
 - `table$manifests` - Manifest file information
 
-## File-Based Access (External Tables)
-
-For reading existing Iceberg tables without a catalog, use `IcebergTableProviderFactory`:
-
-```rust,no_run,noplayground
-{{#rustdoc_include ../../crates/examples/src/datafusion_integration.rs:external_table_setup}}
-```
-
-Then create external tables via SQL:
-
-```sql
-CREATE EXTERNAL TABLE my_table
-STORED AS ICEBERG
-LOCATION '/path/to/iceberg/metadata/v1.metadata.json';
-
-SELECT * FROM my_table;
-```
-
-> **Note**: External tables are read-only. For write operations, use `IcebergCatalogProvider`.
-
-## Table Provider Types
-
-### IcebergTableProvider
-
-- Backed by an Iceberg catalog
-- Automatically refreshes metadata on each operation
-- Supports both read and write operations
-- Use when you need the latest table state or write capability
-
-### IcebergStaticTableProvider
-
-- Fixed table snapshot at construction time
-- No catalog round-trips (better performance)
-- Read-only
-- Use for time-travel queries or when consistency within a query is important
-
 ## Partitioned Tables
 
-### Creating Partitioned Tables
-
-Partitioned tables must be created using the Iceberg catalog API (not SQL):
-
-```rust,no_run
-use iceberg::spec::{Transform, UnboundPartitionSpec};
-
-let partition_spec = UnboundPartitionSpec::builder()
-    .with_spec_id(0)
-    .add_partition_field(column_id, "partition_column", Transform::Identity)?
-    .build();
-```
-
-Supported partition transforms:
-- `Identity` - Partition by exact value
-- `Year`, `Month`, `Day`, `Hour` - Time-based partitioning
-- `Bucket(n)` - Hash partitioning into n buckets
-- `Truncate(width)` - String/number truncation
-
 ### Writing to Partitioned Tables
 
 When inserting into a partitioned table, data is automatically routed to the correct partition directories:
@@ -184,18 +128,10 @@ Configure via table property:
 write.datafusion.fanout.enabled = true
 ```
 
-## Query Optimization
-
-The DataFusion integration supports several query optimizations:
-
-- **Projection Pushdown**: Only reads columns referenced in the query
-- **Filter Pushdown**: Prunes data files using manifest statistics
-- **LIMIT Pushdown**: Reduces the amount of data scanned
-
-These optimizations are applied automatically by the query planner.
-
 ## Configuration Options
 
+These table properties control write behavior. They must be set when creating the table via the Iceberg catalog API, as DataFusion SQL does not support `ALTER TABLE` for property changes.
+
 | Property | Default | Description |
 |----------|---------|-------------|
 | `write.datafusion.fanout.enabled` | `true` | Use FanoutWriter (true) or ClusteredWriter (false) for partitioned writes |