[FLINK-22159][FLINK-22302][docs][table] Restructure SQL "Queries" pages and add docs for the new window TVF based operations #15642

wuchong · 2021-04-16T07:49:46Z

What is the purpose of the change

This add documentations for new introduced window TVF based operations and also restructure "Queries" page.

Currently, the "Queries" page has been very large and it's getting longger when we supporting more features. We already have separate pages for Joins and CEP. I would propose to separate "Queries" into one page per operation. This way we can easily add more detailed informations for the operations and more examples.

Brief change log

The "Queires" page is restructured into following pages:

Queries
- Overview
- Hint (moved from "dev/table/sql/hints")
- WITH clause (new page)
- SELECT & WHERE (refactored)
- SELECT DISTINCT (new page)
- Windowing TVF (new page)
- Window Aggregation (refactored)
- Group Aggregation (refactored)
- Over Aggregation (refactored)
- Joins (moved from "dev/table/concepts/joins")
- Set Operations (refactored)
- ORDER BY clause 
- LIMIT clause
- Top-N
- Window Top-N (new page)
- Deduplication
- Pattern Recognition (moved from "dev/table/concepts/match_recognize")

I also refer some contents from https://docs.ververica.com/user_guide/sql_development/queries.html

Verifying this change

This change is a trivial rework / code cleanup without any test coverage.

Does this pull request potentially affect one of the following parts:

Dependencies (does it add or upgrade a dependency): (yes / no)
The public API, i.e., is any changed class annotated with @Public(Evolving): (yes / no)
The serializers: (yes / no / don't know)
The runtime per-record code paths (performance sensitive): (yes / no / don't know)
Anything that affects deployment or recovery: JobManager (and its components), Checkpointing, Yarn/Mesos, ZooKeeper: (yes / no / don't know)
The S3 file system connector: (yes / no / don't know)

Documentation

Does this pull request introduce a new feature? (yes / no)
If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented)

…to one page per operation

…ased operations

wuchong · 2021-04-16T07:51:17Z

@leonardBang could you help to review this?

cc @twalthr @sjwiesman , would be great if you can have a look too.

flinkbot · 2021-04-16T07:54:54Z

Thanks a lot for your contribution to the Apache Flink project. I'm the @flinkbot. I help the community
to review your pull request. We will use this comment to track the progress of the review.

Automated Checks

Last check on commit 2870d23 (Sat Aug 28 11:16:36 UTC 2021)

✅no warnings

_{Mention the bot in a comment to re-run the automated checks.}

Review Progress

❓ 1. The [description] looks good.
❓ 2. There is [consensus] that the contribution should go into to Flink.
❓ 3. Needs [attention] from.
❓ 4. The change fits into the overall [architecture].
❓ 5. Overall code [quality] is good.

Please see the Pull Request Review Guide for a full explanation of the review process.

Details

The Bot is tracking the review progress through labels. Labels are applied according to the order of the review items. For consensus, approval by a Flink committer of PMC member is required

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot approve description to approve one or more aspects (aspects: description, consensus, architecture and quality)
@flinkbot approve all to approve all aspects
@flinkbot approve-until architecture to approve everything until architecture
@flinkbot attention @username1 [@username2 ..] to require somebody's attention
@flinkbot disapprove architecture to remove an approval you gave earlier

flinkbot · 2021-04-16T08:19:02Z

CI report:

2870d23 Azure: SUCCESS

Bot commands

The @flinkbot bot supports the following commands:

@flinkbot run travis re-run the last Travis build
@flinkbot run azure re-run the last Azure build

leonardBang

Thanks @wuchong for the great work, I left some comments about TVF pages

leonardBang · 2021-04-20T03:27:36Z

docs/content.zh/docs/dev/table/sql/queries/window-tvf.md

+> SELECT * FROM TABLE(
+   TUMBLE(TABLE Bid, DESCRIPTOR(bidtime), INTERVAL '10' MINUTES));
+-- or with the named params
+-- note: the DATA param must be the first
+> SELECT * FROM TABLE(
+   TUMBLE(
+     DATA => TABLE Bid,
+     TIMECOL => DESCRIPTOR(bidtime),
+     SIZE => INTERVAL '10' MINUTES));


Please add note that Note: Currently Flink doesn't support individual window table-valued function, window table-valued function should use with aggregate operation, here we just for explanation the data produced by table-valued function

leonardBang · 2021-04-20T05:18:41Z

docs/content.zh/docs/dev/table/sql/queries/window-tvf.md

+--+---------+-------+------+--------------+------------+--------------+
+
+-- apply aggregation on the tumbling windowed table
+> SELECT window_start, window_end, SUM(price)


nit： we can use TIMESTAMP for bidtime and DECIMAL for price so that user can reproduce this case easily

wuchong · 2021-04-20T07:50:49Z

Thanks @leonardBang for the reviewing, I have addressed your comments.

sjwiesman

Thank you for picking this up @wuchong , I have reviewed the English pages of this PR

docs/content/docs/dev/table/sql/queries/deduplication.md

docs/content/docs/dev/table/sql/queries/group-agg.md

docs/content/docs/dev/table/sql/queries/window-agg.md

docs/content/docs/dev/table/sql/queries/window-tvf.md

docs/content/docs/dev/table/tuning.md

Co-authored-by: Seth Wiesman <sjwiesman@gmail.com>

wuchong · 2021-04-20T14:24:51Z

Thanks @sjwiesman for polishing the docs, it looks much better now! I also applied the changes to Chinese docs.

sjwiesman

LGTM

…ased operations This closes #15642

This closes #15642

…to one page per operation This closes #15642

…ased operations This closes #15642

This closes #15642

…to one page per operation This closes apache#15642

…ased operations This closes apache#15642

This closes apache#15642

wuchong added 3 commits April 16, 2021 15:41

[hotfix][docs] Add SQL CLI examples in Table API "Configuration" page

9b6b4bd

[FLINK-22302][docs][table] Restructure SQL "Queries" documentation in…

1f3f219

…to one page per operation

[FLINK-22159][docs][table] Add documentation for the new window TVF b…

b87e9c2

…ased operations

rmetzger added the review=description? label Apr 16, 2021

rmetzger added component=Documentation component=TableSQL/API labels Apr 16, 2021

wuchong added 2 commits April 16, 2021 16:34

[hotfix][docs][table] Update "Queries" Chinese documentations

c8d627b

fix page weight

8d9a838

sjwiesman self-requested a review April 16, 2021 13:17

wuchong added 2 commits April 16, 2021 21:33

update tuning

aee462a

update zh tuning

e351680

leonardBang reviewed Apr 20, 2021

View reviewed changes

wuchong added 2 commits April 20, 2021 15:48

address Leonard's review comments

8416443

minor improvement in set operation page

61e289e

sjwiesman reviewed Apr 20, 2021

View reviewed changes

wuchong and others added 3 commits April 20, 2021 22:05

Apply suggestions from code review

aec2dfd

Co-authored-by: Seth Wiesman <sjwiesman@gmail.com>

Apply suggestions from code review

65746fd

Co-authored-by: Seth Wiesman <sjwiesman@gmail.com>

apply changes to Chinese docs

2870d23

sjwiesman approved these changes Apr 20, 2021

View reviewed changes

wuchong closed this in 9ba915a Apr 21, 2021

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22159][docs][table] Add documentation for the new window TVF b…

5a7853a

…ased operations This closes #15642

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22302][docs][table] Update "Queries" Chinese documentations

a49d722

This closes #15642

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22302][docs][table] Improvements content based on reviews

