Skip to main content
Version: 1.x

Getting started

In this guide, we will walk you through installing SurrealDB on your machine, defining your schema, and writing some queries with SurrealQL.

BEFORE YOU START : Make sure you’ve installed SurrealDB — it should only take a second!

Start the database​

First ensure that your database is set up correctly. To do so, run:

surreal version

To start your database, run the start command specific to your machine.

macOS or Linux​

surreal start memory -A --auth --user root --pass root

Windows​

surreal.exe start memory -A --auth --user root --pass root

Here's what each segment of this command does:

  • surreal start: This initiates the process of starting the SurrealDB database server.
  • -A: Enable all capabilities.
  • --auth: Enable authentication for the database.
  • --user root --pass root: These flags set the initial username and password to access the database. Here both are set as root. Once the initial credentials are created, they are persisted in the datastore, which means you don't have to include the command line arguments next time you start SurrealDB. Instead, they should be securely stored in environment variables or some form of secret management system.
  • memory: This argument indicates that the database should be run in memory. Databases run in memory can have quicker data access times because they're not reading and writing from disk, but the data will be lost when the server is restarted.

Running queries in SurrealDB​

SurrealQL is the query language for SurrealDB which can be used to query data from your SurrealDB database. While this is not a requirement for getting started, it is helpful to familiarise yourself with some commands.

There are a few different ways to use SurrealQL, including using the Surrealist or using the SurrealDB CLI.

Once you have your database running, head over to Surrealist. Surrealist offers a simple interface to run SurrealQL queries. You can run queries, view the results, and even save your queries for later use. To start running queries, you can either set up a connection using your database credentials or use a sandbox which uses the default credentials.

For the sake of this guide, we recommend using a sandbox connection. Once you have set up your connection, you can run your queries in the query editor.

CREATE​

The create statement is used to add records to the database.

The account record will be created, and a random ID has been generated for this record.

In SurrealDB, every record can be created and accessed directly by its ID. In the following query, we will create a record, but will use a specific ID.

You can also link records to each other by creating a mutual record, for example, create a blog article record, which links to the author and account tables. In the following example we link to the author record directly by its ID, and we link to the account record with a subquery which searches using the name field.

Let's now create a blog article record, which links to the author and account tables. In the following example we link to the author record directly by its ID, and we link to the account record with a subquery which gives us the ID for ACME Inc.

Querying data with SELECT​

The querying functionality in SurrealDB works similarly to a traditional SQL, but with many of the added benefits of NoSQL query languages. To retrieve data, we will use a SELECT statement. You can query all the articles in your records and this will also return the record links.

SELECT * FROM article;

Also, in SurrealDB we can retrieve data from multiple different tables or records at once. In the example below we'll retrieve data from both the article and the account table in one query.

SELECT * FROM article, account;

Also, instead of pulling data from multiple tables and merging that data together, SurrealDB allows you to traverse related records efficiently without needing to use JOINs. In the following example, we will get all the articles where the author is younger than 30. In order to get the information for the author age for our filter condition we need to fetch the relevant records from the author table.

SELECT * FROM article WHERE author.age < 30 FETCH author, account;

UPDATE​

Similar to UPDATE in SQL you can also update specific IDs, for example say you wanted to update the first name of the author you can do so:

UPDATE author:john SET name.first = 'David', name.full = string::join(' ', name.first, name.last);

The above code will update the firstname to be David and then create a new string for fullname with the updated first and last name.

You can also update specific fields:

UPDATE author:john SET admin = false WHERE name.last = 'Adams';

DELETE​

You can also delete specific records from the recordID DELETE author:john with the DELETE statement or, you could delete a record with specific conditions:

DELETE article WHERE author.name.first = 'David';

REMOVE​

You can also remove a specific table using the REMOVE TABLE:

REMOVE TABLE author
REMOVE TABLE article

Congratulations, you’re now on your way to database and API simplicity! For the next steps, take a look at some of our in-depth guides to see some of the other advanced functionality that you can use in SurrealDB.

Learn more​

By completing this guide you have successfully set up a SurrealDB database and ran some SurrealQL queries. To learn more about SurrealQL, refer to the SurrealQL guides.

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.