Back to top
  Back to overview

UPDATE statement

The UPDATE statement can be used to update or modify records in the database.

Statement syntax

UPDATE @targets
	[ CONTENT @value
	  | MERGE @value
	  | PATCH @value
	  | SET @field = @value ...
	[ WHERE @condition ]
	[ RETURN [ NONE | BEFORE | AFTER | DIFF | @projections ... ]
	[ TIMEOUT @duration ]

Example usage

The following query shows example usage of this statement.

-- Update all records in a table
UPDATE person SET skills += ['breathing'];

-- Update or create a record with a specific numeric id
UPDATE person:100 SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

-- Update or create a record with a specific string id
UPDATE person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

When specifying fields to update using the SET clause, it is possible to increment and decrement numeric values, and add or remove values from arrays. To increment a numeric value, or to add an item to an array, use the += operator. To decrement a numeric value, or to remove an value from an array, use the -= operator.

-- Update a document and increment a numeric value
UPDATE webpage:home SET click_count += 1;

-- Update a document and remove a tag from an array
UPDATE person:tobie SET interests -= 'Java';

The update statement supports conditional matching of records using a WHERE clause. If the expression in the WHERE clause evaluates to true, then the respective record will be updated.

-- Update all records which match the condition
UPDATE city SET population = 9541000 WHERE name = 'London';

Instead of specifying record data using the SET clause, it is also possible to use the CONTENT keyword to specify the record data using a SurrealQL object.

-- Update all records with the same content
	name: 'Tobie',
	company: 'SurrealDB',
	skills: ['Rust', 'Go', 'JavaScript'],

-- Update a specific record with some content
UPDATE person:tobie CONTENT {
	name: 'Tobie',
	company: 'SurrealDB',
	skills: ['Rust', 'Go', 'JavaScript'],

Instead of specifying the full record data using the SET clause or the CONTENT keyword, it is also possible to merge-update only specific fields by using the MERGE keyword and specifying only the fields which are to be updated.

-- Update certain fields on all records
	settings: {
		marketing: true,

-- Update certain fields on a specific record
UPDATE person:tobie MERGE {
	settings: {
		marketing: true,

By default, the update statement returns the record value once the changes have been made. To change the return value of each record, specify a RETURN clause, specifying either NONE, BEFORE, AFTER, DIFF, or a comma-separated list of specific fields to return.

-- Don't return any result
UPDATE person SET interests += 'reading' RETURN NONE;

-- Return the changeset diff
UPDATE person SET interests += 'reading' RETURN DIFF;

-- Return the record before changes were applied
UPDATE person SET interests += 'reading' RETURN BEFORE;

-- Return the record after changes were applied (the default)
UPDATE person SET interests += 'reading' RETURN AFTER;

-- Return a specific field only from the updated records
UPDATE person:tobie SET interests = ['skiing', 'music'] RETURN name, interests;

When processing a large result set with many interconnected records, it is possible to use the TIMEOUT keywords to specify a timeout duration for the statement. If the statement continues beyond this duration, then the transaction will fail, no records will be updated in the database, and the statement will return an error.

UPDATE person SET important = true WHERE ->knows->person->(knows WHERE influencer = true) TIMEOUT 5s;