8b732a3

This closes #15642

wuchong deleted the docs-window-tvf branch April 21, 2021 03:51

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22302][docs][table] Restructure SQL "Queries" documentation in…

67cf79e

…to one page per operation This closes #15642

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22159][docs][table] Add documentation for the new window TVF b…

54c2500

…ased operations This closes #15642

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22302][docs][table] Update "Queries" Chinese documentations

e34d3e3

This closes #15642

wuchong added a commit that referenced this pull request Apr 21, 2021

[FLINK-22302][docs][table] Improvements content based on reviews

e8d1b57

This closes #15642

xinggit pushed a commit to xinggit/flink that referenced this pull request Apr 22, 2021

[FLINK-22302][docs][table] Restructure SQL "Queries" documentation in…

3e5c3d2

…to one page per operation This closes apache#15642

xinggit pushed a commit to xinggit/flink that referenced this pull request Apr 22, 2021

[FLINK-22159][docs][table] Add documentation for the new window TVF b…

30062ca

…ased operations This closes apache#15642

xinggit pushed a commit to xinggit/flink that referenced this pull request Apr 22, 2021

[FLINK-22302][docs][table] Update "Queries" Chinese documentations

ac8486f

This closes apache#15642

xinggit pushed a commit to xinggit/flink that referenced this pull request Apr 22, 2021

[FLINK-22302][docs][table] Improvements content based on reviews

6dcdab1

This closes apache#15642

[FLINK-22159][FLINK-22302][docs][table] Restructure SQL "Queries" pages and add docs for the new window TVF based operations #15642

[FLINK-22159][FLINK-22302][docs][table] Restructure SQL "Queries" pages and add docs for the new window TVF based operations #15642

Uh oh!

Conversation

wuchong commented Apr 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What is the purpose of the change

Brief change log

Verifying this change

Does this pull request potentially affect one of the following parts:

Documentation

Uh oh!

wuchong commented Apr 16, 2021

Uh oh!

flinkbot commented Apr 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Automated Checks

Review Progress

Uh oh!

flinkbot commented Apr 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CI report:

Uh oh!

leonardBang left a comment

Choose a reason for hiding this comment

Uh oh!

leonardBang Apr 20, 2021

Choose a reason for hiding this comment

Uh oh!

leonardBang Apr 20, 2021

Choose a reason for hiding this comment

Uh oh!

wuchong commented Apr 20, 2021

Uh oh!

sjwiesman left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wuchong commented Apr 20, 2021

Uh oh!

sjwiesman left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

wuchong commented Apr 16, 2021 •

edited

Loading

flinkbot commented Apr 16, 2021 •

edited

Loading

flinkbot commented Apr 16, 2021 •

edited

Loading