bitsondatadev commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1514954244
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
Review Comment:
Space between header and content is best practice, and ideally avoid
stacking headers.
"View" isn't capitalized unless starting a sentence or following an all-caps
SQL convention.
```suggestion
### Iceberg views in Spark
Iceberg views are a [common representation](../../view-spec.md) of a SQL
view that aims to be interpreted across multiple query engines. This section
covers how to create and manage views in Spark.
#### Creating a basic view
Create a simple view with no extra properties:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
Review Comment:
```suggestion
Create a view with commented columns that use an alias that is different
from the source table and adds a view comment:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
Review Comment:
```suggestion
Using `IF NOT EXISTS` prevents the SQL statement from failing in case the
view already exists:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
Review Comment:
FYI, why I'm making all these changes:
https://learn.microsoft.com/en-us/style-guide/grammar/verbs#active-and-passive-voice.
I still have yet to get to my style linter changes. That will make these
changes less frequent.
```suggestion
Set the properties of an existing view using `ALTER VIEW ... SET`:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
Review Comment:
I'd go with making `zip` vary a bit more in the view column to make the
example clearer.
```suggestion
CREATE VIEW <viewName> (id COMMENT 'Unique id of person (customer or
employee)', zip_code COMMENT 'Zip Code for people')
COMMENT 'Upstream consumer must see Zip Code fields as zip_code'
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
Review Comment:
```suggestion
Update a view's schema, its properties, or the underlying SQL statement by
adding `OR REPLACE` before the view:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
Review Comment:
```suggestion
Display these properties using `SHOW TBLPROPERTIES`:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Properties can be removed using:
Review Comment:
```suggestion
Remove properties of an existing view in a similar way using `ALTER VIEW ...
UNSET`:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
Review Comment:
```suggestion
#### Setting and removing view properties
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Properties can be removed using:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1')
+```
+
+#### Showing available Views
+
+The below SQL will list all views in the currently set namespace:
+```sql
+SHOW VIEWS
+```
+
+The below SQL will list all available views in the defined catalog/namespace
Review Comment:
```suggestion
List all available views in the defined catalog and namespace pair using
`SHOW VIEWS`:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Properties can be removed using:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1')
+```
+
+#### Showing available Views
+
+The below SQL will list all views in the currently set namespace:
Review Comment:
```suggestion
Set a namespace using the SQL `USE` statement:
```sql
USE <catalog>.<namespace>
```<!--delete me - just to avoid the github suggestions from closing-->
List all views in the currently set namespace:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
Review Comment:
```suggestion
Create a view with properties by using `TBLPROPERTIES`:
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Properties can be removed using:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1')
+```
+
+#### Showing available Views
+
+The below SQL will list all views in the currently set namespace:
+```sql
+SHOW VIEWS
+```
+
+The below SQL will list all available views in the defined catalog/namespace
+```sql
+SHOW VIEWS IN <catalog|namespace>
+```
+
+#### Showing the CREATE statement of a View
+
Review Comment:
```suggestion
#### Displaying the view DDL statement
Display the view's DDL statement using `SHOW CREATE TABLE`:
!!! note
This follows the [Spark SQL
syntax](https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-aux-show-create-table.html#description)
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,85 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg Views in Spark
+
+#### Creating a View
+Creating a view in its simplest form can be done as shown below:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL from failing in case the view already
exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+It is also possible to use a modified schema for the view, where each column
has an alias that is different from the source table and carries a comment.
+Additionally, the view itself can have a comment as can be seen below:
+```sql
+CREATE VIEW <viewName> (ID COMMENT 'Unique ID', ZIP COMMENT 'Zipcode')
+ COMMENT 'View Comment'
+ AS SELECT id, zip FROM <tableName>
+```
+
+#### Creating a View with Properties
+
+A view can be created with properties by using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+These properties can be displayed using:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Replacing a View
+
+Updating a view's schema, its properties, or the underlying SQL can be
achieved as shown below:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting/removing View properties
+
+Properties can be set via the following SQL:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Properties can be removed using:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1')
+```
+
+#### Showing available Views
+
+The below SQL will list all views in the currently set namespace:
+```sql
+SHOW VIEWS
+```
+
+The below SQL will list all available views in the defined catalog/namespace
+```sql
+SHOW VIEWS IN <catalog|namespace>
+```
+
+#### Showing the CREATE statement of a View
+
+```sql
+SHOW CREATE TABLE <viewName>
+```
+
+#### Describing a View
+
+A view can be described using the below SQL:
Review Comment:
```suggestion
#### Displaying view details
Display more view details using the `DESCRIBE` statement:
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For additional commands, e-mail: issues-h...@iceberg.apache.org
