Skip to content

Commit f36676b

Browse files
committed
Docs: Add DDL docs for Views
1 parent f0b3733 commit f36676b

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed

docs/docs/spark-ddl.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -566,3 +566,119 @@ Tags can be removed via the `DROP TAG` sql
566566
```sql
567567
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
568568
```
569+
570+
### Iceberg views in Spark
571+
572+
Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
573+
This section covers how to create and manage views in Spark using Spark 3.4 and above (earlier versions of Spark are not supported).
574+
575+
!!! note
576+
577+
All the SQL examples in this section follow the official Spark SQL syntax:
578+
579+
* [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
580+
* [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
581+
* [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
582+
* [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
583+
* [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
584+
* [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
585+
586+
587+
#### Creating a view
588+
589+
Create a simple view without any comments or properties:
590+
```sql
591+
CREATE VIEW <viewName> AS SELECT * FROM <tableName>
592+
```
593+
594+
Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
595+
```sql
596+
CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * FROM <tableName>
597+
```
598+
599+
Create a view with a comment, including aliased and commented columns that are different from the source table:
600+
```sql
601+
CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
602+
COMMENT 'View Comment'
603+
AS SELECT id, zip FROM <tableName>
604+
```
605+
606+
#### Creating a view with properties
607+
608+
Create a view with properties using `TBLPROPERTIES`:
609+
```sql
610+
CREATE VIEW <viewName>
611+
TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
612+
AS SELECT * FROM <tableName>
613+
```
614+
615+
Display view properties:
616+
```sql
617+
SHOW TBLPROPERTIES <viewName>
618+
```
619+
620+
#### Dropping a view
621+
622+
Drop an existing view:
623+
```sql
624+
DROP VIEW <viewName>
625+
```
626+
627+
Using `IF EXISTS` prevents the SQL statement from failing if the view does not exist:
628+
```sql
629+
DROP VIEW IF EXISTS <viewName>
630+
```
631+
632+
#### Replacing a view
633+
634+
Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
635+
```sql
636+
CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
637+
TBLPROPERTIES ('key1' = 'new_val1')
638+
AS SELECT id FROM <tableName>
639+
```
640+
641+
#### Setting and removing view properties
642+
643+
Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
644+
```sql
645+
ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
646+
```
647+
648+
Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
649+
```sql
650+
ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
651+
```
652+
653+
#### Showing available views
654+
655+
List all views in the currently set namespace (via `USE <namespace>`):
656+
```sql
657+
SHOW VIEWS
658+
```
659+
660+
List all available views in the defined catalog and/or namespace using one of the below variations:
661+
```sql
662+
SHOW VIEWS IN <catalog>
663+
```
664+
```sql
665+
SHOW VIEWS IN <namespace>
666+
```
667+
```sql
668+
SHOW VIEWS IN <catalog>.<namespace>
669+
```
670+
671+
#### Showing the CREATE statement of a view
672+
673+
Show the CREATE statement of a view:
674+
```sql
675+
SHOW CREATE TABLE <viewName>
676+
```
677+
678+
#### Displaying view details
679+
680+
Display additional view details using `DESCRIBE`:
681+
682+
```sql
683+
DESCRIBE [EXTENDED] <viewName>
684+
```

0 commit comments

Comments
 (0)