From f394643af3ac18abce5f28d4d0736e08962b24e3 Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Wed, 22 Oct 2025 23:22:23 -0600 Subject: [PATCH 1/5] feat: Implement DESCRIBE SELECT Closes #18234. --- datafusion/sql/src/statement.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/datafusion/sql/src/statement.rs b/datafusion/sql/src/statement.rs index 0e868e8c2689..58d6d57b57a4 100644 --- a/datafusion/sql/src/statement.rs +++ b/datafusion/sql/src/statement.rs @@ -242,6 +242,16 @@ impl SqlToRel<'_, S> { table_name, .. } => self.describe_table_to_plan(table_name), + Statement::Explain { + describe_alias: DescribeAlias::Describe | DescribeAlias::Desc, // only parse 'DESCRIBE statement' or 'DESC statement' and not 'EXPLAIN statement' + statement, + .. + } => match *statement { + Statement::Query(query) => self.describe_query_to_plan(*query), + _ => Err(DataFusionError::NotImplemented(format!( + "Unsupported statement type for DESCRIBE: {statement:?}", + ))), + }, Statement::Explain { verbose, statement, @@ -1396,6 +1406,19 @@ impl SqlToRel<'_, S> { })) } + fn describe_query_to_plan(&self, query: Query) -> Result { + let plan = self.query_to_plan(query, &mut PlannerContext::new())?; + + let schema = Arc::new(plan.schema().as_arrow().clone()); + + let output_schema = DFSchema::try_from(LogicalPlan::describe_schema()).unwrap(); + + Ok(LogicalPlan::DescribeTable(DescribeTable { + schema, + output_schema: Arc::new(output_schema), + })) + } + fn copy_to_plan(&self, statement: CopyToStatement) -> Result { // Determine if source is table or query and handle accordingly let copy_source = statement.source; From 76a9dc61fb997f777a14da0d1ec1f7a8ad89271a Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Sat, 25 Oct 2025 11:27:49 -0600 Subject: [PATCH 2/5] test: Add slt tests for describing statements 1. simple describe select 1 2. a more complex query against table data 3. ensure that describing a non-query statement errors --- .../sqllogictest/test_files/describe.slt | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/datafusion/sqllogictest/test_files/describe.slt b/datafusion/sqllogictest/test_files/describe.slt index de5208b5483a..c86d7e2fd8d5 100644 --- a/datafusion/sqllogictest/test_files/describe.slt +++ b/datafusion/sqllogictest/test_files/describe.slt @@ -116,3 +116,29 @@ col1 Int32 YES # Test error cases statement error DESC nonexistent_table; + +########## +# Describe statement +########## + +# Test describing the schema of a simple statement +query TTT +DESCRIBE SELECT 1; +---- +Int64(1) Int64 NO + +# Insert some data into the existing test table... +statement ok +INSERT INTO test_desc_table (id, name) VALUES (1, 'Alice'), (2, 'Bob'), (3, 'Charlie'), (4, 'Alice'); + +# ... and describe the schema of a more complex query +query TTT +DESCRIBE SELECT name, COUNT(*) AS name_count FROM test_desc_table + GROUP BY name HAVING COUNT(*) > 1 ORDER BY name_count DESC; +---- +name Utf8View YES +name_count Int64 NO + +# Describing a statement that's not a query is not supported +statement error Unsupported statement type for DESCRIBE +DESCRIBE CREATE TABLE test_desc_table (id INT, name VARCHAR); From bb094879c28508495f3c382f16cc3cecd9129abd Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Sat, 25 Oct 2025 19:21:37 -0600 Subject: [PATCH 3/5] docs: Describe change in upgrade guide --- docs/source/library-user-guide/upgrading.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/source/library-user-guide/upgrading.md b/docs/source/library-user-guide/upgrading.md index 8b03193e7f99..3ba92b5259dd 100644 --- a/docs/source/library-user-guide/upgrading.md +++ b/docs/source/library-user-guide/upgrading.md @@ -116,6 +116,13 @@ Users may need to update their paths to account for these changes. See [issue #17713] for more details. +### `DESCRIBE query` support + +`DESCRIBE query` was previously an alias for `EXPLAIN query`, which outputs the +_execution plan_ of the query. With this release, `DESCRIBE query` now outputs +the computed _schema_ of the query, consistent with the behavior of `DESCRIBE +table_name`. + ## DataFusion `50.0.0` ### ListingTable automatically detects Hive Partitioned tables From e2715f6b63ce8d587538390d8866cb70bebcc38c Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Sat, 25 Oct 2025 19:26:59 -0600 Subject: [PATCH 4/5] style: Match prettier's expected formatting --- docs/source/library-user-guide/upgrading.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/source/library-user-guide/upgrading.md b/docs/source/library-user-guide/upgrading.md index 3ba92b5259dd..6b9cb0843c53 100644 --- a/docs/source/library-user-guide/upgrading.md +++ b/docs/source/library-user-guide/upgrading.md @@ -120,8 +120,7 @@ See [issue #17713] for more details. `DESCRIBE query` was previously an alias for `EXPLAIN query`, which outputs the _execution plan_ of the query. With this release, `DESCRIBE query` now outputs -the computed _schema_ of the query, consistent with the behavior of `DESCRIBE -table_name`. +the computed _schema_ of the query, consistent with the behavior of `DESCRIBE table_name`. ## DataFusion `50.0.0` From c95e5641c2b570f15de261375ef76bdd2e29ba25 Mon Sep 17 00:00:00 2001 From: Douglas Anderson Date: Sun, 26 Oct 2025 00:46:12 -0600 Subject: [PATCH 5/5] refactor: Use not_impl_err macro Also better follow the " not supported" not_impl_err message convention used in this file, and significantly improve readability of error by not debug printing the statement. --- datafusion/sql/src/statement.rs | 6 +++--- datafusion/sqllogictest/test_files/describe.slt | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/datafusion/sql/src/statement.rs b/datafusion/sql/src/statement.rs index 58d6d57b57a4..54b28b1f191e 100644 --- a/datafusion/sql/src/statement.rs +++ b/datafusion/sql/src/statement.rs @@ -248,9 +248,9 @@ impl SqlToRel<'_, S> { .. } => match *statement { Statement::Query(query) => self.describe_query_to_plan(*query), - _ => Err(DataFusionError::NotImplemented(format!( - "Unsupported statement type for DESCRIBE: {statement:?}", - ))), + _ => { + not_impl_err!("Describing statements other than SELECT not supported") + } }, Statement::Explain { verbose, diff --git a/datafusion/sqllogictest/test_files/describe.slt b/datafusion/sqllogictest/test_files/describe.slt index c86d7e2fd8d5..4c184c04d128 100644 --- a/datafusion/sqllogictest/test_files/describe.slt +++ b/datafusion/sqllogictest/test_files/describe.slt @@ -140,5 +140,5 @@ name Utf8View YES name_count Int64 NO # Describing a statement that's not a query is not supported -statement error Unsupported statement type for DESCRIBE +statement error Describing statements other than SELECT not supported DESCRIBE CREATE TABLE test_desc_table (id INT, name VARCHAR);