Skip to content

Statements

/

DEFINE

DEFINE TYPE

Available since: v4.0.0

The DEFINE TYPE statement gives a type a name in the current database. A field, a function argument or return value, or a cast can then use that name in the same places as a built-in type such as int or string. A write is coerced to the type and checked against its ASSERT clauses. See Named types for how a named type behaves in a query.

  • You must be authenticated as a root owner or editor, namespace owner or editor, or database owner or editor before you can use the DEFINE TYPE statement.

  • You must select your namespace and database before you can use the DEFINE TYPE statement.

SurrealQL Syntax
DEFINE TYPE [ OVERWRITE | IF NOT EXISTS ] @name AS @type
    [ [ CONSTRAINT @name ] ASSERT @expression ] ...
    [ DEFAULT @expression ]
    [ SQL TYPE POSTGRESQL @string ]
    [ COMMENT @string ]
    [ PERMISSIONS [ NONE | FULL | WHERE @condition ] ]

The body after AS is a type, in one of three forms:

BodyExampleA value of the type
A union of stringsAS 'low' | 'medium' | 'high'Is one of the strings, and sorts in the order they are listed
An objectAS { street: string, city: string }Is an object with those fields
Any other typeAS int ASSERT $value > 0Is a value of that type that passes the checks

The body can name another type defined with DEFINE TYPE. It cannot name a type that does not exist yet, and it cannot lead back to the type being defined, either directly or through other types. A type cannot take the name of a built-in type such as string. PERMISSIONS decides whether a record user can read the type, and defaults to FULL. A cast to a type that the session cannot read fails with You don't have permission to read the type 'name', so the body and checks of the type stay hidden.

A union of string literals defines a fixed list of values, from the lowest to the highest. A field of the type accepts only those values, and sorts and compares them in that order.

DEFINE TYPE priority AS 'low' | 'medium' | 'high' | 'urgent' COMMENT 'Ticket priority, lowest first';
DEFINE FIELD priority ON ticket TYPE priority DEFAULT 'medium';

(INFO FOR DB).types;
Output
{
	priority: "DEFINE TYPE priority AS 'low' | 'medium' | 'high' | 'urgent' COMMENT 'Ticket priority, lowest first' PERMISSIONS FULL"
}

A value listed twice is kept once, in its first position:

DEFINE TYPE status AS 'open' | 'closed' | 'open';
(INFO FOR DB).types.status;
Output
"DEFINE TYPE status AS 'open' | 'closed' PERMISSIONS FULL"

ALTER TYPE adds values to a union at any position and renames them. The enum functions read the values of a union in order.

ASSERT takes an expression over $value, which holds the value after it has been coerced to the body. A write fails when a check returns false, and the checks run in the order they are written. CONSTRAINT names the check that follows it, and an error then reports the name instead of the expression.

DEFAULT is the value that a field of the type takes when a record is created without a value for it. An update that leaves the field empty does not apply it. A DEFAULT on the field itself takes precedence over the type's DEFAULT, and a VALUE clause on the field reads the type's DEFAULT as $value.

DEFINE TYPE percent AS int
    CONSTRAINT in_range ASSERT $value >= 0 AND $value <= 100
    DEFAULT 50;

DEFINE TABLE survey SCHEMAFULL;
DEFINE FIELD score ON survey TYPE percent;

CREATE survey:1;
//- [{ id: survey:1, score: 50 }]

CREATE survey:2 SET score = 140;
Error output
"Couldn't coerce value for field `score` of `survey:2`: Expected `percent (constraint in_range failed)` but found `140`"

A type built on another type runs the checks of both, those of the inner type first:

DEFINE TYPE grade AS percent ASSERT $value % 10 = 0;

<grade> 45;
//- "Could not cast into `grade`: Expected `grade (ASSERT $value % 10 = 0 failed)` but found `45`"

<grade> 120;
//- "Could not cast into `grade`: Expected `percent (constraint in_range failed)` but found `120`"

An object body lists the fields of an object, in the same way as an object literal type on a field. A field or a cast of the type checks each object against it, and refuses an object with a missing field or an extra one.

DEFINE TYPE address AS { street: string, city: string, postcode: option<string> };
DEFINE FIELD home ON person TYPE option<address>;

CREATE person:1 SET home = { street: '1 Main St' };
Error output
"Couldn't coerce value for field `home` of `person:1`: Expected `address ({ city: string, postcode: none | string, street: string })` but found `{ street: '1 Main St' }`"

Defining a type that already exists fails. With IF NOT EXISTS, the statement leaves the existing type unchanged and succeeds. With OVERWRITE, it replaces the type.

-- Uses the priority type defined above
DEFINE TYPE priority AS 'low' | 'high';
//- "The type 'priority' already exists"

