[SPARK-30581][DOC] Document SORT BY Clause of SELECT statement in SQLReference #27289
Conversation
|
Test build #117108 has finished for PR 27289 at commit
|
| <dl> | ||
| <dt><code><em>SORT BY</em></code></dt> | ||
| <dd> | ||
| Specifies a comma separated list of expression along with optional parameters sort_direction |
There was a problem hiding this comment.
comma-separated
expression -> expresisons
Back-tick things like sort_direction, etc.
| <dt><code><em>nulls_sort_order</em></code></dt> | ||
| <dd> | ||
| Optionally specifies whether NULL values are returned before/after non-NULL values, based on the | ||
| sort direction. In spark, NULL values are considered to be lower than any non-NULL values. Therefore |
There was a problem hiding this comment.
spark -> Spark. Are you describing a default here? make it explicit if so. Because this option lets you control that behavior, right?
|
Test build #117136 has finished for PR 27289 at commit
|
| limitations under the License. | ||
| --- | ||
| The <code>SORT BY</code> clause is used to return the result rows sorted | ||
| within each partition in the user specified order. When there are more than one partition |
There was a problem hiding this comment.
When there are more than one partition -> When there is more than one partition?
|
Test build #117159 has finished for PR 27289 at commit
|
|
|
||
| ### Syntax | ||
| {% highlight sql %} | ||
| SORT BY { expression [ sort_direction | nulls_sort_oder ] [ , ...] } |
There was a problem hiding this comment.
Is this actually different from ORDER BY or are they aliases? do we need to copy the docs if so?
There was a problem hiding this comment.
@srowen Yeah.. they are a bit different. ORDER BY performs a total sort where as SORT BY does sort within a partition. I kept them separate for only reason that to the best of my understanding "SORT BY" is not a frequently used clause. Its a hive compatibility thing. I thought of keeping them separate as with discussion with @gatorsmile we think we should have a top level link for "simple select" and "full select". In the "simple select" link, we will only include the most used clauses (i.e not include things like sort by, distribute by and cluster by).
There was a problem hiding this comment.
OK same comments here apply to the ORDER BY PR too then, I guess
There was a problem hiding this comment.
If most parts are duplicate, how about working on ORDER BY first, then copying the committed (final) version of ORDER BY here for less review overheads?
There was a problem hiding this comment.
Sounds good @maropu.
|
Test build #117265 has finished for PR 27289 at commit
|
|
Test build #117279 has finished for PR 27289 at commit
|
|
Test build #117293 has finished for PR 27289 at commit
|
|
Test build #117299 has finished for PR 27289 at commit
|
|
Test build #117302 has finished for PR 27289 at commit
|
ea68204 to
6177310
Compare
|
Test build #117414 has finished for PR 27289 at commit
|
|
How about explicitly leaving some comments about the difference between ORDER BY and SORT BY behaviours somewhere in this doc? The other parts looks fine to me. |
|
@maropu I had tried to document this in the main description section like this :
What do you think ? |
|
@dilipbiswal Yea, that looks ok. |
|
Merged to master |
What changes were proposed in this pull request?
Document SORT BY clause of SELECT statement in SQL Reference Guide.
Why are the changes needed?
Currently Spark lacks documentation on the supported SQL constructs causing
confusion among users who sometimes have to look at the code to understand the
usage. This is aimed at addressing this issue.
Does this PR introduce any user-facing change?
Yes.
Before:
There was no documentation for this.
After.
How was this patch tested?
Tested using jykyll build --serve