SurrealDB Docs Logo

Enter a search query

SHOW statement

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

Requirements

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.

On this page

© SurrealDB GitHub Discord Community Cloud Features Releases Install