huaxingao commented on a change in pull request #28196:
[SPARK-31428][SQL][DOCS] Document Common Table Expression in SQL Reference
URL: https://github.com/apache/spark/pull/28196#discussion_r407886814
##########
File path: docs/sql-ref-syntax-qry-select-cte.md
##########
@@ -19,4 +19,111 @@ license: |
limitations under the License.
---
-**This page is under construction**
+### Description
+
+A common table expression (CTE) defines a temporary result set that a user can
reference possibly multiple times within the scope of a SQL statement. A CTE is
used mainly in a SELECT statement.
+
+### Syntax
+
+{% highlight sql %}
+WITH common_table_expression [ , ... ]
+{% endhighlight %}
+
+While `common_table_expression` is defined as
+{% highlight sql %}
+expression_name [ ( column_name [ , ... ] ) ] [ AS ] ( [
common_table_expression ] query )
+{% endhighlight %}
+
+### Parameters
+
+<dl>
+ <dt><code><em>expression_name</em></code></dt>
+ <dd>
+ Specifies a name for the common table expression.
+ </dd>
+</dl>
+<dl>
+ <dt><code><em>query</em></code></dt>
+ <dd>
+ A <a href="sql-ref-syntax-qry-select.html">SELECT</a> statement.
+ </dd>
+</dl>
+
+### Examples
+
+{% highlight sql %}
+-- CTE with multiple column aliases
+WITH t(x, y) AS (SELECT 1, 2)
+SELECT * FROM t WHERE x = 1 AND y = 2;
+ +---+---+
+ | x| y|
+ +---+---+
+ | 1| 2|
+ +---+---+
+
+-- CTE in CTE definition
+WITH t as (
+ WITH t2 AS (SELECT 1)
+ SELECT * FROM t2
+)
+SELECT * FROM t;
+ +---+
+ | 1|
+ +---+
+ | 1|
+ +---+
+
+-- CTE in subquery
+SELECT max(c) FROM (
+ WITH t(c) AS (SELECT 1)
+ SELECT * FROM t
+);
+ +------+
+ |max(c)|
+ +------+
+ | 1|
+ +------+
+
+-- CTE in subquery expression
+SELECT (
+ WITH t AS (SELECT 1)
+ SELECT * FROM t
+);
+ +----------------+
+ |scalarsubquery()|
+ +----------------+
+ | 1|
+ +----------------+
+
+-- CTE in CREATE VIEW statement
+CREATE VIEW v AS
+ WITH t(a, b, c, d) AS (SELECT 1, 2, 3, 4)
+ SELECT * FROM t;
+SELECT * FROM v;
+ +---+---+---+---+
+ | a| b| c| d|
+ +---+---+---+---+
+ | 1| 2| 3| 4|
+ +---+---+---+---+
+
+-- If name conflict is detected in nested CTE, then AnalysisException is
thrown by default.
Review comment:
Thanks for your comment.
I prefer to document the default behavior. I actually thought the default
behavior is "inner CTE definitions take precedence over outer definitions".
When I tried the example, I was surprised to see the Exception, then I looked
the code and found out I need to set spark.sql.legacy.ctePrecedencePolicy to
make it work. So I guess it is worth mentioning the default 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.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
