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.

Note

Before SurrealDB v3.0.0-alpha.2, 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.

System information

Root information

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.

Note

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"
	}
}

Namespace information

The NS or NAMESPACE command returns information regarding the users, databases and access methods under the namespace in use.

Note

You must be authenticated as a top-level root user, or a namespace user to execute this command.

Note

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"
    }
}

Database information

The DB or DATABASE command returns information regarding the users, tables, params, models, functions, analyzers and access methods under the database in use.

Note

You must be authenticated as a top-level root user, a namespace user, or a database user to execute this command.

Note

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"
    }
}

Table information

The TABLE command returns information regarding the events, fields, tables, and live statement configurations on a specific table.

Note

You must be authenticated as a top-level root user, a namespace user, or a database user to execute this command.

Note

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: {}
}

User information

The USER command returns information for a user defined on either the root, namespace, or database level.

Note

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"

Index information

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
-------- Query 1 --------
{ 
    building: {
        initial: 0,
        pending: 0,
        status: 'indexing', 
        updated: 0
    }
}

-------- Query 2 --------
{ 
    building: {
        initial: 100,
        pending: 20,
        status: 'indexing', 
        updated: 0
    }
}

-------- Query 3 --------
{ 
    building: {
        initial: 100,
        pending: 4,
        status: 'indexing', 
        updated: 16
    }
}

-------- Query 4 --------
{
    building: {
        status: 'ready'
    }
}

The STRUCTURE clause

Note

This clause was originally 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
-------- Query --------

{
	events: {},
	fields: {
		name: 'DEFINE FIELD name ON user TYPE string PERMISSIONS FULL'
	},
	indexes: {},
	lives: {},
	tables: {}
}

-------- Query --------

{
	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-alpha.2

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
-------- First schema --------

{
	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: {}
	}
}

-------- Second schema --------

{
	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: {}
	}
}

-------- Diff --------

[
	{
		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'
	}
]