Changefeeds

Changefeeds are how you ask SurrealDB for a history of writes to a table (or database) so you can replay them elsewhere: search indexes, warehouses, cache warmers, or any system that needs to catch up after downtime.

You define how long changes are retained when you set up the feed by adding a duration like 3d or 100h. Changes are then read with the SHOW statement.

What you need first

Before SHOW CHANGES returns anything useful, the table or database must opt in with a CHANGEFEED definition (duration, scope). Changefeeds are usually defined using a DEFINE TABLE statement, but can be defined on the entire database if desired via DEFINE DATABASE.

Replaying from a point in time or a versionstamp

A typical flow is:

1. 1.

   Note when you last processed changes (a datetime) or where you stopped (a versionstamp).

2. 2.

   Ask for everything since that marker, optionally with a limit so you page through large backlogs.

The SHOW statement reference spells out the full syntax. In practice you are choosing: “give me the next batch of mutations after this cursor.”

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

If the datetime is after the changefeed was created and lines up with your retention window, you get a list of entries, each with changes and a versionstamp (where you are in the log). How each mutation is encoded depends on your DEFINE TABLE ... CHANGEFEED options; when differences are stored (INCLUDE ORIGINAL), an update to an existing row carries a reverse diff from the current state to the state immediately before that write. The SHOW reference covers this in full. The following shape is representative:

[
	{
		changes: [
			{
				define_table: {
					changefeed: {
						expiry: 3d,
						original: false
					},
					drop: false,
					id: 0,
					kind: {
						kind: 'ANY'
					},
					name: 'reading',
					permissions: {
						create: false,
						delete: false,
						select: false,
						update: false
					},
					schemafull: false
				}
			}
		],
		versionstamp: 116372747574247424
	},
	{
		changes: [
			{
				update: {
					id: reading:1up24usipwi7wjs4nbgk,
					story: 'Once upon a time'
				}
			}
		],
		versionstamp: 116372747574247425
	},
	{
		changes: [
			{
				update: {
					id: reading:6q3845opi3nikxr7jvgg,
					story: 'there was a database'
				}
			}
		],
		versionstamp: 116372747574312960
	}
]