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:

• a type named enum X
• a table X with one line per enum value
• X.Label (text) and X.Value (enum values)
• enum<<X>>(text) and text(enum X) conversions

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

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

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

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.