Enum

Available since: v4.0.0

These functions work with the values of a union of strings in the order it declares them. The first argument names the list: a string for a named type declared with DEFINE TYPE as a union of strings, or an array of strings for the values of an inline enum, such as ['s', 'm', 'l'] for enum<'s', 'm', 'l'>.

The examples on this page use the following type:

DEFINE TYPE priority AS 'low' | 'medium' | 'high' | 'urgent';

A value that the type does not list makes enum::max(), enum::min() and enum::rank() fail with an error that names the values it accepts. A type that is not a union of strings, such as DEFINE TYPE small AS int, makes every function on this page fail with The type 'small' is not a union of string labels, so it has no order: it is int.

enum::cast

The enum::cast function casts a value to the type and returns it when the type lists it. It is what a cast such as <priority> does. The first argument can also be a type that holds the union type, such as 'array<priority>', to cast to that type.

enum::cast($enum: string | array<string>, $value: any) -> string

enum::cast('priority', 'high');
//- 'high'

enum::cast('priority', 'critical');
//- "Could not cast into `priority`: Expected `priority ('low' | 'medium' | 'high' | 'urgent')` but found `'critical'`"

enum::cast('array<priority>', ['low', 'urgent']);
//- ['low', 'urgent']

enum::max

The enum::max function returns the value that ranks highest in the type. It takes an array of values or a single value. NONE and NULL are skipped, and an empty array returns NONE.

enum::max($enum: string | array<string>, $values: string | array<option<string>>) -> option<string>

enum::max('priority', ['low', 'urgent', 'medium']);
//- 'urgent'

enum::max('priority', ['low', NONE]);
//- 'low'

In a GROUP BY query over a field of a union type, math::max() and array::max() give the same result.

enum::min

The enum::min function returns the value that ranks lowest in the type. It takes an array of values or a single value. NONE and NULL are skipped, and an empty array returns NONE.

enum::min($enum: string | array<string>, $values: string | array<option<string>>) -> option<string>

enum::min('priority', ['urgent', 'medium', 'high']);
//- 'medium'

enum::min('priority', []);
//- NONE

enum::rank

The enum::rank function returns the position of a value in the type, starting from 0. It returns NONE for NONE and NULL.

enum::rank($enum: string | array<string>, $value: option<string>) -> option<int>

enum::rank('priority', 'urgent');
//- 3

enum::rank(['s', 'm', 'l'], 'l');
//- 2

enum::rank('priority', 'nope');
//- "'nope' is not a value of the type 'priority'; its values are 'low', 'medium', 'high', 'urgent'"

SurrealDB uses the rank when it sorts or compares a field of a union type. To order values that are not held in such a field in the order of the type, sort by their rank:

SELECT VALUE name FROM [{ name: 'a', p: 'urgent' }, { name: 'b', p: 'low' }]
	ORDER BY enum::rank('priority', p);

['b', 'a']

enum::values

The enum::values function returns the values of a union type in declaration order.

enum::values($enum: string | array<string>) -> array<string>

enum::values('priority');
//- ['low', 'medium', 'high', 'urgent']

enum::values('missing');
//- "The type 'missing' does not exist"

See also

• •

  Named types

• •

  DEFINE TYPE

• •

  ALTER TYPE