docs: rewrite pull query docs page #7532

cprasad1 · 2021-05-17T05:53:17Z

Description

Rewrite pull query docs page https://docs.ksqldb.io/en/latest/developer-guide/ksqldb-reference/select-pull-query/

Testing done

Describe the testing strategy. Unit and integration tests are expected for any behavior changes.

Reviewer checklist

Ensure docs are updated if necessary. (eg. if a user visible feature is being added or changed).
Ensure relevant issues are linked (description should include text like "Fixes #")

docs/developer-guide/ksqldb-reference/select-pull-query.md

JimGalasyn

LGTM, with a few suggestions! If you'd like this to go live now, it needs to be cherry-picked to the 0.17.0-ksqldb branch, and to keep branches in sync, also to the 0.18.x-ksqldb branch. #LifeWithoutPintMerge

docs/developer-guide/ksqldb-reference/select-pull-query.md

vvcephei

Thanks, I agree with @agavra 's feedback. Otherwise, LGTM!

docs/developer-guide/ksqldb-reference/select-pull-query.md

agavra

Left some comments inline - thanks for the PR!

docs/developer-guide/ksqldb-reference/select-pull-query.md

agavra · 2021-05-26T23:55:15Z

docs/developer-guide/ksqldb-reference/select-pull-query.md

 [Push Queries](select-push-query.md).

-Execute a pull query by sending an HTTP request to the ksqlDB REST API, and
+You can execute a pull query by sending an HTTP request to the ksqlDB REST API, and


@AlanConfluent do we need to update this at all after #6813? (shouldn't block this PR)

It streams back a chunked response. Technically, it's a single response, though maybe it's a little misleading, since I think that wording was intended to mean it's returned in one fell swoop (one chunk!). Maybe we want to change the description to either say "Streams back a chunked response as rows are fetched" or just make it a little more vague so that it's a little less tied to an implementation by saying "the API responds with resulting rows".

docs/developer-guide/ksqldb-reference/select-pull-query.md

agavra · 2021-05-26T23:56:38Z

docs/developer-guide/ksqldb-reference/select-pull-query.md

+-   You can issue a pull query against any table that was created by using 
+    a [CREATE TABLE AS SELECT](../../ksqldb-reference/create-table-as-select) 
+    statement.
+-   `SELECT` statements can contain column arithmetic and function calls.


I thought we can express any expression? this implies we can only do arithmetic and function calls

ewmoved the commentary on SELECT. It was a bit confusing and wrong

docs/developer-guide/ksqldb-reference/select-pull-query.md

agavra · 2021-05-27T00:00:00Z

docs/developer-guide/ksqldb-reference/select-pull-query.md

+-   On windowed tables, WINDOWSTART and WINDOWEND can be optionally compared to literals. 
+    For more information on windowed tables, see [Time and Windows in ksqlDB](../../concepts/time-and-windows-in-ksqldb-queries.md).
+
+You can enable table scans to loosen the restrictions on the `WHERE` clause or eliminate 


we might want to say what a "table scan" is (perhaps the note below is a good place for this). @JimGalasyn thoughts?

docs/developer-guide/ksqldb-reference/select-pull-query.md

agavra · 2021-05-27T00:00:57Z

docs/developer-guide/ksqldb-reference/select-pull-query.md

+-   Key column(s) using range comparisons to literals.
+-   Non key columns to be used alone, without key references.
+-   Columns to be compared to other columns.
+-   References to subsets of columns from a multi-column key.


do we also support UDFs and function calls? Might make sense to call out what is not supported as opposed to what is here.

Yeah, we do support UDFs and function calls. Really, anything goes. The below line gives an example of this: (e.g. instr(NAME_COL, 'hello') > 0)

agavra · 2021-05-27T00:02:17Z

docs/developer-guide/ksqldb-reference/select-pull-query.md

-	`CREATE TABLE QUERYABLE_JOIN_TABLE AS SELECT * FROM JOIN_TABLE;` and then issue pull queries against `QUERYABLE_JOIN_TABLE`.
-
+
+Pull queries against a table `INNER_JOIN` that is created by joining multiple tables:


I'm not entirely sure this example is helpful (the windowed one below is helpful because it shows the usage of window bounds on key lookups)

We have stated in our 0.17 blog and 0.17 docs explicitly that Pull queries are not supported on Table-Table joins. This just clarifies to a certain degree that they are now supported.

IMO I think it's sufficiently clarified above when you discuss that any CTAS table can be queried. Not a big deal though, we can keep it or get another opinion on it.

Let's keep it. It is also one of the examples in our 0.18 blog

Co-authored-by: Almog Gavra <[email protected]>

docs/developer-guide/ksqldb-reference/select-pull-query.md

cprasad1 · 2021-05-27T19:58:03Z

