Subscription is used to pull data change records for a specific table or materialized view (MV).
FROM
clause must specify either a table or a materialized view (mv).
The retention
parameter should be provided as a string in the format of an interval. It represents the duration for which incremental data will be retained. Any incremental data that exceeds the specified retention duration will be automatically deleted and will no longer be accessible.
since_clause
is used to specify the starting point for reading data. By setting this clause, you can control the range of data that is returned, allowing you to retrieve only the incremental data or data starting from a specific time or event.
Below are the available choices for since_clause
. If you don’t specify the since_clause
, the returned data will just include the incremental data after declaration, which equals to the first choice below.
since now()/proctime()
: The returned data will include only the incremental data starting from the time of declaration.since begin()
: The returned data will include the oldest incremental data available, typically starting from the beginning of the subscription’s retention period.since unix_ms
: Starts reading from the first time point greater than or equal to the specified unix_ms
value. It’s important to note that the unix_ms
value should fall within the range of now() - subscription's retention
and now
.FULL
instead of the since_clause
, the subscription cursor starts consuming data from stock.
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.
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
, you can set a longer timeout to simulate a scenario where you want the FETCH
to block until new data arrives.
rw_timestamp
, values are returned in the order the events occurred.rw_timestamp
, the order matches the event sequence if the data belongs to the same primary key in the subscribed materialized view or table.rw_timestamp
but different primary keys, the order may not reflect the exact event sequence.t1
and subscribe this table, then create a cursor for this subscription.
FETCH NEXT FROM cursor_name
statement to fetch data from this cursor:
t1
and fetch again to view the changes:
since_clause
. Let’s use since unix_ms
to rebuild the cursor:
rw_timestamp
) without data loss after a failure recovery. We also guarantee no duplicates in subscriptions, thus ensuring exactly-once delivery.