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.
Requirements
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 TYPEstatement.You must select your namespace and database before you can use the
DEFINE TYPEstatement.
Statement 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:
| Body | Example | A value of the type |
|---|---|---|
| A union of strings | AS 'low' | 'medium' | 'high' | Is one of the strings, and sorts in the order they are listed |
| An object | AS { street: string, city: string } | Is an object with those fields |
| Any other type | AS int ASSERT $value > 0 | Is 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.
Union types
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;{
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;"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.
Checks and defaults
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;"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`"Object types
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' };"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' }`" Using IF NOT EXISTS and OVERWRITE
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';"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;"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`"Changing a type that is in use
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;"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;[
{ 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.
Errors when defining a type
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.
Listing types
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;[
{
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
}
]Declaring a PostgreSQL type
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)';