> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# Enum

Functions to read the values of a union type or inline enum, find the position of a value, pick the lowest or highest value in declaration order, and cast a value to the type.

_(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](/docs/reference/query-language/language-primitives/data-types/named-types.md) declared with [`DEFINE TYPE`](/docs/reference/query-language/statements/define/type.md) as a union of strings, or an array of strings for the values of an [inline enum](/docs/reference/query-language/language-primitives/data-types/named-types.md#inline-enums), such as `['s', 'm', 'l']` for `enum<'s', 'm', 'l'>`.

<table>
  <thead>
    <tr>
      <th scope="col">Function</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td scope="row" data-label="Function"><a href="#enumcast"><code>enum::cast()</code></a></td>
      <td scope="row" data-label="Description">Casts a value to a union type, failing if the type does not list it.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#enummax"><code>enum::max()</code></a></td>
      <td scope="row" data-label="Description">Returns the value that comes last in the order of a union type.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#enummin"><code>enum::min()</code></a></td>
      <td scope="row" data-label="Description">Returns the value that comes first in the order of a union type.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#enumrank"><code>enum::rank()</code></a></td>
      <td scope="row" data-label="Description">Returns the position of a value in a union type, from zero.</td>
    </tr>
    <tr>
      <td scope="row" data-label="Function"><a href="#enumvalues"><code>enum::values()</code></a></td>
      <td scope="row" data-label="Description">Returns the values of a union type in declaration order.</td>
    </tr>
  </tbody>
</table>

The examples on this page use the following type:

```surql
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.

```surql title="API DEFINITION"
enum::cast($enum: string | array<string>, $value: any) -> string
```

```surql
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`.

```surql title="API DEFINITION"
enum::max($enum: string | array<string>, $values: string | array<option<string>>) -> option<string>
```

```surql
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`.

```surql title="API DEFINITION"
enum::min($enum: string | array<string>, $values: string | array<option<string>>) -> option<string>
```

```surql
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`.

```surql title="API DEFINITION"
enum::rank($enum: string | array<string>, $value: option<string>) -> option<int>
```

```surql
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:

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

```surql title="Output"
['b', 'a']
```

## `enum::values`

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

```surql title="API DEFINITION"
enum::values($enum: string | array<string>) -> array<string>
```

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

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

## See also

* [Named types](/docs/reference/query-language/language-primitives/data-types/named-types.md)
* [`DEFINE TYPE`](/docs/reference/query-language/statements/define/type.md)
* [`ALTER TYPE`](/docs/reference/query-language/statements/alter/type.md)