[SPARK-50309][SQL] Add documentation for SQL pipe syntax #48852
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
dtenedor
changed the title
|
cc @cloud-fan @gengliangwang here is documentation support for the new SQL pipe syntax, which is nearly completed. |
|
@dtenedor The doc looks good to me overall. |
docs/sql-pipe-syntax.md
Outdated
| * To perform full-table aggregation, use the `AGGREGATE` operator with a list of aggregate | ||
| expressions to evaluate.<br> | ||
| This returns one single row in the output table. | ||
| * To perform aggregation with grouping, use the `AGGREGATE` oeprator with a `GROUP BY` clause.<br> |
There was a problem hiding this comment.
Suggested change
| * To perform aggregation with grouping, use the `AGGREGATE` oeprator with a `GROUP BY` clause.<br> | |
| * To perform aggregation with grouping, use the `AGGREGATE` operator with a `GROUP BY` clause.<br> |
docs/sql-pipe-syntax.md
Outdated
| | `LIMIT <n> [OFFSET <m>]` | Returns the specified number of input rows, preserving ordering<br/>(if any). | | ||
| | `AGGREGATE <agg_expr> [[AS] alias], ...` | Performs full-table aggregation, returning one result row with<br/>a column for each aggregate expression. | | ||
| | `AGGREGATE [<agg_expr> [[AS] alias], ...]`<br/>`GROUP BY <grouping_expr> [AS alias], ...` | Performs aggregation with grouping, returning one row per group.<br/>The column list includes the grouping columns first and then the<br/>aggregate columns afterwards. Aliases can be assigned directly<br/>on grouping expressions. | | ||
| | `[LEFT \| ...] JOIN <relation>`<br/>` [ON <condition> \| USING(col, ...)]` | Joins rows from both inputs, returning a filtered cross-product of<br/>the pipe input table and the table expression following the<br/>JOIN keyword. | |
There was a problem hiding this comment.
Let's put down all the supported join types?
There was a problem hiding this comment.
Sounds good, updated.
docs/sql-pipe-syntax.md
Outdated
| | `AGGREGATE <agg_expr> [[AS] alias], ...` | Performs full-table aggregation, returning one result row with<br/>a column for each aggregate expression. | | ||
| | `AGGREGATE [<agg_expr> [[AS] alias], ...]`<br/>`GROUP BY <grouping_expr> [AS alias], ...` | Performs aggregation with grouping, returning one row per group.<br/>The column list includes the grouping columns first and then the<br/>aggregate columns afterwards. Aliases can be assigned directly<br/>on grouping expressions. | | ||
| | `[LEFT \| ...] JOIN <relation>`<br/>` [ON <condition> \| USING(col, ...)]` | Joins rows from both inputs, returning a filtered cross-product of<br/>the pipe input table and the table expression following the<br/>JOIN keyword. | | ||
| | `ORDER BY <expr> [ASC \| DESC], ...` | Returns the input rows after sorting as indicated. | |
There was a problem hiding this comment.
Here is the doc for ORDER BY: https://spark.apache.org/docs/latest/sql-ref-syntax-qry-select-orderby.html
Do we support nulls_sort_order?
There was a problem hiding this comment.
Yes, we do support it. I added a mention for this.
|
@gengliangwang thanks for your review! I updated the docs with more examples and information per recommendation, please take another look. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What changes were proposed in this pull request?
This PR adds documentation for SQL pipe syntax.
Why are the changes needed?
It provides a reference table of available operators and describes how the syntax works in each of the supported circumstances.
Does this PR introduce any user-facing change?
No, this is a documentation-only change.
How was this patch tested?
N/A
Was this patch authored or co-authored using generative AI tooling?
No