Commit 3a685b1
committed
[SPARK-56678][SQL] Use structured Catalog/Namespace/Table rows in DESCRIBE TABLE EXTENDED for v2 tables and views
### What changes were proposed in this pull request?
Standardize the `# Detailed Table Information` / `# Detailed View
Information` block in `DESCRIBE TABLE EXTENDED` output for v2 tables
and views to emit structured rows derived from the resolved
identifier:
- For tables (`DescribeTableExec`): the single `Name` row that came
from `Table.name()` is replaced by `Catalog`, `Namespace`,
`Database`, and `Table`.
- For views (`DescribeV2ViewExec`): the `Catalog` + `Identifier`
pair (where `Identifier` was a single string concatenating
namespace and name with `.`) is replaced by `Catalog`,
`Namespace`, `Database`, and `View`.
The catalog name and resolved `Identifier` are threaded from
`ResolvedTable` / `ResolvedPersistentView` through the v2 execs.
`DescribeTablePartitionExec` is updated to pass the catalog name to
the inner `DescribeTableExec` it constructs for the schema/partition
header.
The `Namespace` row uses `Identifier.namespace().quoted` —
dot-separated, with back-tick quoting only on segments that need it
— matching the existing Spark convention for multi-segment
namespaces. This keeps the row round-trip-safe for namespaces with
dots in segments while staying readable for the common single-level
case.
#### `Database` row for v1 compatibility
v1 `DescribeTableCommand` (via `CatalogTable.toJsonLinkedHashMap`)
emits `Catalog` / `Database` / `Table` rows, where `Database` is
the single-string `database` field of `TableIdentifier`. To keep
DESCRIBE consumers that read the `Database` row working uniformly
across v1 (HMS) and v2, this PR also emits a `Database` row in the
v2 output. The row is **always present**:
- For a single-segment namespace, `Database` is that single
segment (matches v1 exactly).
- For a multi-segment namespace, `Database` is the trailing
segment — multi-segment namespaces still surface their leaf
segment under the v1-compat row, while consumers that need the
full namespace read `Namespace`.
- For a root-level entity (empty namespace), `Database` is the
empty string. The row is still emitted so the layout is uniform
across all v2 namespaces.
`Database` alone is not round-trip-safe for multi-segment cases;
`Namespace` is the canonical v2 representation.
### Why are the changes needed?
In a multi-catalog deployment, the catalog name is a first-class
part of a v2 table or view identifier. The previous output buried
it inside connector-controlled strings:
- `Table.name()` for tables is connector-defined; some connectors
return `catalog.namespace.name`, others just `namespace.name`,
others use a custom format. The result is that `DESCRIBE TABLE`
output looks different across catalogs even for the same logical
table shape.
- `Identifier` for v2 views collapsed namespace and name into a
single dotted string, so consumers had to parse the dot back out
and could not unambiguously round-trip multi-level namespaces
with dots in segments.
Splitting the components into `Catalog`, `Namespace`,
`Database`, and `Table` / `View` rows:
- gives `DESCRIBE TABLE EXTENDED` a uniform shape across v2
connectors,
- makes the catalog name explicit and surfaceable when multiple v2
catalogs are configured,
- handles multi-level namespaces naturally via
`Identifier.namespace().quoted`,
- aligns the table and view sections so consumers can read the same
rows from either, switching only on the section header
(`# Detailed Table Information` vs `# Detailed View Information`),
- with the always-emitted `Database` compatibility row, lets
consumers built for v1 (HMS) keep working without changes,
- is parseable programmatically without splitting strings.
### Does this PR introduce any user-facing change?
Yes, slight output change in `DESCRIBE TABLE EXTENDED` for v2 tables
and v2 views.
For v2 tables, single-segment namespace (most common):
- Before: `Name | testcat.ns.t | `
- After: `Catalog | testcat | `, `Namespace | ns | `,
`Database | ns | `, `Table | t | `.
For v2 tables, multi-segment namespace:
- Before: `Name | testcat.ns1.ns2.t | `
- After: `Catalog | testcat | `, `Namespace | ns1.ns2 | `,
`Database | ns2 | `, `Table | t | `.
For v2 views, single-segment namespace:
- Before: `Catalog | testcat | `, `Identifier | ns.v | `
- After: `Catalog | testcat | `, `Namespace | ns | `,
`Database | ns | `, `View | v | `.
For v2 views, multi-segment namespace:
- Before: `Catalog | testcat | `, `Identifier | ns1.ns2.v | `
- After: `Catalog | testcat | `, `Namespace | ns1.ns2 | `,
`Database | ns2 | `, `View | v | `.
v1 paths (session-catalog tables and views via HMS) are unchanged.
Tools that read DESCRIBE output should switch from concatenating
`Name` / `Identifier` to reading the structured rows.
### How was this patch tested?
- Updated the affected golden assertion in `DescribeTableSuite`
(`DESCRIBE TABLE EXTENDED of a partitioned table`) to match the
new row layout including the `Database` compatibility row.
- Added focused tests in v2 `DescribeTableSuite` pinning the
structured rows on a freshly created v2 table for both
single-segment (`ns`) and multi-segment (`ns1.ns2`) namespaces —
the multi-segment test pins that `Database` carries the trailing
segment while `Namespace` carries the full dot-joined form.
- Added parallel tests in v2 `DescribeViewSuite` pinning the same
layout for v2 views (single-segment and multi-segment).
- Removed the now-redundant `DESCRIBE TABLE EXTENDED on a non-view
MetadataTable shows the real identifier` test in
`DataSourceV2MetadataTableSuite` (the structured-row layout is
what's pinned by the new tests in `v2.DescribeTableSuite`; the
identifier-passthrough behavior is no longer tied to
`MetadataTable.name()`).
Ran:
build/sbt 'sql/testOnly \
org.apache.spark.sql.execution.command.v2.DescribeTableSuite \
org.apache.spark.sql.execution.command.v2.DescribeViewSuite \
org.apache.spark.sql.connector.DataSourceV2MetadataTableSuite \
org.apache.spark.sql.connector.DataSourceV2MetadataViewSuite'
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude Opus 4.7
Closes #55625 from cloud-fan/describe-table-view-structured-rows.
Authored-by: Wenchen Fan <wenchen@databricks.com>
Signed-off-by: Wenchen Fan <wenchen@databricks.com>1 parent 520835a commit 3a685b1
9 files changed
Lines changed: 239 additions & 119 deletions
File tree
- sql
- catalyst/src/main/java/org/apache/spark/sql/connector/catalog
- core/src
- main/scala/org/apache/spark/sql/execution/datasources/v2
- test/scala/org/apache/spark/sql
- connector
- execution/command/v2
Lines changed: 6 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
50 | 50 | | |
51 | 51 | | |
52 | 52 | | |
53 | | - | |
54 | | - | |
55 | | - | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
56 | 59 | | |
57 | 60 | | |
58 | 61 | | |
| |||
Lines changed: 1 addition & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
547 | 547 | | |
548 | 548 | | |
549 | 549 | | |
550 | | - | |
| 550 | + | |
551 | 551 | | |
552 | 552 | | |
553 | 553 | | |
| |||
Lines changed: 139 additions & 82 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
24 | 24 | | |
25 | 25 | | |
26 | 26 | | |
27 | | - | |
| 27 | + | |
| 28 | + | |
28 | 29 | | |
29 | 30 | | |
30 | 31 | | |
31 | 32 | | |
32 | 33 | | |
33 | 34 | | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
| 155 | + | |
| 156 | + | |
| 157 | + | |
| 158 | + | |
| 159 | + | |
| 160 | + | |
| 161 | + | |
| 162 | + | |
| 163 | + | |
| 164 | + | |
| 165 | + | |
| 166 | + | |
| 167 | + | |
34 | 168 | | |
35 | 169 | | |
| 170 | + | |
| 171 | + | |
36 | 172 | | |
37 | | - | |
| 173 | + | |
38 | 174 | | |
39 | 175 | | |
40 | 176 | | |
| |||
48 | 184 | | |
49 | 185 | | |
50 | 186 | | |
51 | | - | |
52 | | - | |
53 | | - | |
54 | | - | |
55 | | - | |
56 | | - | |
57 | | - | |
58 | 187 | | |
59 | 188 | | |
60 | 189 | | |
61 | | - | |
| 190 | + | |
62 | 191 | | |
63 | 192 | | |
64 | 193 | | |
| |||
87 | 216 | | |
88 | 217 | | |
89 | 218 | | |
90 | | - | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | 219 | | |
98 | 220 | | |
99 | 221 | | |
| |||
117 | 239 | | |
118 | 240 | | |
119 | 241 | | |
120 | | - | |
121 | | - | |
122 | | - | |
123 | | - | |
124 | | - | |
125 | | - | |
126 | | - | |
127 | | - | |
128 | | - | |
129 | | - | |
130 | | - | |
131 | | - | |
132 | | - | |
133 | | - | |
134 | | - | |
135 | | - | |
136 | | - | |
137 | | - | |
138 | | - | |
139 | | - | |
140 | | - | |
141 | | - | |
142 | | - | |
143 | | - | |
144 | | - | |
145 | | - | |
146 | | - | |
147 | 242 | | |
148 | 243 | | |
149 | 244 | | |
| |||
160 | 255 | | |
161 | 256 | | |
162 | 257 | | |
163 | | - | |
164 | | - | |
165 | | - | |
166 | | - | |
167 | | - | |
168 | | - | |
169 | | - | |
170 | | - | |
171 | | - | |
172 | | - | |
173 | | - | |
174 | | - | |
175 | | - | |
176 | | - | |
177 | | - | |
178 | | - | |
179 | | - | |
180 | | - | |
181 | | - | |
182 | | - | |
183 | | - | |
184 | | - | |
185 | | - | |
186 | | - | |
187 | | - | |
188 | | - | |
189 | | - | |
190 | | - | |
191 | | - | |
192 | | - | |
193 | | - | |
194 | | - | |
195 | | - | |
196 | | - | |
197 | | - | |
198 | | - | |
199 | | - | |
200 | | - | |
201 | 258 | | |
Lines changed: 5 additions & 3 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
35 | | - | |
| 35 | + | |
36 | 36 | | |
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
40 | | - | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
41 | 43 | | |
42 | | - | |
| 44 | + | |
43 | 45 | | |
44 | 46 | | |
45 | 47 | | |
| |||
Lines changed: 8 additions & 9 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
146 | 146 | | |
147 | 147 | | |
148 | 148 | | |
149 | | - | |
150 | | - | |
151 | | - | |
152 | | - | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| 154 | + | |
153 | 155 | | |
154 | 156 | | |
155 | 157 | | |
156 | 158 | | |
157 | 159 | | |
158 | 160 | | |
159 | | - | |
| 161 | + | |
160 | 162 | | |
161 | 163 | | |
162 | 164 | | |
| |||
166 | 168 | | |
167 | 169 | | |
168 | 170 | | |
169 | | - | |
170 | | - | |
171 | | - | |
172 | | - | |
| 171 | + | |
173 | 172 | | |
174 | 173 | | |
175 | 174 | | |
| |||
Lines changed: 0 additions & 18 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
83 | 83 | | |
84 | 84 | | |
85 | 85 | | |
86 | | - | |
87 | | - | |
88 | | - | |
89 | | - | |
90 | | - | |
91 | | - | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
101 | | - | |
102 | | - | |
103 | | - | |
104 | 86 | | |
105 | 87 | | |
106 | 88 | | |
| |||
Lines changed: 2 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
3912 | 3912 | | |
3913 | 3913 | | |
3914 | 3914 | | |
3915 | | - | |
3916 | | - | |
| 3915 | + | |
| 3916 | + | |
3917 | 3917 | | |
3918 | 3918 | | |
3919 | 3919 | | |
| |||
0 commit comments