Skip to content

Commit fca0a6c

Browse files
kevinyu98srowen
kevinyu98
authored and
srowen
committed
[SPARK-28833][DOCS][SQL] Document ALTER VIEW command
### What changes were proposed in this pull request? Document ALTER VIEW statement in the SQL Reference Guide. ### Why are the changes needed? Currently Spark SQL doc lacks documentation on the supported SQL syntax. This pr is aimed to address this issue. ### Does this PR introduce any user-facing change? Yes #### Before: There was no documentation for this. #### After: ![Screen Shot 2019-11-13 at 10 51 33 PM](https://user-images.githubusercontent.com/7550280/68833575-ac947f80-0668-11ea-910f-c133407ef502.png) ![Screen Shot 2019-11-13 at 10 56 42 PM](https://user-images.githubusercontent.com/7550280/68833597-bae29b80-0668-11ea-9782-b7be94789c12.png) ![Screen Shot 2019-11-13 at 10 56 53 PM](https://user-images.githubusercontent.com/7550280/68833607-be762280-0668-11ea-8a30-5602e755bab8.png) ### How was this patch tested? Tested using jkyll build --serve Closes apache#25573 from kevinyu98/spark-28833-alterview. Authored-by: Kevin Yu <[email protected]> Signed-off-by: Sean Owen <[email protected]>
1 parent 04e99c1 commit fca0a6c

File tree

1 file changed

+214
-1
lines changed

1 file changed

+214
-1
lines changed

‎docs/sql-ref-syntax-ddl-alter-view.md

Lines changed: 214 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,217 @@ license: |
1919
limitations under the License.
2020
---
2121

