Namespace

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.

Namespace structure

Namespaces are defined using the DEFINE NAMESPACE statement in SurrealQL. The statement requires a unique name for the namespace and can optionally include a comment for additional context. The following is the syntax for defining a namespace:

SurrealQL Syntax
DEFINE NAMESPACE [ OVERWRITE | IF NOT EXISTS ] @name [ COMMENT @string ]

You can also view the list of namespaces in your SurrealDB instance using the INFO statement. This statement provides information about the accesses, databases, and users present in the current SurrealDB instance.

Using the NAMESPACE or NS keyword.

SurrealQL Syntax
INFO FOR [ NS | NAMESPACE ];

By running the command above, you will get info ONLY about the current namespace in your SurrealDB instance.

{
	databases: {},
	accesses: {},
	users: {}
}

Once a namespace has been defined, the command below you will get a list of all the namespaces in your SurrealDB instance. We are still using the INFO statement, but we are asking for the info for ROOT. The output will include the namespace name and a list of namespace users.

SurrealQL Syntax
INFO FOR ROOT;

{
	namespaces: {},
	users: {}
}

Lets go ahead and list info about the SurrealDB instance and also about the current namspace from the demo dataset.

Let 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.

Requirements

• You must be authenticated as a root or namespace user before you can use the DEFINE NAMESPACE statement.

Learn more

To learn more about namespaces and how to use them in SurrealDB, refer to the SurrealQL documentation.