Navigation :

enum

enum (extension), keyword

The enum keyword is used to introduce a complex data type from an enumeration of its values.

table enum Countries = "BE", "FR", "UK", "US"

show table "Countries" with
  text(Countries.Value)
  "(\{Countries.Label})"
 
be = enum<<Countries>>("BE")
show scalar "Belgium" c1 with text(be)

enum (comprehension), function

The enum keyword is used to introduce a complex data type from a vector that contains its values.

table T = with 
  [| as Country|]
  [| "BE" |]
  [| "FR" |]
  [| "UK" |]
  [| "US" |]

table enum Countries = T.Country
 
show table "Countries" with
  text(Countries.Value)
  "(\{Countries.Label})"
 
be = enum<<Countries>>("BE")
show scalar "Belgium" c1 with text(be)

Enum semantics

enum values are immutable, case-sensitive, and whitespace-sensitive. They are unordered; use hash() if an ordering is required.

A table enum X = ... declaration creates:

When writing to a schema that declares enum X, the source vector must be of type enum X; convert from text with enum<<X>>.

Table size constraints

table enum accepts the same size qualifiers as other table declarations: min, max, and small. These qualifiers constrain the enum table produced by the statement.

table Empty = extend.range(0)
Empty.Label = text(Empty.N)

table T = extend.range(3)
T.Label = text(T.N)

table enum Optional min 0 = Empty.Label
table enum Checked max 5..10 = T.Label
table enum Small small = "A", "B", "C"

show table "Checked" with Checked.Label

Text erasure

Assigning an enum value to a text vector replaces its type with the enum type.

table enum Countries = "FR", "UK", "DE", "US"

table Factories = with
  [| as Code, as Country |]
  [| 0,      "US"        |]
  [| 1,      "FR"        |]
  [| 2,      "US"        |]

Factories.Country = enum<<Countries>>(Factories.Country)

show table "Factories" with Factories.Code, Factories.Country

Matching and validation

match over an enum is exhaustive unless a .. fallback is provided. Enum labels can be validated with in:

table enum Countries = "BE", "FR", "UK", "US"

table Raw = with
  [| as Label |]
  [| "BE" |]
  [| "fr" |]
  [| " US" |]

Raw.IsValid = Raw.Label in Countries.Label

show table "Countries" with Raw.Label, Raw.IsValid

Enum-typed reads

Enum types can be enforced in read blocks:

table enum Countries = "BE", "FR", "UK", "US"

read "/sample/countries.csv" as C with
  Code : enum Countries
  Name : text

Enums can also be defined from a read block:

read "/sample/countries.csv" as C with
  Code : table enum Countries
  Name : text

show table "Codes" with Countries.Label

Anonymous enums can be requested with enum _ in read blocks and schemas. They create an unnamed enum type from the field values instead of binding the field to a reusable enum table.

read "/sample/countries.ion" as C with
  Country : enum _

C.Label = text(C.Country)

show table "Countries" with
  C.Label

Multiple read blocks that append to the same table and field share the same anonymous enum. Separate enum _ declarations create separate enum types; convert to text before comparing values across them.

Validation is enforced only if the enum-typed column is used downstream.

Script-defined enums can also type a read form field, with an optional default label. See enum form fields and defaults.

Editable-table dropdowns

In an editable table tile, an enum-typed column automatically offers a dropdown of its labels when a cell is edited. This applies to enums whose labels are defined explicitly in the script, with at most 256 distinct values. Enums populated from data or containing more values are displayed as text, without the automatic dropdown.

table enum Status = "Pending", "Approved", "Rejected"

read upload "order-status" as Submitted min 0 with
  Order : text
  Status : enum Status

table Orders = with
  [| as Order |]
  [| "PO-001" |]
  [| "PO-002" |]

Orders.Status = single(Submitted.Status) by Submitted.Order at Orders.Order default enum<<Status>>("Pending")

show table "Order approval" editable:"order-status" { 1..6, 1..6 } with
  Orders.Order { columnReadOnly: true }
  Orders.Status

On the first run, both orders have status Pending. Editing a Status cell offers Pending, Approved, and Rejected; the order identifiers remain read-only. No fieldType or fieldChoices configuration is needed.

The matching editable: and read upload identifiers connect the table to its submitted values. On the next run after submission, the join restores each order’s selected status. min 0 allows the first run without submitted data, and the default supplies Pending for orders without a submitted row.

Enum dimensions and lookups

Enum tables can name their primary dimension:

table enum Countries[country] = "BE", "FR", "UK", "US"
show table "Countries" with country

Lookups over enum tables accept either enum values or text values (auto-converted):

table enum Countries = "FR", "UK", "DE", "US"
Countries.Selected = random.binomial(0.5 into Countries)
show scalar "Is FR selected?" with Countries.Selected["FR"]

Limits and performance

An enum is limited to 100 million distinct values or 1 GB of source text, whichever comes first. Enum vectors are more compact than text vectors and are recommended for low-cardinality text columns once data preparation is complete.

© Lokad 2014 - 2026