DEFINE TYPE IF NOT EXISTS priority AS 'low' | 'high';
enum::values('priority');
//- ['low', 'medium', 'high', 'urgent']

OVERWRITE can change the body, the checks, the default, the comment and the permissions of a type that is in use. It checks the values that fields of the type already hold in the same way as a write, and fails if a stored value does not pass the new definition. It does not rewrite stored records.

The values of a union are the exception. OVERWRITE with a different list, or with the same values in another order, fails while a field or a function names the type. To add or rename a value while the type is in use, use ALTER TYPE.

DEFINE TYPE OVERWRITE priority AS 'low' | 'high';
Error output
"Invalid statement: Cannot change the values of the type 'priority': the field 'priority' on the table 'ticket' has a type that names it"

Once no field or function names the type, OVERWRITE can set any list of values.

A new body or check that a stored value does not pass is refused, and the error names the field and the value:

-- Uses the survey table and the percent type defined above
DEFINE TYPE OVERWRITE percent AS int ASSERT $value <= 40;
Error output
"Invalid statement: Cannot change the type 'percent': the field 'score' on the table 'survey' holds a value it does not admit: Expected `percent (ASSERT $value <= 40 failed)` but found `50`"

A type and a field check a change in different ways. A change to a field compares the old definition with the new one, and needs MIGRATE EXISTING ROWS when the new one does not accept everything the old one did, whatever the records hold. A change to a type checks the values that its fields hold, on every table that uses it, including a SCHEMALESS one. DEFINE TYPE has no MIGRATE EXISTING ROWS clause, and OVERWRITE converts nothing, so a value that would only pass after a cast still stops the change:

DEFINE TYPE code AS string;
DEFINE TABLE item SCHEMAFULL;
DEFINE FIELD c ON item TYPE code;
CREATE item:1 SET c = '100';
CREATE item:2 SET c = 'two hundred';

DEFINE TYPE OVERWRITE code AS int;
Error output
"Invalid statement: Cannot change the type 'code': the field 'c' on the table 'item' holds a value it does not admit: Expected `code (int)` but found `'100'`"

A change that every stored value passes, such as string to string | int, is accepted. To convert the values, define a new type and change the field to it with a migration, then remove the old type once nothing names it:

DEFINE TYPE code_int AS int;
ALTER FIELD c ON item TYPE code_int
    MIGRATE EXISTING ROWS AS code_to_int USING <int> $value FALLBACK 0;
REMOVE TYPE code;

SELECT * FROM item;
Output
[
	{ c: 100, id: item:1 },
	{ c: 0, id: item:2 }
]

To rename a value of a union of strings, use ALTER TYPE ... RENAME VALUE, which rewrites the records that hold it.

A type that names a type which does not exist, or that leads back to itself, is refused when it is defined. The same applies to a field or a function that names a missing type.

DEFINE TYPE node AS { next: option<node> };
//- "Invalid statement: The type 'node' cannot be defined: its body leads back to itself through the type 'node'"

DEFINE FIELD score ON survey TYPE missing;
//- "Invalid statement: The field 'score' on the table 'survey' cannot be defined: the type 'missing' it names does not exist"

REMOVE TYPE fails while another definition names the type, such as a field, a function, an event, a view, a permission or another type.

INFO FOR DB lists each type under the types key as its DEFINE TYPE statement. INFO FOR DB STRUCTURE lists each type as an object, with the labels of a union in order, and each check with the name it was given:

-- In a database that has only the percent and priority types
(INFO FOR DB STRUCTURE).types;
Output
[
	{
		asserts: [
			{
				check: '$value >= 0 AND $value <= 100',
				name: 'in_range'
			}
		],
		default: '50',
		kind: 'int',
		name: 'percent',
		permissions: true
	},
	{
		asserts: [],
		comment: 'Ticket priority, lowest first',
		kind: "'low' | 'medium' | 'high' | 'urgent'",
		labels: ['low', 'medium', 'high', 'urgent'],
		name: 'priority',
		permissions: true
	}
]

SQL TYPE POSTGRESQL records the type that a client of the PostgreSQL wire protocol sees for the type. SurrealQL does not read it: a write or a cast checks only the body, the ASSERT clauses and the DEFAULT, and the string is stored as it is written. POSTGRESQL is the only dialect that DEFINE TYPE accepts, and SQL TYPE MYSQL is a parse error. A CREATE DOMAIN or a CREATE TYPE sent over the PostgreSQL protocol defines a type with this clause set. INFO FOR DB STRUCTURE shows the string as sql_type.

DEFINE TYPE price AS decimal ASSERT $value >= 0dec
    SQL TYPE POSTGRESQL 'numeric(10,2)';

Was this page helpful?