Back to top
Documentation SurrealQL Statements CREATE statement

CREATE statement

The CREATE statement can be used to add records to the database, if those records do not already exist.

Statement syntax

CREATE [ ONLY ] @targets
	[ CONTENT @value
	  | SET @field = @value ...
	]
	[ RETURN [ NONE | BEFORE | AFTER | DIFF | @projections ... ]
	[ TIMEOUT @duration ]
	[ PARALLEL ]
;

Example usage

The following query shows example usage of this statement.

-- Create a new record with a random id
CREATE person SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

-- Create a new record with a specific numeric id
CREATE person:100 SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

-- Create a new record with a specific string id
CREATE person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

-- Create just a single record
-- Using the ONLY keyword, just an object for the record in question will be returned.
-- This, instead of an array with a single object.
CREATE ONLY person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

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.

-- Create a new record with a random id
CREATE person CONTENT {
	name: 'Tobie',
	company: 'SurrealDB',
	skills: ['Rust', 'Go', 'JavaScript'],
};

-- Create a new record with a specific id
CREATE person:tobie CONTENT {
	name: 'Tobie',
	company: 'SurrealDB',
	skills: ['Rust', 'Go', 'JavaScript'],
};

By default, the create 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
CREATE person SET age = 46, username = "john-smith" RETURN NONE;

-- Return the changeset diff
CREATE person SET age = 46, username = "john-smith" RETURN DIFF;

-- Return the record before changes were applied
CREATE person SET age = 46, username = "john-smith" RETURN BEFORE;

-- Return the record after changes were applied (the default)
CREATE person SET age = 46, username = "john-smith" RETURN AFTER;

-- Return a specific field only from the updated records
CREATE person SET age = 46, username = "john-smith", interests = ['skiing', 'music'] RETURN interests;