Getting started

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

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:

user@localhost % surreal version

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

macOS or Linux

user@localhost % surreal start memory -A --auth --user root --pass root

Windows

PS C:\> 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.

Using SurrealQL

Using SurrealQL, you can query data from your SurrealDB database. While this is not a requirement for getting started, it is helpful to familiarise yourself with some commands.

Once you have your database running, head over to Surrealist.app. Before you can start using Surrealist you will have to input the credentials for your session, which include the Endpoint URL, Namespace, Database, Username, and Password. By default these fields are empty and you can set them to the values below. However, these values can be set to your preference.

EndpointURL: 'http://127.0.0.1:8000/'
Namespace: 'test',
Database: 'test',
Username: 'root',
Password: 'root',

Surrealist is a third-party web-based SurrealQL client that allows you to run queries against your SurrealDB, built and maintained by StarlaneStudios!

CREATE

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

CREATE account SET
	name = 'ACME Inc',
	created_at = time::now()
;

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.

CREATE author:john SET
	name.first = 'John',
	name.last = 'Adams',
	name.full = string::join(' ', name.first, name.last),
	age = 29,
	admin = true,
	signup_at = time::now()
;

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.

CREATE article SET
	created_at = time::now(),
	author = author:john,
	title = 'Lorem ipsum dolor',
	text = 'Donec eleifend, nunc vitae commodo accumsan, mauris est fringilla.',
	account = (SELECT VALUE id FROM account WHERE name = 'ACME Inc' LIMIT 1)[0]
;

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 query. 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 = 'David'

you can also update specific fields:

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

DELETE

You can also delete specific records DELETE person:david. You could also delete a record with specific conditions:

DELETE article WHERE author = 'David';

REMOVE

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

REMOVE TABLE person

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.