docs(subscription): document multi-row cursor fetch and non-blocking short-read behavior

serve/subscription.mdx

@@ -96,13 +96,19 @@ FETCH from cursor function is supported in the PSQL simple query mode and extend
 
 #### Non-blocking data fetch
 
+Use `FETCH NEXT` to retrieve a single row, or `FETCH n` to retrieve up to `n` rows in one call:
+
 ```sql
+-- Fetch one row
 FETCH NEXT FROM cursor_name;
+
+-- Fetch up to n rows at once
+FETCH n FROM cursor_name;
 ```
 
-Fetch the next row from the cursor. If there are no rows available (i.e., the latest data has been reached), an empty result is returned immediately.
+`FETCH NEXT` is equivalent to `FETCH 1`.
 
-To fetch multiple rows, call `FETCH NEXT` repeatedly in a loop.
+Both forms are non-blocking: if fewer than `n` rows are available, only the available rows are returned immediately. If no rows are available, an empty result is returned immediately.
 
 ```sql
 FETCH NEXT FROM cur;
@@ -114,19 +120,35 @@ t1.v1 | t1.v2 | t1.v3 |    t1.op     |  rw_timestamp
 (1 row)
 ```
 
-In the example above, the `op` column in the result indicates the type of change operations. There are four options: `Insert`, `UpdateInsert`, `Delete`,  and `UpdateDelete`. For a single UPDATE statement, the subscription log will contain two separate rows: one with `UpdateInsert` and another with `UpdateDelete`. This is because RisingWave treats an UPDATE as a delete of the old value followed by an insert of the new value. As for `rw_timestamp`, it corresponds to the Unix timestamp in milliseconds when the data was written.
+```sql
+-- Fetch up to 10 rows at once
+FETCH 10 FROM cur;
+
+----RESULT
+ t1.v1 | t1.v2 | t1.v3 |    t1.op     |  rw_timestamp
+-------+-------+-------+--------------+---------------
+     1 |     1 |     1 | UpdateDelete | 1715669376304
+     1 |     1 |    10 | UpdateInsert | 1715669376304
+(2 rows)
+```
+
+In the example above, the `op` column in the result indicates the type of change operations. There are four options: `Insert`, `UpdateInsert`, `Delete`, and `UpdateDelete`. For a single UPDATE statement, the subscription log will contain two separate rows: one with `UpdateInsert` and another with `UpdateDelete`. This is because RisingWave treats an UPDATE as a delete of the old value followed by an insert of the new value. As for `rw_timestamp`, it corresponds to the Unix timestamp in milliseconds when the data was written.
 
 #### Blocking data fetch
 
 ```sql
+-- Block until 1 row arrives or the timeout elapses
 FETCH NEXT FROM cursor_name WITH (timeout = '1s');
+
+-- Block until up to n rows arrive or the timeout elapses
+FETCH n FROM cursor_name WITH (timeout = '1s');
 ```
 
-Fetch up to N rows from the cursor with a specified timeout. The `timeout` value should be a string in the interval format. In this case, the fetch statement will return when either N rows have been fetched or the timeout occurs. If the timeout occurs, whatever has been read up to that point will be returned. Here are two scenarios to trigger the timeout:
+Fetch up to `n` rows from the cursor with a specified timeout. The `timeout` value should be a string in the interval format. The fetch statement returns when either `n` rows have been fetched or the timeout occurs. If the timeout occurs, whatever has been read up to that point will be returned. Here are two scenarios to trigger the timeout:
 
 1. The cursor has reached the latest data and has been waiting too long for new data to arrive.
 
-2. At least N rows are available for the cursor to read, but retrieving all of them takes an extended period.
+2. At least `n` rows are available for the cursor to read, but retrieving all of them takes an extended period.
 
 To avoid polling for new data frequently with the non-blocking `FETCH`, you can set a longer timeout to simulate a scenario where you want the `FETCH` to block until new data arrives.
 
@@ -179,10 +201,25 @@ fetch next from cur;
 (1 row)
 ```
 
-Then we can update table `t1` and fetch again to view the changes:
+Then we can update table `t1` and fetch again to view the changes. Use `FETCH NEXT` to consume one row at a time, or `FETCH n` to retrieve multiple rows in a single call:
 
 ```sql
 update t1 set v3 = 10 where v1 = 1;
+
+-- Fetch both change rows in one call
+FETCH 10 FROM cur;
+
+----RESULT
+ t1.v1 | t1.v2 | t1.v3 |     t1.op     |  rw_timestamp
+-------+-------+-------+---------------+---------------
+     1 |     1 |     1 | UpdateDelete  | 1715669376304
+     1 |     1 |    10 | UpdateInsert  | 1715669376304
+(2 rows)
+```
+
+Alternatively, use `FETCH NEXT` to fetch one row at a time:
+
+```sql
 fetch next from cur;
 
 ----RESULT