master is broken. merging this in as it is just docs

* chore: rewrite pull query docs page * revise some more * incorporate Alan's comment * explicitly call out features and limitations * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * nits Co-authored-by: Chittaranjan Prasad <> Co-authored-by: Almog Gavra <[email protected]>

* chore: fix pull queries in https://docs/concepts/queries.md (#7597) * chore: fix pull queries in docs/concepts/queries.md * nit in language Co-authored-by: Chittaranjan Prasad <> * docs: rewrite pull query docs page (#7532) * chore: rewrite pull query docs page * revise some more * incorporate Alan's comment * explicitly call out features and limitations * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * Update docs/developer-guide/ksqldb-reference/select-pull-query.md Co-authored-by: Almog Gavra <[email protected]> * nits Co-authored-by: Chittaranjan Prasad <> Co-authored-by: Almog Gavra <[email protected]> Co-authored-by: Almog Gavra <[email protected]>

chore: rewrite pull query docs page

98747cd

cprasad1 requested review from JimGalasyn and a team as code owners May 17, 2021 05:53

JimGalasyn reviewed May 17, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

JimGalasyn reviewed May 17, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

JimGalasyn reviewed May 17, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

JimGalasyn reviewed May 17, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

JimGalasyn approved these changes May 17, 2021

View reviewed changes

agavra reviewed May 17, 2021

View reviewed changes

vvcephei reviewed May 19, 2021

View reviewed changes

AlanConfluent reviewed May 26, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

revise some more

02c1540

cprasad1 force-pushed the pull_doc branch from e530bb3 to 02c1540 Compare May 26, 2021 21:22

AlanConfluent approved these changes May 26, 2021

View reviewed changes

AlanConfluent reviewed May 26, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Show resolved Hide resolved

Chittaranjan Prasad added 2 commits May 26, 2021 14:45

incorporate Alan's comment

fb2d635

explicitly call out features and limitations

53a4d3c

cprasad1 changed the title ~~chore: rewrite pull query docs page~~ docs: rewrite pull query docs page May 26, 2021

cprasad1 requested a review from agavra May 26, 2021 23:42

agavra approved these changes May 27, 2021

View reviewed changes

cprasad1 and others added 5 commits May 26, 2021 17:07

Update docs/developer-guide/ksqldb-reference/select-pull-query.md

05fcba4

Co-authored-by: Almog Gavra <[email protected]>

Update docs/developer-guide/ksqldb-reference/select-pull-query.md

34a26f6

Co-authored-by: Almog Gavra <[email protected]>

Update docs/developer-guide/ksqldb-reference/select-pull-query.md

f08da30

Co-authored-by: Almog Gavra <[email protected]>

Update docs/developer-guide/ksqldb-reference/select-pull-query.md

3d55765

Co-authored-by: Almog Gavra <[email protected]>

Update docs/developer-guide/ksqldb-reference/select-pull-query.md

ef84573

Co-authored-by: Almog Gavra <[email protected]>

JimGalasyn reviewed May 27, 2021

View reviewed changes

docs/developer-guide/ksqldb-reference/select-pull-query.md Outdated Show resolved Hide resolved

nits

fc036bf

cprasad1 merged commit ed969c6 into confluentinc:master May 27, 2021

cprasad1 deleted the pull_doc branch May 27, 2021 19:58

This was referenced May 27, 2021

docs: rewrite pull query docs page #7603

Merged

docs: rewrite pull query docs page #7604

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: rewrite pull query docs page #7532

docs: rewrite pull query docs page #7532

cprasad1 commented May 17, 2021 •

edited

Loading

JimGalasyn left a comment

vvcephei left a comment

agavra left a comment

agavra May 26, 2021

AlanConfluent May 27, 2021

agavra May 26, 2021

cprasad1 May 27, 2021

agavra May 27, 2021

agavra May 27, 2021

AlanConfluent May 27, 2021

agavra May 27, 2021

cprasad1 May 27, 2021

agavra May 27, 2021

cprasad1 May 27, 2021

cprasad1 commented May 27, 2021

		`CREATE TABLE QUERYABLE_JOIN_TABLE AS SELECT * FROM JOIN_TABLE;` and then issue pull queries against `QUERYABLE_JOIN_TABLE`.


		Pull queries against a table `INNER_JOIN` that is created by joining multiple tables:

docs: rewrite pull query docs page #7532

docs: rewrite pull query docs page #7532

Conversation

cprasad1 commented May 17, 2021 • edited Loading

Description

Testing done

Reviewer checklist

JimGalasyn left a comment

Choose a reason for hiding this comment

vvcephei left a comment

Choose a reason for hiding this comment

agavra left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cprasad1 commented May 27, 2021

cprasad1 commented May 17, 2021 •

edited

Loading