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.
SurrealDB is a multi-model database that allows you to store data in a variety of ways.
When we say SurrealDB is a multi-model database, we mean that SurrealDB can store and query data using a variety of different paradigms. For example, you can use SurrealDB as a Graph, Document, Time-Series, or Vector database, all designed to be queried with our SurrealQL query language. This allows you to design a database that fits the shape and requirements of your data.
In addition to giving you complete flexibility over your data model, SurrealDB can also be integrated in a variety of ways. You can use SurrealDB as a traditional backend database, connect to it directly as a BaaS (Backend-as-a-Service), embed it directly into your applications, and much more!
The advantage of using SurrealDB lies in its ability to adapt to your needs, rather than forcing you to adopt a rigid data structure or spreading your data across different databases, which can lead to data inconsistency and duplication.
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.
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, initialized 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 want to reference a specific record in your queries. In the following example, we create a person record with the ID john, and set the name, 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.
After inserting records into your database, you can now use the SELECT statement to retrieve data. This statement will be familiar to anyone who has used traditional SQL before, however 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 multiple of such features:
WHERE clause to only include records where the author’s age is less than 30.FETCH clause to replace record ids with their actual record values.author.name.full to directly access the full name of the author.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.
Finally, you can 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.
SurrealDB is built to be flexibile and versatile. This means it can be integrated into your applications in a variety of ways, depending on your needs and requirements. Let’s explore some of the different ways you can start using SurrealDB.
Surreal Cloud is the easiest way to get up and running with SurrealDB. It provides a fully managed solution that takes the hassle out of infrastructure operations, allowing you to focus on building your application.
To get started with Surreal Cloud, you can sign up for a free account and create a free instance. Once you have created your account, you can effortlessly provision your first Cloud Instance and integrate it into your application.
Get started with Surreal Cloud
SurrealDB offers SDKs for a variety of programming languages, allowing you to interact with SurrealDB from your application. Depending on the language you are using, you can also use SDKs to embed SurrealDB directly in your application, either running as an in-memory database, or persisting data to disk.
Each SDK has its own set of methods and features, so be sure to refer to the documentation for the language you are using. Follow the links below to learn more about integrating SurrealDB in your desired programming language:
One of the most popular ways to get started with SurrealDB is to install and run it as a standalone database service, allowing any number of clients to connect to it and interact with the data. When starting SurrealDB through the command line, you can fully customize the database to your needs.
Install SurrealDB
After you have installed SurrealDB, you can start the database using the surreal start command provided by the SurrealDB CLI.
When you start the database, you must specify which storage engine to use. This can be done by providing the engine as as the connection URL protocol. The following examples demonstrate how to start SurrealDB using different storage engines.
surreal start memory
surreal start -u root -p root rocksdb://mydb
surreal start tikv://127.0.0.1:2379
NoteThe
-uand-pflags are used to set the username and password for the database. The username and password are set torootby default if not specified.
By completing this guide you have successfully learnt the basics of SurrealQL and started your journey integrating SurrealDB into your application. To continue learning about SurrealDB, visit SurrealDB University, and for more examples and guides, refer to the SurrealQL documentation.
Explore SurrealDB University