SHOW statement
Change Feeds allows you to retrieve and sync changes from SurrealDB to external systems and platforms using the SHOW statement.
The SHOW statement can be used to replay changes made to a table.
Requirements
- You must first
DEFINE a changefeed on either a table or a database.
Statement syntax
SurrealQL Syntax
SHOW CHANGES FOR TABLE @tablename
SINCE @timestamp | @versionstamp
[ LIMIT @number ]
Example usage
Basic usage
The following expression shows usage of the SHOW statement.
DEFINE TABLE reading CHANGEFEED 3d;
CREATE reading SET story = "Once upon a time";
CREATE reading SET story = "there was a database";
SHOW CHANGES FOR TABLE reading SINCE d"2023-09-07T01:23:52Z" LIMIT 10;
SHOW CHANGES FOR TABLE reading SINCE 1 LIMIT 10;
Assuming the datetime above matches with the one when the changefeed was established, the response for both queries will be as follows.
Response
[
{
changes: [
{
define_table: {
name: 'reading'
}
}
],
versionstamp: 65536
},
{
changes: [
{
update: {
id: reading:bavjgpnhkgvudfg4mg16,
story: 'Once upon a time'
}
}
],
versionstamp: 131072
},
{
changes: [
{
update: {
id: reading:liq4e7hzjaw7bp5t4pn1,
story: 'there was a database'
}
}
],
versionstamp: 196608
}
]
Note the following when working with the versionstamps of a changefeed:
- Changefeeds defined on tables are implemented via a single
CHANGEFEED on the database level. As such, SHOW CHANGES FOR TABLE sometable will only show versionstamps in sequential order if sometable is the database’s only table. - The
versionstamp output above is due to an extra two bytes needed for more detailed ordering needed in the FoundationDB distributed SurrealDB backend. To turn these versionstamps into a normal sequence of numbers, a right shift of sixteen bits (>> 16) can be used. - A
SINCE <number greater than the current sequential number will return an empty array. SINCE <time> needs to be a datetime after which the CHANGEFEED was defined.
Versionstamps carry the following two guarantees:
- Versionstamps monotonically increase.
- Versionstamp format is universal across various backends.
