INFO statement
The INFO command outputs information about the setup of the SurrealDB system. There are a number of different INFO commands for retrieving the configuration at the different levels of the database.
SurrealQL Syntax
INFO FOR [
ROOT
| NS | NAMESPACE
| DB | DATABASE
| TABLE @table
| USER @user [ON @level]
| INDEX @index ON @table
];
The information returned from an INFO command is an object containing items that almost always correspond to a matching DEFINE statement. For example, the INFO FOR NS command returns the information on the access methods, databases and users of a namespace, which are defined with DEFINE ACCESS, DEFINE DATABASE and DEFINE USER statements.
Before SurrealDB v3.0.0, the output of an INFO FOR was only able to be used as a standalone statement and not in a dynamic context, such as inside other queries or as the value of a parameter.
Example usage
There are a number of different INFO commands for retrieving the configuration at the different levels of the database.
The top-level ROOT command returns information regarding:
- The users and namespaces which exists within the SurrealDB system.
- The memory allocated by SurrealDB itself. Note that this may not match what the operating system reports, as it also includes memory consumed by third-party libraries or pre-allocated memory.
- The level of parallelism: This number indicates the number of available hardware threads.
You must be authenticated as a top-level root user to execute this command.
Examples
INFO FOR ROOT;
Sample output
{
accesses: {},
namespaces: {
ns: 'DEFINE NAMESPACE ns'
},
nodes: {
"2d3b720d-f152-4c0d-8a16-26d1474ed3cd": 'NODE 2d3b720d-f152-4c0d-8a16-26d1474ed3cd SEEN 1745463977888 ACTIVE'
},
system: {
available_parallelism: 14,
cpu_usage: 0.3816290497779846f,
load_average: [
1.2734375f,
1.68310546875f,
1.9189453125f
],
memory_allocated: 13900485,
memory_usage: 136314880,
physical_cores: 14,
threads: 32
},
users: {
root: "DEFINE USER root ON ROOT PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$0RoO7PtdHuGLOz9Pomoucg$T6FYVogdEF8sFse/Su11nKaZb8FjEp3Bb3rD35mI1b8' ROLES OWNER DURATION FOR TOKEN 1h, FOR SESSION NONE"
}
}
The NS or NAMESPACE command returns information regarding the users, databases and access methods under the namespace in use.
You must be authenticated as a top-level root user, or a namespace user to execute this command.
You must have a NAMESPACE selected before running this command.
Examples
INFO FOR NS;
Sample output
{
accesses: {},
databases: {
db: 'DEFINE DATABASE db'
},
users: {
n: "DEFINE USER n ON NAMESPACE PASSHASH '' ROLES VIEWER DURATION FOR TOKEN 1h, FOR SESSION NONE",
username: "DEFINE USER username ON NAMESPACE PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$K9DIBCuzH2IA6w7t3ZVGkQ$KkRODt0cqgUap9OwZCxLJC4ESo6wEToUk55oumhmgA0' ROLES EDITOR DURATION FOR TOKEN 1m, FOR SESSION 12h"
}
}
The DB or DATABASE command returns information regarding the users, tables, params, models, functions, analyzers and access methods under the database in use.
You must be authenticated as a top-level root user, a namespace user, or a database user to execute this command.
You must have a NAMESPACE and a DATABASE selected before running this command.
Examples
INFO FOR DB;
Sample output
{
accesses: {},
analyzers: {},
apis: {},
buckets: {},
configs: {},
functions: {},
models: {},
params: {},
tables: {
person: 'DEFINE TABLE person TYPE ANY SCHEMALESS PERMISSIONS NONE'
},
users: {
db_user: "DEFINE USER db_user ON DATABASE PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$S8WJ88AnJwWah2VjqnmnoA$OJcQs9SHC5R5q3kOimiKsV5fIUpwZiax3RUcW8VQupk' ROLES OWNER DURATION FOR TOKEN 1h, FOR SESSION NONE"
}
}
The TABLE command returns information regarding the events, fields, tables, and live statement configurations on a specific table.
You must be authenticated as a top-level root user, a namespace user, or a database user to execute this command.
You must have a NAMESPACE and a DATABASE selected before running this command.
Examples
INFO FOR TABLE user;
Sample output
{
events: {},
fields: {
name: 'DEFINE FIELD name ON user TYPE string PERMISSIONS FULL'
},
indexes: {},
lives: {},
tables: {}
}
The USER command returns information for a user defined on either the root, namespace, or database level.
You must be authenticated as a user equal to or greater than the level of the user you are attempting to obtain information for to execute this command.
Examples
INFO FOR USER root ON ROOT;
INFO FOR USER ns_user ON NAMESPACE;
INFO FOR USER db_user ON DATABASE;
If a level after ON is not specified, the INFO command will default to the database level. Thus, the following two commands are equivalent.
INFO FOR USER db_user ON DATABASE;
INFO FOR USER db_user;
Sample output
"DEFINE USER db_user ON DATABASE PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$S8WJ88AnJwWah2VjqnmnoA$OJcQs9SHC5R5q3kOimiKsV5fIUpwZiax3RUcW8VQupk' ROLES OWNER DURATION FOR TOKEN 1h, FOR SESSION NONE"
INFO FOR INDEX returns the status for an index: started, initial indexing, update indexing, built, or error.
This command only applies when the CONCURRENTLY clause is used in a DEFINE INDEX command. Without this clause, the following statement will not be executed until the index is fully created, or fails. In this case, the INFO FOR INDEX statement will return an empty object: {}.
CREATE |user:50000| SET name = id.id() RETURN NONE;
DEFINE INDEX unique_name ON TABLE user FIELDS name UNIQUE;
INFO FOR INDEX unique_name ON TABLE user;
However, when the CONCURRENTLY clause is used, the index will build in the background while other statements are permitted to run. In this case, the INFO FOR INDEX statement will provide the current status on the index. The following code sample shows such an example in which an index is defined on a large number of records. A SLEEP statement is run in between each INFO FOR INDEX command to show the progress after each 50 millisecond interval.
CREATE |user:50000| SET name = id.id() RETURN NONE;
DEFINE INDEX unique_name ON TABLE user FIELDS name UNIQUE CONCURRENTLY;
INFO FOR INDEX unique_name ON user;
SLEEP 50ms;
INFO FOR INDEX unique_name ON user;
SLEEP 50ms;
INFO FOR INDEX unique_name ON user;
SLEEP 50ms;
INFO FOR INDEX unique_name ON user;
Possible output
{
building: {
initial: 0,
pending: 0,
status: 'indexing',
updated: 0
}
}
{
building: {
initial: 100,
pending: 20,
status: 'indexing',
updated: 0
}
}
{
building: {
initial: 100,
pending: 4,
status: 'indexing',
updated: 16
}
}
{
building: {
status: 'ready'
}
}
The STRUCTURE clause
This clause was created for internal use and is subject to change without notice.
Adding the STRUCTURE clause changes the structure of the statement from an object that contains objects into an object with fields that each contain an array and often extra info.
DEFINE TABLE user SCHEMAFULL;
DEFINE FIELD name ON user TYPE STRING;
INFO FOR TABLE user;
INFO FOR TABLE user STRUCTURE;
Output
{
events: {},
fields: {
name: 'DEFINE FIELD name ON user TYPE string PERMISSIONS FULL'
},
indexes: {},
lives: {},
tables: {}
}
{
events: [],
fields: [
{
flex: false,
kind: 'string',
name: 'name',
permissions: {
create: true,
delete: true,
select: true,
update: true
},
readonly: false,
what: 'user'
}
],
indexes: [],
lives: [],
tables: []
}
Using the output of INFO
Available since: v3.0.0
The output of an INFO statement, both with and without the STRUCTURE clause, can be used in other operations. As the output of the statement is always a single object, the SurrealQL object functions can also be used on the output for such tasks as schema change tracking.
LET $cat = CREATE ONLY cat RETURN VALUE id;
LET $first_schema = {
revision: rand::uuid(),
schema: INFO FOR DB
};
$first_schema;
CREATE person SET feeds = [$cat];
LET $second_schema = {
revision: rand::uuid(),
schema: INFO FOR DB
};
$second_schema;
$first_schema.diff($second_schema);
Output
{
revision: u'019665cc-f730-75f0-8251-894e11fee7d8',
schema: {
accesses: {},
analyzers: {},
apis: {},
buckets: {},
configs: {},
functions: {},
models: {},
params: {},
tables: {
cat: 'DEFINE TABLE cat TYPE ANY SCHEMALESS PERMISSIONS NONE'
},
users: {}
}
}
{
revision: u'019665cc-f73b-7313-807f-dd22ad1a0685',
schema: {
accesses: {},
analyzers: {},
apis: {},
buckets: {},
configs: {},
functions: {},
models: {},
params: {},
tables: {
cat: 'DEFINE TABLE cat TYPE ANY SCHEMALESS PERMISSIONS NONE',
person: 'DEFINE TABLE person TYPE ANY SCHEMALESS PERMISSIONS NONE'
},
users: {}
}
}
[
{
op: 'replace',
path: '/revision',
value: u'019665cc-f73b-7313-807f-dd22ad1a0685'
},
{
op: 'add',
path: '/schema/tables/person',
value: 'DEFINE TABLE person TYPE ANY SCHEMALESS PERMISSIONS NONE'
}
]
Default namespace and database output
Available since: v3.0.0
A namespace and database with the name of name are generated by default when starting a SurrealDB instance unless the SURREAL_NO_DEFAULTS environment variable is set to false or the --no-defaults flag is used.
The output of the INFO statement in this case includes a comment on how these two resources were defined.
[INFO FOR ROOT.namespaces, INFO FOR NS.databases];
Output
[
{ main: "DEFINE NAMESPACE main COMMENT 'Default namespace generated by SurrealDB'" },
{ main: "DEFINE DATABASE main COMMENT 'Default database generated by SurrealDB'" }
]
