Add new user doc to translate logical plan to physical plan

docs/Cargo.toml

@@ -33,3 +33,4 @@ workspace = true
 
 [dependencies]
 datafusion = { workspace = true }
+tokio = { workspace = true }

docs/source/library-user-guide/building-logical-plans.md

@@ -131,6 +131,38 @@ Filter: person.id > Int32(500) [id:Int32;N, name:Utf8;N]
   TableScan: person [id:Int32;N, name:Utf8;N]
 ```
 
+## Translating Logical Plan to Physical Plan
+
+<!-- source for this example is in datafusion_docs::library_logical_plan::translate_logical_to_physical -->
+
+```rust
+// create a default table source
+let schema = Schema::new(vec![
+    Field::new("id", DataType::Int32, true),
+    Field::new("name", DataType::Utf8, true),
+]);
+let table_provider = Arc::new(MemTable::try_new(Arc::new(schema), vec![])?);
+let table_source = Arc::new(DefaultTableSource::new(table_provider));
+
+// create a LogicalPlanBuilder for a table scan without projection or filters
+let logical_plan = LogicalPlanBuilder::scan("person", table_source, None)?.build()?;
+
+// create a physical plan using the default physical planner
+let ctx = SessionContext::new();
+let planner = DefaultPhysicalPlanner::default();
+let physical_plan = planner.create_physical_plan(&logical_plan, &ctx.state()).await?;
+
+// print the plan
+println!("{}", DisplayableExecutionPlan::new(physical_plan.as_ref()).indent(true));
+```
+
+This example produces the following physical plan:
+
+```
+MemoryExec: partitions=0, partition_sizes=[]
+```
+
+
 ## Table Sources
 
 The previous example used a [LogicalTableSource], which is used for tests and documentation in DataFusion, and is also

docs/src/library_logical_plan.rs

@@ -16,9 +16,12 @@
 // under the License.
 
 use datafusion::arrow::datatypes::{DataType, Field, Schema, SchemaRef};
+use datafusion::datasource::{DefaultTableSource, MemTable};
 use datafusion::error::Result;
 use datafusion::logical_expr::builder::LogicalTableSource;
 use datafusion::logical_expr::{Filter, LogicalPlan, LogicalPlanBuilder, TableScan};
+use datafusion::physical_plan::display::DisplayableExecutionPlan;
+use datafusion::physical_planner::{DefaultPhysicalPlanner, PhysicalPlanner};
 use datafusion::prelude::*;
 use std::sync::Arc;
 
@@ -76,3 +79,32 @@ fn plan_builder_1() -> Result<()> {
 
     Ok(())
 }
+
+#[tokio::test]
+async fn translate_logical_to_physical() -> Result<()> {
+    // create a default table source
+    let schema = Schema::new(vec![
+        Field::new("id", DataType::Int32, true),
+        Field::new("name", DataType::Utf8, true),
+    ]);
+    let table_provider = Arc::new(MemTable::try_new(Arc::new(schema), vec![])?);
+    let table_source = Arc::new(DefaultTableSource::new(table_provider));
+
+    // create a LogicalPlanBuilder for a table scan without projection or filters
+    let logical_plan = LogicalPlanBuilder::scan("person", table_source, None)?.build()?;
+
+    // create a physical plan using the default physical planner
+    let ctx = SessionContext::new();
+    let planner = DefaultPhysicalPlanner::default();
+    let physical_plan = planner
+        .create_physical_plan(&logical_plan, &ctx.state())
+        .await?;
+
+    // print the plan
+    println!(
+        "{}",
+        DisplayableExecutionPlan::new(physical_plan.as_ref()).indent(true)
+    );
+
+    Ok(())
+}