Concepts

This page aims to give details about some of the core concepts of SurrealDB, including the intended usecases, design choices, and overarching features.

Traditional database or backend layer

SurrealDB can be used either as a traditional database platform, with backend languages and frameworks including Golang, Python, Rust, C, Java, .NET, Node.js, and PHP. Alternatively, you can use SurrealDB as a complete backend platform, connecting directly to it from frontend languages and frameworks including JavaScript, WebAssembly, React.js, Next.js, and Ember.js. SurrealDB provides fine-grained table-, record-, and field-level permissions that support secure access in both backend and frontend architectures.

Relational, document, or graph

SurrealDB is, at its core, a document database. Each record is stored on an underlying key-value store storage engine, with the ability to store arbitrary arrays, objects, and many other types of data. However, SurrealDB isn’t just a document database. Because of the way that SurrealDB handles Record IDs and the fetching of individual records from the underlying key-value storage engine, it can be used to store time-series ordered data, and highly-connected graph data. With its SQL-like query language named SurrealQL, it is easy to create, update, and read data from across the database.

For more on the various data models available in SurrealDB, see the Data Models section.

Single-node or distributed

SurrealDB is designed to be run in many different ways and environments. Due to the separation of the storage and compute layers, SurrealDB can be run as an embedded database, as a vertically-scalable, single-node database server, or as a horizontally-scalable, multi-node, distributed cluster. In embedded mode, SurrealDB can be run with an in-memory storage engine, in a web browser it can persist data using IndexedDB, or it can persist data using the file-based RocksDB or SurrealKV storage engines. As a database server, SurrealDB stores data in memory by default with RocksDB or SurrealKV as options for persistent storage, or TiKV for distributed deployments.

System structure

SurrealDB works similarly to other traditional relational databases and document databases, with a few slight differences. SurrealDB is designed and developed to be a multi-tenant database platform with a high-level namespace layer designed as a separation for each organisations, department, or development team. There is no limit to the number of namespaces on SurrealDB. Below this, the databases layer is similar to databases in other database management systems. There is no limit to the number of databases on each namespace. Within each database, data can be stored within table definitions, otherwise known as collections in other database management systems. In SurrealDB each row or document is called a record and columns are called fields. Each of these resources has its own define statement:

• namespace
• databases
• table
• fields

The records of a database can be created, read, updated, and deleted. Many other statements exist to work with records, such as:

• UPSERT to update a record if it exists or create a new one if it does not.
• RELATE to link one record to another via another table called a graph edge.

Multiple access methods can be defined on namespace and database. The record access method allows for custom authentication across tables, records, and fields.

Namespaces and databases

A namespace in SurrealDB acts as a higher-level container that can hold multiple databases. It is primarily used for organizing and isolating databases within the same SurrealDB instance. This is particularly useful in multi-tenant environments where different applications or groups might need to operate independently within the same server or cluster.

Namespaces help in managing permissions and access at a broader level than individual databases. There is no limit to the number of namespaces on SurrealDB and each namespace can have its own set of databases, tables, and records.

A database within SurrealDB is contained within a namespace and is the primary unit where data is stored. Databases hold the actual data tables, indexes, and other data structures. Each database can have its own schema, settings, and permissions. The database is where you perform most of the data operations like CRUD (Create, Read, Update, Delete) operations, queries, and transactions.

Namespaces and databases are defined using the DEFINE NAMESPACE and DEFINE DATABASE statements in SurrealQL. These statements requires a unique name and can optionally include a comment for additional context. The USE statement allows you to move from one namespace or database to another.

DEFINE NAMESPACE dev_namespace COMMENT "Internal use only: do not use in prod";
USE NAMESPACE dev_namespace;
// Now inside 'dev_namespace', define a database within it
DEFINE DATABASE dev_db_1 COMMENT "First of many dev databases";

You can view the list of resources in your SurrealDB instance using the INFO statement.

• INFO FOR ROOT: Information on namespaces as well as system info: memory allocated, physical cores, other users, etc.
• INFO FOR NAMESPACE: Information on a namespace’s databases, users, and access methods.
• INFO FOR DATABASE: Information an a database’s tables, users, accesses, etc.

Other INFO statements exist to see the status of tables, users, and indexes.

An example of output for the INFO FOR ROOT statement is as follows.

[
	{
		accesses: {},
		namespaces: {},
		nodes: {
			"0e87c953-68d7-40e1-9090-3dfc404af25e": 'NODE 0e87c953-68d7-40e1-9090-3dfc404af25e SEEN 1742869518357 ACTIVE'
		},
		system: {
			available_parallelism: 14,
			cpu_usage: 4.321133613586426f,
			load_average: [
				2.2265625f,
				2.2138671875f,
				2.044921875f
			],
			memory_allocated: 13428527,
			memory_usage: 154812416,
			physical_cores: 14,
			threads: 32
		},
		users: {
			root: "DEFINE USER root ON ROOT PASSHASH '...' ROLES OWNER DURATION FOR TOKEN 1h, FOR SESSION NONE"
		}
	}
];

Trying out a query or two

Let’s go ahead and list info about the SurrealDB instance and also about the current namespace from the demo dataset.

Let’s go ahead and create our own namespace called acme using the DEFINE NAMESPACE and list the namespaces in the SurrealDB instance.

Now that we have the acme namespace in the SurrealDB instance we can now switch to use that namespace using the USE.

Since we just created the new acme namespace, it is empty and does not have any databases, tokens, or users. You can now create databases, tokens, and users within the acme namespace.