Version: 1.x

`CREATE` statement

The CREATE statement can be used to add a record to the database. If the record already exists, the statement will give an error.

Note: This statement can not be used to create graph relationships. For that, use the RELATE statement.

Statement syntax

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

Creating a Table Record

When using the create statement the first word after CREATE is the table name. You also specify a record identifier using the : followed by a value. Ex. CREATE Table:this. The two together form the full record ID which can be used to query the created data or by using the SELECT statement. See the record ID page to learn more about what counts as a valid record identifier. If no record identifier is specified, a random identifier will be generated.

Note: You can also assign the recordID to be randomly generated

The query below will create a new person table and also create a new record with a random ID.

-- Create a new table
CREATE person

Response
[
    {
        "id": "person:2vvgzt6m24s952yiy7x8"
    }
]

Alternatively, you can specify the record identifier of the record you want to create.

-- Create a new record with a specific numeric id
CREATE person:100

The above will create a new record with the ID person:100.

Response
[
	{
		"id": "person:100"
	}
]

It is also possible to specify the ID of the record you want to create using a string or any of the supported formats for record IDs.

Adding Record Data

When creating a record, you can specify the record data using the SET clause, or the CONTENT clause. The SET clause is used to specify the record data using a list of key-value pairs, while the CONTENT clause is used to specify the record data using a SurrealQL object. The CONTENT clause is useful when the record data is already in the form of a SurrealQL or JSON object.

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

The above will create a new record with the ID person:100 and the specified data.

Response
[
	{
		"id": "person:100",
		"name": "Tobie",
		"company": "SurrealDB",
		"skills": ["Rust", "Go", "JavaScript"]
	}
]

Alternatively, you can specify the record data using the CONTENT keyword.

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

Options and clauses

Creating multiple records

Multiple records or even multiple record types can be created by separating record names by commas.

--Note: meta::tb(id) returns just the table name portion of a record ID
CREATE townsperson, cat, dog SET
    created_at = time::now(),
    name = "Just a " + meta::tb(id);

Output
[
    {
        "created_at": "2024-03-19T03:12:05.079Z",
        "id": "townsperson:p37ha2lngckp3v8tvf2j",
        "name": "Just a townsperson"
    },
    {
        "created_at": "2024-03-19T03:12:05.080Z",
        "id": "cat:p1pwbjaq96nhhnuohjtc",
        "name": "Just a cat"
    },
    {
        "created_at": "2024-03-19T03:12:05.080Z",
        "id": "dog:01vcxgdpuctdk354hzkp",
        "name": "Just a dog"
    }
]

ONLY

Using the ONLY clause after CREATE will return just the record object instead of the default, which returns the object inside of an array.

-- Create just a single record
CREATE ONLY person:tobie SET name = 'Tobie', company = 'SurrealDB', skills = ['Rust', 'Go', 'JavaScript'];

Return Values

By default, the create statement returns the record once the changes have been made. To change what is returned, we can use the RETURN clause, specifying either NONE, BEFORE, AFTER, DIFF, or a comma-separated list of specific fields to return.

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) if any.
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;

Timeout

The TIMEOUT clause can be used to specify the maximum time the statement should take to execute. This is useful when you want more control. Such as controlling compute costs or making sure queries succeed or fail within tight latency boundaries to not have a big query queue forming.

The value for TIMEOUT is specified in Second or milliseconds.

CREATE person:25 SET age = 46, username = "john-smith" TIMEOUT 1000ms;

Parallel

The PARALLEL keyword can be used to specify that the statement should be executed in parallel. Similar to the TIMEOUT clause this is useful for more control over how your queries should behave, if that is needed.

CREATE person:26, CREATE person:27 PARALLEL;

Learn more

To learn more about SurrealDB, check out the following resources:

CREATE statement

Statement syntax​

Creating a Table Record​

Adding Record Data​

Options and clauses​

Creating multiple records​

ONLY​

Return Values​

Timeout​

Parallel​

Learn more​