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;