Doc: support subscription cursor to be blocking

[WanYixian]

Description

Divide fetch from cursor to be non-blocking and blocking

Related code PR

risingwavelabs/risingwave#18675

Related doc issue

Resolve #2672

Rendered preview

https://pr-2736.d2fbku9n2b6wde.amplifyapp.com/docs/next/subscription/#fetch-from-cursor

Checklist

• I have checked the doc site preview, and the updated parts look good.
• I have acquired the approval from the owner (and optionally the reviewers) of the code PR and at least one tech writer (emile-00, hengm3467, & WanYixian).

[aws-amplify-us-east-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2736.d2fbku9n2b6wde.amplifyapp.com

[WanYixian]

Hi @hzxa21 and @xxhZs , for timeout not set part below,

My reference is the release note of this code pr

My question is, when timeout is not set, can it just be equivalent to FETCH NEXT/n FROM cursor_name, that is, the non-blocking way of data fetching? Thanks in advance

[hzxa21]

Thanks for raising the question. I think what you have documented is correct but I do feel that it can confuse users with: if timeout not set in case 1, timeout = max; if timeout not set in case 2, timeout = 0.

My suggestion is to clearly document the behavior of blocking fetch and non-block fetch, without mentioning "if timeout not set". I will put an example with my own words and feel free to modify it:

Non-blocking data fetch

...
Fetch at most N rows from the cursor. If there are less than N rows available, return whatever we get immediately without waiting. This also means if there is 0 row available (already reached latest), return immediately with empty result.
...

Blocking data fetch

...
Fetch at most N rows from the cursor with timeout. The fetch statement will be returned when either the N rows has been fetched or the timeout fires. When the timeout fires, whatever has been read so far will be returned. There are two cases when the timeout can be hit:

1. The cursor already reached latest and is waiting for new data to come for too long.
2. There are at least N rows available for cursor to read but reading all of them takes a long time.

You can use a large timeout to mimic the case when you would like the FETCH to block until new data arrives without needing to frequently "poll" subscription for new data with the non-blocking FETCH.
...

[WanYixian]

Closed in risingwavelabs/risingwave-docs-new#23