SHOW statement

The SHOW statement can be used to replay changes made to a table.

Requirements

• You must first DEFINE a Change Feed.

Statement syntax

SurrealQL Syntax
SHOW CHANGES FOR TABLE @tableName [ SINCE "@timestamp" ] [ 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.

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.