SurrealDB Docs Logo

Enter a search query

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 --user root --pass root

Windows

surreal.exe start memory -A --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.
  • --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 two main ways to use SurrealQL:

  1. Surrealist: A graphical user interface (GUI) that can be accessed via a web browser or used as a desktop application.
  2. SurrealDB CLI: A command-line interface that allows you to interact with SurrealQL directly from the terminal.

For more information, you can visit Surrealist and the SurrealDB CLI documentation.

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 person and account tables.

In the following example we link to the specific person record directly by its ID, in the article table’s author field, 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 references the person and account tables in it’s author and account fields.

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 person table referenced by the author field.

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 person you can do so:

UPDATE person: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 person:john SET admin = false WHERE name.last = 'Adams';

DELETE

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

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

REMOVE

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

REMOVE TABLE person
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.

© SurrealDB GitHub Discord Community Cloud Features Releases Install