Dictionaries
A dictionary maps values of one type to compact IDs of another - classic interning. Store a currency code, a stock symbol, or a country name once, and every row that references it carries a small integer instead of the repeated string.
Creating a dictionary
The declaration names the value type and the ID type: create dictionary ns::name for value_type as id_type. The ID type bounds how many distinct values the dictionary can hold - a uint2 allows 65,536. Inserting returns the assigned mapping. Run the snippets on this page in order:
Inserting a value that is already interned is not an error - it returns the existing ID, so writers never need to check first:
The mapping is queryable
A dictionary reads like any other source - each row is an ID/value pair:
Dictionary-encoded columns
The real payoff is wiring a dictionary to a table column with with { dictionary: ns::dict }. Writers and readers keep using plain strings; the engine stores and compares the compact IDs underneath:
Note the insert above used "NVDA", which was not in the dictionary. Unknown values are interned automatically on write:
When to use one
Dictionaries pay off when a string column has low cardinality relative to its row count - status names, symbols, categories, country codes. They are the wrong tool for high-cardinality values like emails or UUIDs, where nearly every row would add a dictionary entry. For a fixed, closed set of variants known at design time, consider an enum instead: enums are schema, dictionaries are data.