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

SHOW CHANGES FOR TABLE @tablename
	SINCE @timestamp | @versionstamp
	[ LIMIT @number ]

Example usage

Basic usage

The following expression shows usage of the SHOW statement.

-- Define the change feed and its duration
DEFINE TABLE reading CHANGEFEED 3d;

-- Create some records in the reading table
CREATE reading SET story = "Once upon a time";
CREATE reading SET story = "there was a database";

-- Replay changes to the reading table since a date
SHOW CHANGES FOR TABLE reading SINCE d"2023-09-07T01:23:52Z" LIMIT 10;
-- Replay changes to the reading table since a versionstamp
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.

[
	{
		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.