This is an automated email from the ASF dual-hosted git repository.
cloud-fan pushed a commit to branch branch-4.x
in repository https://gitbox.apache.org/repos/asf/spark.git
The following commit(s) were added to refs/heads/branch-4.x by this push:
new 820db6e8ad79 [SPARK-34254][SQL][DOC] Document CREATE EXTERNAL TABLE
for data source tables
820db6e8ad79 is described below
commit 820db6e8ad797f7ecc3ac57ef362b2f2ee0b0732
Author: deepinsight coder <[email protected]>
AuthorDate: Wed Aug 19 05:11:17 2026 +0800
[SPARK-34254][SQL][DOC] Document CREATE EXTERNAL TABLE for data source
tables
### What changes were proposed in this pull request?
Document `CREATE EXTERNAL TABLE` on the data source CREATE TABLE page.
- Syntax diagram now shows `CREATE [ EXTERNAL ] TABLE`
- New EXTERNAL parameter next to LOCATION: the table uses the given path,
DROP TABLE keeps the files, and `CREATE EXTERNAL TABLE` for a data source table
must include `LOCATION` or an equivalent path option. A table created with
`LOCATION` or a path option is also external without the `EXTERNAL` keyword.
- Parquet examples for `LOCATION` and `OPTIONS (PATH ...)`
`CREATE EXTERNAL TABLE ... USING ... LOCATION` has been legal since
SPARK-33651. The Hive CREATE TABLE page already documents EXTERNAL. This page
did not.
### Why are the changes needed?
The syntax has been supported since Spark 3.2.0, but
`docs/sql-ref-syntax-ddl-create-table-datasource.md` still starts with `CREATE
TABLE [ IF NOT EXISTS ]` and never shows an external example. Readers of this
page would think EXTERNAL is Hive-only.
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
Docs only. No unit tests for this markdown. I did not run `SKIP_API=1
bundle exec jekyll build` here because Bundler was not available. Please check
the rendered page for the syntax diagram, the EXTERNAL bullet next to LOCATION,
and that the examples use `USING parquet`, not Hive `STORED AS` clauses.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Cursor Grok 4.6
Made with [Cursor](https://cursor.com)
Closes #58037 from Vamsi-klu/spark-34254-external-docs.
Lead-authored-by: deepinsight coder <[email protected]>
Co-authored-by: Cursor Agent <[email protected]>
Signed-off-by: Wenchen Fan <[email protected]>
(cherry picked from commit c854ed8b5b2c2907c78545a04b68a61564719c2c)
Signed-off-by: Wenchen Fan <[email protected]>
---
docs/sql-ref-syntax-ddl-create-table-datasource.md | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/docs/sql-ref-syntax-ddl-create-table-datasource.md
b/docs/sql-ref-syntax-ddl-create-table-datasource.md
index f645732a15df..07bdbe4f4173 100644
--- a/docs/sql-ref-syntax-ddl-create-table-datasource.md
+++ b/docs/sql-ref-syntax-ddl-create-table-datasource.md
@@ -26,7 +26,7 @@ The `CREATE TABLE` statement defines a new table using a Data
Source.
### Syntax
```sql
-CREATE TABLE [ IF NOT EXISTS ] table_identifier
+CREATE [ EXTERNAL ] TABLE [ IF NOT EXISTS ] table_identifier
[ ( col_name1 col_type1 [ COMMENT col_comment1 ], ... ) ]
USING data_source
[ OPTIONS ( key1=val1, key2=val2, ... ) ]
@@ -78,6 +78,14 @@ as any order. For example, you can write COMMENT
table_comment after TBLPROPERTI
Specifies buckets numbers, which is used in `CLUSTERED BY` clause.
+* **EXTERNAL**
+
+ The table is defined using the path provided as `LOCATION` and does not
use the default location for this table.
+ Dropping an external table removes catalog metadata and leaves the data
files in place.
+ `CREATE EXTERNAL TABLE` for a data source table must include `LOCATION`.
+ A data source table created with `LOCATION` is also external even without
the
+ `EXTERNAL` keyword.
+
* **LOCATION**
Path to the directory where table data is stored, which could be a path on
distributed storage like HDFS, etc.
@@ -116,6 +124,11 @@ input query, to make sure the table gets created contains
exactly the same data
--Use data source
CREATE TABLE student (id INT, name STRING, age INT) USING CSV;
+-- External data source table. DROP TABLE keeps the files at the location.
+CREATE EXTERNAL TABLE student (id INT, name STRING, age INT)
+ USING parquet
+ LOCATION '/tmp/student';
+
--Use data from another table
CREATE TABLE student_copy USING CSV
AS SELECT * FROM student;
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
