Skip to content

[SPARK-49073][SQL][DOCS] Improve the doc sql-ref-syntax-qry-select.md - #47552

Closed
panbingkun wants to merge 6 commits into
apache:masterfrom
panbingkun:sql-ref-syntax-qry-select
Closed

[SPARK-49073][SQL][DOCS] Improve the doc sql-ref-syntax-qry-select.md#47552
panbingkun wants to merge 6 commits into
apache:masterfrom
panbingkun:sql-ref-syntax-qry-select

Conversation

@panbingkun

@panbingkunpanbingkun commented Jul 31, 2024•
edited
Loading

Copy link
Copy Markdown
Contributor

What changes were proposed in this pull request?

The pr aims to update the explanation for star_clause in the doc sql-ref-syntax-qry-select.md.

Why are the changes needed?

Does this PR introduce any user-facing change?

Yes, only for docs.

How was this patch tested?

Manually test.

Was this patch authored or co-authored using generative AI tooling?

No.

@panbingkun

panbingkun commented Jul 31, 2024

Copy link
Copy Markdown
ContributorAuthor

Manually check as follows:
image

panbingkun
panbingkun commented Jul 31, 2024
View reviewed changes
Comment threaddocs/sql-ref-syntax-qry-select.md

An expression with an assigned name. In general, it denotes a column expression.

**Syntax:** `expression [[AS] alias]`

@panbingkunpanbingkunJul 31, 2024

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have already moved this up.

@panbingkun
panbingkun marked this pull request as ready for review July 31, 2024 10:55
@panbingkunpanbingkun changed the title [SPARK-49073][SQL][DOCS] Improve docs sql-ref-syntax-qry-select.md[SPARK-49073][SQL][DOCS] Improve the doc sql-ref-syntax-qry-select.mdJul 31, 2024
@panbingkun

panbingkun commented Jul 31, 2024

Copy link
Copy Markdown
ContributorAuthor

cc @stefankandic@HyukjinKwon

@panbingkun

panbingkun commented Jul 31, 2024

Copy link
Copy Markdown
ContributorAuthor

ref: https://docs.databricks.com/en/sql/language-manual/sql-ref-syntax-qry-select.html

@stefankandic

stefankandic commented Jul 31, 2024

Copy link
Copy Markdown
Contributor

I don't see these link for parameters anywhere in the spark docs, so not sure we should just add them for the select page

@panbingkun

panbingkun commented Jul 31, 2024•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

I understand your concern that it may result in inconsistent document styles.
Perhaps we can apply the above pattern to all parameters of "docs/sql-ref-syntax*.md" files (approximately 89 documents).
I think this clickable parameter can bring convenience to end-users.

(base) ➜ docs git:(master) ✗ find . -name "sql-ref-syntax*.md" | xargs grep "### Parameters" | wc -l
89

WDYT @HyukjinKwon ?

HyukjinKwon
HyukjinKwon reviewed Aug 2, 2024
View reviewed changes
Comment threaddocs/sql-ref-syntax-qry-select.md Outdated
out repeated subquery blocks in the FROM clause and improves readability of the query.

* **hints**
* **[hints](sql-ref-syntax-qry-select-hints.html)**

@HyukjinKwonHyukjinKwonAug 2, 2024

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we go ahead with this, we should probably do it for all? I would separate the PR

@panbingkunpanbingkunAug 2, 2024•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay,
I will restore the related clickable parameter first in this pr, and I will do it in another separate PR.

@panbingkunpanbingkunAug 2, 2024

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

allisonwang-db
allisonwang-db reviewed Aug 7, 2024
View reviewed changes
Comment threaddocs/sql-ref-syntax-qry-select.md Outdated
Comment threaddocs/sql-ref-syntax-qry-select.md
While `select_statement` is defined as
```sql
SELECT [ hints , ... ] [ ALL | DISTINCT ] { [ [ named_expression | regex_column_names | star ] [ , ... ] | TRANSFORM (...) ] }
SELECT [ hints , ... ] [ ALL | DISTINCT ] { [ [ named_expression | regex_column_names | star_clause ] [ , ... ] | TRANSFORM (...) ] }

@allisonwang-dballisonwang-dbAug 7, 2024

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should do star [ except_clause ] instead of having except_clause inside the star_clause.

@panbingkunpanbingkunAug 8, 2024•
edited
Loading

Copy link
Copy Markdown
ContributorAuthor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am referring to this doc https://docs.databricks.com/en/sql/language-manual/sql-ref-syntax-qry-select.html, as follows:
image
Based on my understanding, I think one possible reason is that EXCEPT cannot exist independently of STAR, which seems to emphasize this relationship.

@panbingkun@allisonwang-db
Update docs/sql-ref-syntax-qry-select.md
43c7c0a
Co-authored-by: Allison Wang <allison.wang@databricks.com>
@github-actions

github-actionsBot commented Nov 17, 2024

Copy link
Copy Markdown

We're closing this PR because it hasn't been updated in a while. This isn't a judgement on the merit of the PR in any way. It's just a way of keeping the PR queue manageable.
If you'd like to revive this PR, please reopen it and ask a committer to remove the Stale tag!

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@HyukjinKwonHyukjinKwonHyukjinKwon left review comments
@allisonwang-dballisonwang-dbAwaiting requested review from allisonwang-db

Assignees

No one assigned

Labels

DOCSStale

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@panbingkun@stefankandic@HyukjinKwon@allisonwang-db