Welcome to SurrealDB! In this guide, you will learn about the various ways you can start using SurrealDB with interactive examples. Before we dive in, let's cover some basics.
Running queries in SurrealDB
Much like any other database, you can communicate with SurrealDB by executing queries.
Queries are written using SurrealQL, SurrealDB's powerful and flexible query language. While SurrealQL takes inspiration from traditional SQL, it is designed to be more expressive and flexible, allowing you to query your data in a variety of ways.
Let's take a look at some of the basic queries you can run in SurrealDB.
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.
One of the many powerful features of SurrealDB is the ability to write subqueries, which in the following example is used 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 includes additional powerful features inspired by 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.
The SELECT statement offers a variety of different features, such as the ability to filter on fields, fetch and resolve record id contents, and the ability to access data directly from Record IDs without the need of JOINs or complex queries.
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.
Congratulations, you're now on your way to database and API simplicity! For the next steps, we will explore the different ways to integrate SurrealDB into your applications.