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.

Note

Before SurrealDB version 3.0.0-beta, the FULLTEXT ANALYZER clause used the syntax SEARCH ANALYZER.

SurrealQL Syntax

DEFINE [
	NAMESPACE [ OVERWRITE | IF NOT EXISTS ] @name
	| DATABASE [ OVERWRITE | IF NOT EXISTS ] @name
	| USER [ OVERWRITE | IF NOT EXISTS ] @name ON [ ROOT | NAMESPACE | DATABASE ] [ PASSWORD @pass | PASSHASH @hash ] ROLES @roles
	| TABLE [ OVERWRITE | 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 [ OVERWRITE | IF NOT EXISTS ] @name ON [ TABLE ] @table WHEN @expression THEN @expression
	| FIELD [ OVERWRITE | IF NOT EXISTS ] @name ON [ TABLE ] @table
		[ TYPE @type ]
		[ VALUE @expression ]
		[ ASSERT @expression ]
		[ PERMISSIONS [ NONE | FULL
			| FOR select @expression
			| FOR create @expression
			| FOR update @expression
			| FOR delete @expression
		] ]
	| PARAM [ OVERWRITE | IF NOT EXISTS ] $name VALUE @value
	| FUNCTION [ OVERWRITE | IF NOT EXISTS ] fn::@name ( [ ( @argument:@type ... ) ] ) { [@query] [RETURNS @returned] }
	| ANALYZER [ OVERWRITE | IF NOT EXISTS ] @name
		[ TOKENIZERS @tokenizers ]
		[ FILTERS @filters ]
	| INDEX [ OVERWRITE | IF NOT EXISTS ] @name ON [ TABLE ] @table [ FIELDS | COLUMNS ] @fields
		[ UNIQUE | FULLTEXT ANALYZER @analyzer [ BM25 [(@k1, @b)] ] [ HIGHLIGHTS ] ]
	| SEQUENCE [ OVERWRITE | IF NOT EXISTS ] @name
		[ BATCH @batch ]
		[ START @start ]
	| ACCESS [ OVERWRITE | IF NOT EXISTS ] @name ON [ NAMESPACE | DATABASE ]
		TYPE [
			JWT [ ALGORITHM @algorithm KEY @key | URL @url ]
			| RECORD
				[ SIGNUP @expression ]
				[ SIGNIN @expression ]
				[ WITH JWT [ ALGORITHM @algorithm KEY @key | URL @url ] [ WITH ISSUER KEY @key ] ]
		]
		[ DURATION [ FOR TOKEN @duration ] [ FOR SESSION @duration ] ]
    [ 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;

{
    "accesses": {},
    "analyzers": {},
    "functions": {},
    "models": {},
    "params": {},
    "tables": {
        "person": "DEFINE TABLE person TYPE ANY SCHEMAFULL PERMISSIONS NONE"
    },
    "users": {
        "db_user": "DEFINE USER db_user ON DATABASE PASSHASH '$argon2id$v=19$m=19456,t=2,p=1$P5nVYXOMvk6rEz67kjL5Dg$0T/XNmgIaB+lK0IPspg1l8LruzNK96jd/PvktRCB/ww' ROLES OWNER"
    }
}