This page walks through the four statements that do most of the work in SurrealQL: CREATE, SELECT, UPDATE and DELETE. Every example runs against a live database in an embedded SurrealDB Studio, so you can edit a query and run it again to see what changes.
SurrealQL's basic shape is largely equivalent to SQL, but includes additional syntax to allow conveniences such as record links, subqueries and nested field access. The examples below introduce each of those in turn.
Creating data with CREATE
Before we can start querying data, we need to create some records. This can be done using the CREATE statement, which is used to add new records to the database.
The following example demonstrates how to create a record in the category table, initialised with a name field and a created_at field. Press the "Run query" button to execute the query and view the response.
After executing this statement, the category record is created in the database, and a randomly generated unique id known as a Record ID is assigned to it. This ID represents the primary key of our record, and can be used to reference the record in future queries.
When creating records, you can also explicitly set the record ID. This can be useful when you are able to use predictable unique record IDs such as company:surrealdb or planet:earth. In the following example, we create a person record with the ID john, and set the first, last, age, admin, and signup_at fields.
SurrealDB also supports subqueries, used in the following example to populate the category field of the article record with the ID of the Technology category.
Querying data with SELECT
After inserting records into your database, you can now use the SELECT statement to retrieve data. While this statement will be familiar to anyone who has used traditional SQL before, SurrealDB's SELECT statement adds features drawn from NoSQL databases.
For example, in addition to selecting records from a single table, you can also select records from multiple tables, or select specific records by their Record ID.
-- Select records from multiple tables SELECT * FROM category, person;
-- Selecting specific records SELECT * FROM person:john; `} />
The SELECT statement can filter on fields, resolve the contents of a record link, and reach data through a Record ID directly, with no JOIN planning or indexes needed.
The following query combines a number of such features:
Filtering: Use the
WHEREclause to only include records where the author's age is less than 30.Fetching: Use the
.*idiom to replace record ids with their actual field values.Specific fields: Only want to retrieve the title and author fields from the article table.
Record links: Structure the field data from the author in a preferred format, including an alias for the field
name.full.
Modifying data with UPDATE
Records can be updated using the UPDATE statement, which allows you to modify the contents of existing records.
Much like the SELECT statement, you can pass both table names and individual record IDs to the UPDATE statement. This allows you to update specific records, or update multiple records at once.
The UPDATE statement offers a variety of features to further filter down records, and apply different update strategies. The following example demonstrates how we can merge new data into records matching a specific condition.
In addition to the UPDATE statement, SurrealDB also offers an UPSERT statement, which has the added functionality of creating a record if it does not already exist. This can be useful when you want to update a record if it exists, or create it if it does not.
Deleting data with DELETE
You can also delete records from your database using the DELETE statement. This statement allows you to remove records from your database, either by specifying the record ID, or by using specific conditions.
The following example demonstrates the use of the RETURN clause, which instructs SurrealDB to return the records before they are deleted.
Where next
Writing SurrealQL for the syntax rules behind these examples.
Statements and values for choosing between
CREATE,INSERT,UPDATE,UPSERTandRELATE.Executing queries for running the same statements from the CLI, an SDK or over HTTP.
Transactions for grouping statements that must succeed or fail together.