You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@iceberg.apache.org by "nastra (via GitHub)" <gi...@apache.org> on 2024/03/06 11:08:42 UTC
[PR] Docs: Add DDL docs for Views [iceberg]
nastra opened a new pull request, #9878:
URL: https://github.com/apache/iceberg/pull/9878
(no comment)
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1516115104
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+Display view properties:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Dropping a view
+
+Drop an existing view:
+```sql
+DROP VIEW <viewName>
+```
+
+Using `IF EXISTS` prevents the SQL statment from failing if the view does not exist:
+```sql
+DROP VIEW IF EXISTS <viewName>
+```
+
+#### Replacing a view
+
+Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting and removing view properties
+
+Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
+```
+
+#### Showing available views
+
+The below SQL will list all views in the currently set namespace (via `USE <namespace>`):
+```sql
+SHOW VIEWS
+```
+
+List all available views in the defined catalog and/or namespace using one of the below variations:
+```sql
+SHOW VIEWS IN <catalog>
+```
+```sql
+SHOW VIEWS IN <namespace>
+```
+```sql
+SHOW VIEWS IN catalog.namespace
+```
+
+#### Showing the CREATE statement of a view
+
Review Comment:
makes sense, updated
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+Display view properties:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Dropping a view
+
+Drop an existing view:
+```sql
+DROP VIEW <viewName>
+```
+
+Using `IF EXISTS` prevents the SQL statment from failing if the view does not exist:
+```sql
+DROP VIEW IF EXISTS <viewName>
+```
+
+#### Replacing a view
+
+Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting and removing view properties
+
+Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
+```
+
+#### Showing available views
+
+The below SQL will list all views in the currently set namespace (via `USE <namespace>`):
+```sql
+SHOW VIEWS
+```
+
+List all available views in the defined catalog and/or namespace using one of the below variations:
+```sql
+SHOW VIEWS IN <catalog>
+```
+```sql
+SHOW VIEWS IN <namespace>
+```
+```sql
+SHOW VIEWS IN catalog.namespace
Review Comment:
done
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515708669
##########
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
Review Comment:
added a note mentioning that this is only supported for Spark 3.4+
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1516115351
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
Review Comment:
good catch, updated
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra merged PR #9878:
URL: https://github.com/apache/iceberg/pull/9878
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1516076704
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
Review Comment:
may be mention as 3.4 and above, 3.4+ might suggest that above 3.4 (excluding 3.4)
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515824918
##########
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 was trying to match the example from Spark here
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#issuecomment-1983465385
thanks for reviewing @ajantha-bhat and @bitsondatadev
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1514341452
##########
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>
+```
Review Comment:
this is describing SQL-level examples where you can't specify the dialect as it's controlled by the engine that executes the SQL
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515645687
##########
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:
everything follows the Spark SQL syntax, so `SHOW CREATE TABLE` is not the only one.
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515829364
##########
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
Review Comment:
yes forgot to push, should be there now
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "bitsondatadev (via GitHub)" <gi...@apache.org>.
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1514339962
##########
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 stmt of a View
+
+```sql
+SHOW CREATE TABLE <viewName>
Review Comment:
yes that's the official Spark syntax
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1514308982
##########
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 stmt of a View
Review Comment:
```suggestion
#### Showing the CREATE statement of a 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:
+```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 stmt of a View
+
+```sql
+SHOW CREATE TABLE <viewName>
Review Comment:
`Table` keyword here and `TBLPROPERTIES` keywords above looks weird for view.
But thats how the Spark syntax is also maintained I guess.
https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-ddl-create-view.html#create-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:
+```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>
+```
Review Comment:
Can we add an example if replacing view with new dialect? (only API supports it and SQL doesn't?)
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515692131
##########
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:
I've added links to all existing Spark SQLs at the top of the section
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515655248
##########
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:
I think this should say `aim` instead of `aims`, since it's referring to `Iceberg views`
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "nastra (via GitHub)" <gi...@apache.org>.
nastra commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515828965
##########
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:
I've framed this slightly differently
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "bitsondatadev (via GitHub)" <gi...@apache.org>.
bitsondatadev commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1516075615
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
Review Comment:
Nit
```suggestion
CREATE VIEW <viewName> AS SELECT * FROM <tableName>
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
Review Comment:
nit x2
```suggestion
CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * FROM <tableName>
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+Display view properties:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Dropping a view
+
+Drop an existing view:
+```sql
+DROP VIEW <viewName>
+```
+
+Using `IF EXISTS` prevents the SQL statment from failing if the view does not exist:
+```sql
+DROP VIEW IF EXISTS <viewName>
+```
+
+#### Replacing a view
+
+Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting and removing view properties
+
+Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
+```
+
+#### Showing available views
+
+The below SQL will list all views in the currently set namespace (via `USE <namespace>`):
Review Comment:
```suggestion
List all views in the currently set namespace (via `USE <namespace>`):
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+Display view properties:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Dropping a view
+
+Drop an existing view:
+```sql
+DROP VIEW <viewName>
+```
+
+Using `IF EXISTS` prevents the SQL statment from failing if the view does not exist:
+```sql
+DROP VIEW IF EXISTS <viewName>
+```
+
+#### Replacing a view
+
+Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting and removing view properties
+
+Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
+```
+
+#### Showing available views
+
+The below SQL will list all views in the currently set namespace (via `USE <namespace>`):
+```sql
+SHOW VIEWS
+```
+
+List all available views in the defined catalog and/or namespace using one of the below variations:
+```sql
+SHOW VIEWS IN <catalog>
+```
+```sql
+SHOW VIEWS IN <namespace>
+```
+```sql
+SHOW VIEWS IN catalog.namespace
+```
+
+#### Showing the CREATE statement of a view
+
Review Comment:
Nit
This should have text between the header and the code IMO.
I like to keep headers brief and the current header would make an excellent directive.
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
Review Comment:
nit x3
```suggestion
AS SELECT * FROM <tableName>
```
##########
docs/docs/spark-ddl.md:
##########
@@ -566,3 +566,118 @@ Tags can be removed via the `DROP TAG` sql
```sql
ALTER TABLE prod.db.sample DROP TAG `historical-tag`
```
+
+### Iceberg views in Spark
+
+Iceberg views are a [common representation](../../view-spec.md) of a SQL view that aim to be interpreted across multiple query engines.
+This section covers how to create and manage views in Spark using Spark 3.4+ (earlier versions of Spark are not supported).
+
+!!! note
+
+ All the SQL examples in this section follow the official Spark SQL syntax:
+
+ * [CREATE VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-view.html#create-view)
+ * [ALTER VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-alter-view.html)
+ * [DROP VIEW](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-drop-view.html)
+ * [SHOW VIEWS](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-views.html)
+ * [SHOW TBLPROPERTIES](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-tblproperties.html)
+ * [SHOW CREATE TABLE](https://spark.apache.org/docs/latest/sql-ref-syntax-aux-show-create-table.html)
+
+
+#### Creating a view
+
+Create a simple view without any comments or properties:
+```sql
+CREATE VIEW <viewName> AS SELECT * from <tableName>
+```
+
+Using `IF NOT EXISTS` prevents the SQL statement from failing in case the view already exists:
+```sql
+CREATE VIEW IF NOT EXISTS <viewName> AS SELECT * from <tableName>
+```
+
+Create a view with a comment, including aliased and commented columns that are different from the source table:
+```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
+
+Create a view with properties using `TBLPROPERTIES`:
+```sql
+CREATE VIEW <viewName>
+ TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+ AS SELECT * from <tableName>
+```
+
+Display view properties:
+```sql
+SHOW TBLPROPERTIES <viewName>
+```
+
+#### Dropping a view
+
+Drop an existing view:
+```sql
+DROP VIEW <viewName>
+```
+
+Using `IF EXISTS` prevents the SQL statment from failing if the view does not exist:
+```sql
+DROP VIEW IF EXISTS <viewName>
+```
+
+#### Replacing a view
+
+Update a view's schema, its properties, or the underlying SQL statement using `CREATE OR REPLACE`:
+```sql
+CREATE OR REPLACE <viewName> (updated_id COMMENT 'updated ID')
+ TBLPROPERTIES ('key1' = 'new_val1')
+ AS SELECT id FROM <tableName>
+```
+
+#### Setting and removing view properties
+
+Set the properties of an existing view using `ALTER VIEW ... SET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> SET TBLPROPERTIES ('key1' = 'val1', 'key2' = 'val2')
+```
+
+Remove the properties from an existing view using `ALTER VIEW ... UNSET TBLPROPERTIES`:
+```sql
+ALTER VIEW <viewName> UNSET TBLPROPERTIES ('key1', 'key2')
+```
+
+#### Showing available views
+
+The below SQL will list all views in the currently set namespace (via `USE <namespace>`):
+```sql
+SHOW VIEWS
+```
+
+List all available views in the defined catalog and/or namespace using one of the below variations:
+```sql
+SHOW VIEWS IN <catalog>
+```
+```sql
+SHOW VIEWS IN <namespace>
+```
+```sql
+SHOW VIEWS IN catalog.namespace
Review Comment:
```suggestion
SHOW VIEWS IN <catalog>.<namespace>
```
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515696765
##########
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
Review Comment:
I just saw that Spark-3.3 wont support these syntax. I think we should document it aswell.
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org
Re: [PR] Docs: Add DDL docs for Views [iceberg]
Posted by "ajantha-bhat (via GitHub)" <gi...@apache.org>.
ajantha-bhat commented on code in PR #9878:
URL: https://github.com/apache/iceberg/pull/9878#discussion_r1515815655
##########
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
Review Comment:
Did you forgot to push it? I couldn't see.
--
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-unsubscribe@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@iceberg.apache.org
For additional commands, e-mail: issues-help@iceberg.apache.org