Version: 1.x

DEFINE statement

The DEFINE statement can be used to specify instructions to the schema such as authentication access and behaviour, global parameters, table configurations, table events, analyzers, and indexes.

SurrealQL Syntax
DEFINE [
	NAMESPACE [ IF NOT EXISTS ] @name
	| DATABASE [ IF NOT EXISTS ] @name
	| USER [ IF NOT EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles
	| TOKEN [ IF NOT EXISTS ] @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value
	| SCOPE [ IF NOT EXISTS ] @name
		[ SESSION @duration ]
		[ SIGNUP @expression ]
		[ SIGNIN @expression ]
	| TABLE [ IF NOT EXISTS ] @name
		[ DROP ]
		[ SCHEMAFULL | SCHEMALESS ]
		[ AS SELECT @projections
			FROM @tables
			[ WHERE @condition ]
			[ GROUP [ BY ] @groups ]
		]
		[ PERMISSIONS [ NONE | FULL
			| FOR select @expression
			| FOR create @expression
			| FOR update @expression
			| FOR delete @expression
		] ]
	| EVENT [ IF NOT EXISTS ] @name ON [ TABLE ] @table WHEN @expression THEN @expression
	| FIELD [ IF NOT EXISTS ] @name ON [ TABLE ] @table
		[ [ FLEXIBLE ] TYPE @type ]
		[ VALUE @expression ]
		[ ASSERT @expression ]
		[ PERMISSIONS [ NONE | FULL
			| FOR select @expression
			| FOR create @expression
			| FOR update @expression
			| FOR delete @expression
		] ]
	| PARAM [ IF NOT EXISTS ] $@name VALUE @value
	| FUNCTION [ IF NOT EXISTS ] fn::@name ( [ ( @argument:@type ... ) ] ) { [@query] [RETURNS @returned] }
	| ANALYZER [ IF NOT EXISTS ] @name
		[ TOKENIZERS @tokenizers ]
		[ FILTERS @filters ]
	| INDEX [ IF NOT EXISTS ] @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields
		[ UNIQUE | SEARCH ANALYZER @analyzer [ BM25 [(@k1, @b)] ] [ HIGHLIGHTS ] ]
	[ COMMENT @string ]
]

The INFO statement can be used to see which definition statements currently exist in a database connection. All DEFINE statements can be followed up with a COMMENT.

An example of defining a field on a table, followed by an INFO command for the same table:

DEFINE FIELD name ON TABLE person TYPE string COMMENT "Todo: add assertion for maximum length";
INFO FOR TABLE person;

{
	events: {},
	fields: {
		name: "DEFINE FIELD name ON person TYPE string COMMENT 'Todo: add assertion for maximum length' PERMISSIONS FULL"
	},
	indexes: {},
	lives: {},
	tables: {}
}

An example of defining a user and a table for a database, followed by an INFO command for the current database:

DEFINE USER db_user ON DATABASE PASSWORD "strongpassword" ROLES OWNER;
DEFINE TABLE person SCHEMAFULL;
INFO FOR DB;

{
	analyzers: {},
	functions: {},
	models: {},
	params: {},
	scopes: {},
	tables: {
		person: 'DEFINE TABLE person TYPE ANY SCHEMAFULL PERMISSIONS NONE'
	},
	tokens: {},
	users: {
		db_user: "DEFINE USER db_user ON DATABASE PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$PexHeFtoFFf+aKUzU2GXXQ$hZdC5HK8xOUyiMyNC2PhXLhE3Vb3rlxg5ykgul3W3UQ' ROLES OWNER"
	}
}