kevinyu98 commented on a change in pull request #25573:
[SPARK-28833][DOCS][SQL] Document ALTER VIEW command
URL: https://github.com/apache/spark/pull/25573#discussion_r344849321
##########
File path: docs/sql-ref-syntax-ddl-alter-view.md
##########
@@ -19,4 +19,217 @@ license: |
limitations under the License.
---
-**This page is under construction**
+### Description
+The `ALTER VIEW` statement can alter metadata associated with the view. It can
change the definition of the view, change
+the name of a view to a different name, set and unset the metadata of the view
by setting `TBLPROPERTIES`.
+
+#### Rename VIEW
+Renames the existing view. If the view name already exists in the source
database, a TableAlreadyExistsException is thrown. This operation
+does not support moving the views cross databases.
+
+##### Syntax
+{% highlight sql %}
+ALTER VIEW view_identifier RENAME TO view_identifier
+{% endhighlight %}
+
+##### Parameters
+<dl>
+ <dt><code><em>view_identifier</em></code></dt>
+ <dd>
+ Specifies a view name, which may be optionally qualified with a database
name.<br><br>
+ <b> Syntax:</b>
+ <code>
+ [database_name.]view_name
+ </code>
+ </dd>
+</dl>
+
+#### Set VIEW Properties
+Set one or more properties of an existing view. The properties are the key
value pairs. If the properties' keys exist,
+the values are replaced with the new values. If the properties' keys do not
exist, the key value pairs are added into
+the properties.
+
+##### Syntax
+{% highlight sql %}
+ALTER VIEW view_identifier SET TBLPROPERTIES
+ (property_key=property_val [, ...])
+{% endhighlight %}
+
+##### Parameters
+<dl>
+ <dt><code><em>view_identifier</em></code></dt>
+ <dd>
+ Specifies a view name, which may be optionally qualified with a database
name.<br><br>
+ <b> Syntax:</b>
+ <code>
+ [database_name.]view_name
+ </code>
+ </dd>
+ <dt><code><em>property_key</em></code></dt>
+ <dd>
+ Specifies the property key. The key may consists of multiple parts
separated by dot.<br><br>
+ <b>Syntax:</b>
+ <code>
+ [key_part1][.key_part2][...]
+ </code>
+ </dd>
+</dl>
+
+#### Drop VIEW properties
+Drop one or more properties of an existing view. If the specified keys do not
exist, an exception is thrown. Use
+`IF EXISTS` to avoid the exception.
+
+##### Syntax
+{% highlight sql %}
+ALTER VIEW view_identifier UNSET TBLPROPERTIES [IF EXISTS]
+ (property_key [, ...])
+{% endhighlight %}
+
+##### Parameters
+<dl>
+ <dt><code><em>view_identifier</em></code></dt>
+ <dd>
+ Specifies a view name, which may be optionally qualified with a database
name.<br><br>
+ <b> Syntax:</b>
+ <code>
+ [database_name.]view_name
+ </code>
+ </dd>
+ <dt><code><em>property_key</em></code></dt>
+ <dd>
+ Specifies the property key. The key may consists of multiple parts
separated by dot.<br><br>
+ <b>Syntax:</b>
+ <code>
+ [key_part1][.key_part2][...]
+ </code>
+ </dd>
+</dl>
+
+#### Alter VIEW As Select
+`ALTER VIEW view_identifier AS SELECT` statement changes the definition of a
view, the `SELECT` statement must be valid,
+and the `view_identifier` must exist.
+
+##### Syntax
+{% highlight sql %}
+ALTER VIEW view_identifier AS select_statement
+{% endhighlight %}
+
+##### Parameters
+<dl>
+ <dt><code><em>view_identifier</em></code></dt>
+ <dd>
+ Specifies a view name, which may be optionally qualified with a database
name.<br><br>
+ <b> Syntax:</b>
+ <code>
+ [database_name.]view_name
+ </code>
+ </dd>
+ <dt><code><em>select_statement</em></code></dt>
+ <dd>
+ Specifies the definition of the view, detail check
[select_statement](sql-ref-syntax-qry-select.html)
+ </dd>
+</dl>
+
+#### Examples
+{% highlight sql %}
+-- Rename only changes the view name.
+-- The source and target databases of the view have to be the same, use
qualified or unqualified name for the target view
+ALTER VIEW tempdb1.v1 RENAME TO v2;
+
+-- Verify that the new view is created.
+DESCRIBE TABLE EXTENDED tempdb1.v2;
+
++----------------------------+----------+-------+
+|col_name |data_type |comment|
++----------------------------+----------+-------+
+|c1 |int |null |
+|c2 |string |null |
+| | | |
+|# Detailed Table Information| | |
+|Database |tempdb1 | |
+|Table |v2 | |
++----------------------------+----------+-------+
+
+-- Use `DESC TABLE EXTENDED tempdb1.v2` before and after the `ALTER VIEW`
statement to verify the changes.
+-- Before ALTER VIEW SET TBLPROPERTIES
+DESC TABLE EXTENDED tempdb1.v2;
+
++----------------------------+----------+-------+
+|col_name |data_type |comment|
++----------------------------+----------+-------+
+|c1 |int |null |
+|c2 |string |null |
+| | | |
+|# Detailed Table Information| | |
+|Database |tempdb1 | |
+|Table |v2 | |
+|Table Properties |[....] | |
++----------------------------+----------+-------+
+
+-- Set properties in TBLPROPERTIES
+ALTER VIEW tempdb1.v2 SET TBLPROPERTIES ('created.by.user' = "John",
'created.date' = '01-01-2001' );
+
+-- Use `DESCRIBE TABLE EXTENDED tempdb1.v2` to verify
+DESC TABLE EXTENDED tempdb1.v2;
+
++----------------------------+-----------------------------------------------------+-------+
+|col_name |data_type
|comment|
++----------------------------+-----------------------------------------------------+-------+
+|c1 |int
|null |
+|c2 |string
|null |
+| |
| |
+|# Detailed Table Information|
| |
+|Database |tempdb1
| |
+|Table |v2
| |
+|Table Properties |[created.by.user=John, created.date=01-01-2001,
....]| |
++----------------------------+-----------------------------------------------------+-------+
+
+-- Use `DESC TABLE EXTENDED tempdb1.v2` before and after the `ALTER VIEW` to
verify the change.
+-- Remove the key created.by.user and created.date from TBLPROPERTIES
+ALTER VIEW tempdb1.v2 UNSET TBLPROPERTIES ('created.by.user', 'created.date');
+
+--Use `DESC TABLE EXTENDED tempdb1.v2` to verify the changes
+DESC TABLE EXTENDED tempdb1.v2;
+
++----------------------------+----------+-------+
+|col_name |data_type |comment|
++----------------------------+----------+-------+
+|c1 |int |null |
+|c2 |string |null |
+| | | |
+|# Detailed Table Information| | |
+|Database |tempdb1 | |
+|Table |v2 | |
+|Table Properties |[....] | |
++----------------------------+----------+-------+
+
+-- Do the select on tempdb.view1 before and after the `ALTER VIEW` statement
to verify.
+-- Change the view definition
+ALTER VIEW tempdb1.v2 AS SELECT * FROM tempdb1.v1;
+
+-- Use `DESC TABLE EXTENDED` to verify
+DESC TABLE EXTENDED tempdb1.v2;
+
++----------------------------+---------------------------+-------+
+|col_name |data_type |comment|
++----------------------------+---------------------------+-------+
+|c1 |int |null |
+|c2 |string |null |
+| | | |
+|# Detailed Table Information| | |
+|Database |tempdb1 | |
+|Table |v2 | |
+|Type |VIEW | |
+|View Text |select * from tempdb1.v1 | |
+|View Original Text |select * from tempdb1.v1 | |
++----------------------------+---------------------------+-------+
+{% endhighlight %}
+
+#### Related Statements
+- [describe-table](sql-ref-syntax-aux-describe-table.html)
+- [create-view](sql-ref-syntax-ddl-create-view.html)
+- [drop-view](sql-ref-syntax-ddl-drop-view.html)
+- [select](sql-ref-syntax-qry-select.md)
Review comment:
removed
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscr...@spark.apache.org
For additional commands, e-mail: reviews-h...@spark.apache.org
