Support DuckDB DESCRIBE <query>

DESCRIBE now accepts a query as well as a table, so DESCRIBE SELECT ...,
DESCRIBE FROM ... and DESCRIBE WITH ... parse. The described query is
reachable from TablesNamesFinder and rendered by the deparser.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EqinwHBKuAtPEmtXr3b5P2

Author: hayssams

src/main/java/net/sf/jsqlparser/statement/DescribeStatement.java

@@ -10,10 +10,12 @@
 package net.sf.jsqlparser.statement;
 
 import net.sf.jsqlparser.schema.Table;
+import net.sf.jsqlparser.statement.select.Select;
 
 public class DescribeStatement implements Statement {
 
     private Table table;
+    private Select select;
     private String describeType;
 
     public DescribeStatement() {
@@ -32,9 +34,24 @@ public void setTable(Table table) {
         this.table = table;
     }
 
+    /** DuckDB also describes a query: {@code DESCRIBE SELECT ...}. */
+    public Select getSelect() {
+        return select;
+    }
+
+    public void setSelect(Select select) {
+        this.select = select;
+    }
+
+    public DescribeStatement withSelect(Select select) {
+        setSelect(select);
+        return this;
+    }
+
     @Override
     public String toString() {
-        return this.describeType + " " + table.getFullyQualifiedName();
+        return this.describeType + " "
+                + (select != null ? select.toString() : table.getFullyQualifiedName());
     }
 
     @Override

src/main/java/net/sf/jsqlparser/util/TablesNamesFinder.java

@@ -2044,7 +2044,11 @@ public void visit(Values values) {
 
     @Override
     public <S> Void visit(DescribeStatement describe, S context) {
-        describe.getTable().accept(this, context);
+        if (describe.getSelect() != null) {
+            describe.getSelect().accept((SelectVisitor<?>) this, context);
+        } else {
+            describe.getTable().accept(this, context);
+        }
         return null;
     }
 

src/main/java/net/sf/jsqlparser/util/deparser/StatementDeParser.java

@@ -444,7 +444,11 @@ public <S> StringBuilder visit(Comment comment, S context) {
     public <S> StringBuilder visit(DescribeStatement describe, S context) {
         builder.append(describe.getDescribeType());
         builder.append(" ");
-        builder.append(describe.getTable());
+        if (describe.getSelect() != null) {
+            describe.getSelect().accept(this, context);
+        } else {
+            builder.append(describe.getTable());
+        }
         return builder;
     }
 

src/main/jjtree/net/sf/jsqlparser/parser/JSqlParserCC.jjt

@@ -4373,11 +4373,19 @@ PurgeStatement PurgeStatement(): {
 
 DescribeStatement Describe(): {
     Table table;
+    Select select;
     DescribeStatement stmt = new DescribeStatement();
     Token tk = null;
 } {
     (tk=<K_DESCRIBE> | tk=<K_DESC>)
-    table = Table() { stmt.setDescribeType(tk.image).setTable(table); }
+    (
+        // DuckDB describes the result of a query, not only a table
+        LOOKAHEAD({ getToken(1).kind == K_SELECT || getToken(1).kind == K_WITH
+                || getToken(1).kind == K_FROM || getToken(1).kind == OPENING_BRACKET })
+        select = Select() { stmt.setDescribeType(tk.image).setSelect(select); }
+        |
+        table = Table() { stmt.setDescribeType(tk.image).setTable(table); }
+    )
     {
         return stmt;
     }

src/test/java/net/sf/jsqlparser/statement/select/DuckDBTest.java

@@ -13,6 +13,7 @@
 import net.sf.jsqlparser.schema.Table;
 import net.sf.jsqlparser.statement.create.table.CreateTable;
 import net.sf.jsqlparser.statement.insert.Insert;
+import net.sf.jsqlparser.statement.DescribeStatement;
 import net.sf.jsqlparser.test.TestUtils;
 import org.junit.jupiter.api.Assertions;
 import org.junit.jupiter.api.Test;
@@ -176,4 +177,32 @@ void testUsingSampleReservoir() throws JSQLParserException {
         Assertions.assertEquals(SampleClause.SampleMethod.RESERVOIR,
                 select.getFromItem().getSampleClause().getMethod());
     }
+
+    @Test
+    void testDescribeQuery() throws JSQLParserException {
+        String sqlStr = "DESCRIBE SELECT * FROM t";
+        DescribeStatement describe =
+                (DescribeStatement) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertNotNull(describe.getSelect());
+        Assertions.assertNull(describe.getTable());
+    }
+
+    @Test
+    void testDescribeQueryTablesNamesFinder() throws JSQLParserException {
+        String sqlStr = "DESCRIBE SELECT * FROM ds.t";
+
+        Assertions.assertEquals(java.util.Collections.singletonList("ds.t"),
+                new net.sf.jsqlparser.util.TablesNamesFinder<Void>()
+                        .getTableList(net.sf.jsqlparser.parser.CCJSqlParserUtil.parse(sqlStr)));
+    }
+
+    @Test
+    void testDescribeTableStillParses() throws JSQLParserException {
+        String sqlStr = "DESCRIBE t";
+        DescribeStatement describe =
+                (DescribeStatement) TestUtils.assertSqlCanBeParsedAndDeparsed(sqlStr, true);
+
+        Assertions.assertEquals("t", describe.getTable().getName());
+    }
 }