Skip to main content

Map

You use maps to store key-value pairs where you have too many different keys to create separate fields. Hamelin's map type matches SQL's design - it's a homogeneous structure where all keys have the same type and all values have the same type.

When to use maps​

You should use maps rarely. Before using a map, consider whether you could:

  • Factor subset key spaces into separate tables
  • Leave the data as a JSON string and parse only commonly needed values into fields

You use maps only when you have a high cardinality key space that can't be handled with these alternatives.

Creating maps​

You construct maps using the map() function, which has two overloaded forms.

Map literals​

You create a map by listing key-value pairs directly:

SET config = map(
  'timeout': 30,
  'retries': 3,
  'debug': false
)

From key and value arrays​

You build a map from separate arrays of keys and values:

SET field_names = ['user_id', 'email', 'created_at']
SET field_values = [12345, '[email protected]', '2024-01-15']
SET user_data = map(field_names, field_values)

Empty maps​

You create an empty map using the function without arguments:

SET empty_config = map()

Type homogeneity​

Maps must be homogeneous - all values must have the same type. This example will generate an error:

// ERROR: mixing integer and string values
SET broken_map = map(
  'count': 42,
  'name': 'example'
)

Accessing map values​

You use bracket notation to retrieve values by key:

FROM events
| SET metadata = map('source': 'api', 'version': 2)
| SELECT event_source = metadata['source']

Map storage​

The underlying engine stores each map as a pair of related columns - one for keys and one for values. Row positions in each column relate the keys to their values.

Performance considerations​

Unlike structs, which add overhead by creating a column per field, maps have minimal impact on table width (only two columns). However, you pay the cost of key values being actual data rather than column names, even though they're dictionary encoded.