22-
**This page is under construction**
22+
### Description
23+
24+
The `ALTER VIEW` statement can alter metadata associated with the view. It can change the definition of the view, change
25+
the name of a view to a different name, set and unset the metadata of the view by setting `TBLPROPERTIES`.
26+
27+
#### RENAME View
28+
Renames the existing view. If the new view name already exists in the source database, a `TableAlreadyExistsException` is thrown. This operation
29+
does not support moving the views across databases.
30+
31+
#### Syntax
32+
{% highlight sql %}
33+
ALTER VIEW view_identifier RENAME TO view_identifier
34+
{% endhighlight %}
35+
36+
#### Parameters
37+
<dl>
38+
<dt><code><em>view_identifier</em></code></dt>
39+
<dd>
40+
Specifies a view name, which may be optionally qualified with a database name.<br><br>
41+
<b> Syntax:</b>
42+
<code>
43+
[database_name.]view_name
44+
</code>
45+
</dd>
46+
</dl>
47+
48+
#### SET View Properties
49+
Set one or more properties of an existing view. The properties are the key value pairs. If the properties' keys exist,
50+
the values are replaced with the new values. If the properties' keys do not exist, the key value pairs are added into
51+
the properties.
52+
53+
#### Syntax
54+
{% highlight sql %}
55+
ALTER VIEW view_identifier SET TBLPROPERTIES (property_key=property_val [, ...])
56+
{% endhighlight %}
57+
58+
#### Parameters
59+
<dl>
60+
<dt><code><em>view_identifier</em></code></dt>
61+
<dd>
62+
Specifies a view name, which may be optionally qualified with a database name.<br><br>
63+
<b> Syntax:</b>
64+
<code>
65+
[database_name.]view_name
66+
</code>
67+
</dd>
68+
<dt><code><em>property_key</em></code></dt>
69+
<dd>
70+
Specifies the property key. The key may consists of multiple parts separated by dot.<br><br>
71+
<b>Syntax:</b>
72+
<code>
73+
[key_part1][.key_part2][...]
74+
</code>
75+
</dd>
76+
</dl>
77+
78+
#### UNSET View Properties
79+
Drop one or more properties of an existing view. If the specified keys do not exist, an exception is thrown. Use
80+
`IF EXISTS` to avoid the exception.
81+
82+
#### Syntax
83+
{% highlight sql %}
84+
ALTER VIEW view_identifier UNSET TBLPROPERTIES [IF EXISTS] (property_key [, ...])
85+
{% endhighlight %}
86+
87+
#### Parameters
88+
<dl>
89+
<dt><code><em>view_identifier</em></code></dt>
90+
<dd>
91+
Specifies a view name, which may be optionally qualified with a database name.<br><br>
92+
<b> Syntax:</b>
93+
<code>
94+
[database_name.]view_name
95+
</code>
96+
</dd>
97+
<dt><code><em>property_key</em></code></dt>
98+
<dd>
99+
Specifies the property key. The key may consists of multiple parts separated by dot.<br><br>
100+
<b>Syntax:</b>
101+
<code>
102+
[key_part1][.key_part2][...]
103+
</code>
104+
</dd>
105+
</dl>
106+
107+
#### ALTER View AS SELECT
108+
`ALTER VIEW view_identifier AS SELECT` statement changes the definition of a view, the `SELECT` statement must be valid,
109+
and the `view_identifier` must exist.
110+
111+
#### Syntax
112+
{% highlight sql %}
113+
ALTER VIEW view_identifier AS select_statement
114+
{% endhighlight %}
115+
116+
#### Parameters
117+
<dl>
118+
<dt><code><em>view_identifier</em></code></dt>
119+
<dd>
120+
Specifies a view name, which may be optionally qualified with a database name.<br><br>
121+
<b> Syntax:</b>
122+
<code>
123+
[database_name.]view_name
124+
</code>
125+
</dd>
126+
<dt><code><em>select_statement</em></code></dt>
127+
<dd>
128+
Specifies the definition of the view, detail check <a href="sql-ref-syntax-qry-select.html">select_statement</a>
129+
</dd>
130+
</dl>
131+
132+
### Examples
133+
134+
{% highlight sql %}
135+
-- Rename only changes the view name.
136+
-- The source and target databases of the view have to be the same.
137+
-- Use qualified or unqualified name for the source and target view
138+
ALTER VIEW tempdb1.v1 RENAME TO tempdb1.v2;
139+
140+
-- Verify that the new view is created.
141+
DESCRIBE TABLE EXTENDED tempdb1.v2;
142+
143+
+----------------------------+----------+-------+
144+
|col_name |data_type |comment|
145+
+----------------------------+----------+-------+
146+
|c1 |int |null |
147+
|c2 |string |null |
148+
| | | |
149+
|# Detailed Table Information| | |
150+
|Database |tempdb1 | |
151+
|Table |v2 | |
152+
+----------------------------+----------+-------+
153+
154+
-- Before ALTER VIEW SET TBLPROPERTIES
155+
DESC TABLE EXTENDED tempdb1.v2;
156+
157+
+----------------------------+----------+-------+
158+
|col_name |data_type |comment|
159+
+----------------------------+----------+-------+
160+
|c1 |int |null |
161+
|c2 |string |null |
162+
| | | |
163+
|# Detailed Table Information| | |
164+
|Database |tempdb1 | |
165+
|Table |v2 | |
166+
|Table Properties |[....] | |
167+
+----------------------------+----------+-------+
168+
169+
-- Set properties in TBLPROPERTIES
170+
ALTER VIEW tempdb1.v2 SET TBLPROPERTIES ('created.by.user' = "John", 'created.date' = '01-01-2001' );
171+
172+
-- Use `DESCRIBE TABLE EXTENDED tempdb1.v2` to verify
173+
DESC TABLE EXTENDED tempdb1.v2;
174+
175+
+----------------------------+-----------------------------------------------------+-------+
176+
|col_name |data_type |comment|
177+
+----------------------------+-----------------------------------------------------+-------+
178+
|c1 |int |null |
179+
|c2 |string |null |
180+
| | | |
181+
|# Detailed Table Information| | |
182+
|Database |tempdb1 | |
183+
|Table |v2 | |
184+
|Table Properties |[created.by.user=John, created.date=01-01-2001, ....]| |
185+
+----------------------------+-----------------------------------------------------+-------+
186+
187+
-- Remove the key `created.by.user` and `created.date` from `TBLPROPERTIES`
188+
ALTER VIEW tempdb1.v2 UNSET TBLPROPERTIES ('created.by.user', 'created.date');
189+
190+
--Use `DESC TABLE EXTENDED tempdb1.v2` to verify the changes
191+
DESC TABLE EXTENDED tempdb1.v2;
192+
193+
+----------------------------+----------+-------+
194+
|col_name |data_type |comment|
195+
+----------------------------+----------+-------+
196+
|c1 |int |null |
197+
|c2 |string |null |
198+
| | | |
199+
|# Detailed Table Information| | |
200+
|Database |tempdb1 | |
201+
|Table |v2 | |
202+
|Table Properties |[....] | |
203+
+----------------------------+----------+-------+
204+
205+
-- Change the view definition
206+
ALTER VIEW tempdb1.v2 AS SELECT * FROM tempdb1.v1;
207+
208+
-- Use `DESC TABLE EXTENDED` to verify
209+
DESC TABLE EXTENDED tempdb1.v2;
210+
211+
+----------------------------+---------------------------+-------+
212+
|col_name |data_type |comment|
213+
+----------------------------+---------------------------+-------+
214+
|c1 |int |null |
215+
|c2 |string |null |
216+
| | | |
217+
|# Detailed Table Information| | |
218+
|Database |tempdb1 | |
219+
|Table |v2 | |
220+
|Type |VIEW | |
221+
|View Text |select * from tempdb1.v1 | |
222+
|View Original Text |select * from tempdb1.v1 | |
223+
+----------------------------+---------------------------+-------+
224+
{% endhighlight %}
225+
226+
### Related Statements
227+
228+
- [describe-table](sql-ref-syntax-aux-describe-table.html)
229+
- [create-view](sql-ref-syntax-ddl-create-view.html)
230+
- [drop-view](sql-ref-syntax-ddl-drop-view.html)
231+
232+
#### Note:
233+
234+
`ALTER VIEW` statement does not support `SET SERDE` or `SET SERDEPROPERTIES` properties
235+

0 commit comments

Comments
 (0)