Skip to main content

Data Structure Functions

Scalar functions for data structure operations and type information that can be used in any expression context.

typeof(x)​

Returns type information for any expression.

Parameters​

  • x - Expression of any type

Description​

The typeof() function returns a struct containing detailed type information about the input expression. The result includes both the Hamelin type name and the corresponding SQL type name. This function is useful for debugging, type introspection, and understanding how Hamelin maps types to the underlying SQL engine.

map(keys, values)​

Creates a map from separate key and value arrays.

Parameters​

  • keys - Array expression containing map keys
  • values - Array expression containing map values

Description​

The map() function creates a map by pairing elements from the keys array with elements from the values array. Both arrays must have the same length. The nth element from the keys array is paired with the nth element from the values array. If the arrays have different lengths, an error is raised.

map(elements)​

Creates a map from an array of key-value tuples.

Parameters​

  • elements - Array of tuples where each tuple contains a key and value

Description​

The map() function creates a map from an array of key-value pairs represented as tuples. Each tuple in the array must contain exactly two elements: the first element becomes the key, and the second element becomes the value. This format is useful when you have structured key-value data.

map()​

Creates an empty map.

Parameters​

This function takes no parameters.

Description​

The map() function creates an empty map with unknown key and value types. This is useful for initializing map variables or as a starting point for map operations. The specific key and value types are inferred from subsequent usage context.

map(key: value, ...)​

Creates a map from literal key-value pairs.

Parameters​

  • key: value - Variable number of key-value pairs using colon syntax

Description​

The map() function creates a map from explicitly specified key-value pairs using Hamelin's colon syntax. Each key must be unique within the map. All keys must be of the same type, and all values must be of the same type. This provides a concise way to create maps with known literal values.

map_keys(map)​

Extracts all keys from a map as an array.

Parameters​

  • map - Map expression

Description​

The map_keys() function returns an array containing all keys from the input map. The order of keys in the resulting array is not guaranteed. If the map is empty, it returns an empty array. If the map is null, the function returns null.

map_values(map)​

Extracts all values from a map as an array.

Parameters​

  • map - Map expression

Description​

The map_values() function returns an array containing all values from the input map. The order of values in the resulting array corresponds to the order of keys returned by map_keys(), though this order is not guaranteed across calls. If the map is empty, it returns an empty array. If the map is null, the function returns null. This is useful for extracting and processing all values from a map structure.

parse_json(json)​

Parses a JSON string into a variant type.

Parameters​

  • json - String expression containing valid JSON

Description​

The parse_json() function parses a JSON string and returns the result as a variant type that can represent any JSON structure including objects, arrays, strings, numbers, booleans, and null values. If the input string is not valid JSON, an error is raised. The variant type preserves the original JSON structure and allows dynamic access to nested elements.

parse_json(variant)​

Returns a variant value unchanged (identity function for variants).

Parameters​

  • variant - Variant expression

Description​

When parse_json() is called with a variant input, it simply returns the variant unchanged. This overload allows parse_json() to be safely used on values that might already be variants without causing errors or unnecessary conversions.

to_json_string(json)​

Converts a variant to its JSON string representation.

Parameters​

  • json - Variant expression containing JSON data

Description​

The to_json_string() function converts a variant type back into a JSON string. This is the inverse of parse_json(), allowing you to serialize structured data back to JSON format. The resulting string is properly formatted JSON that can be stored, transmitted, or parsed by other systems. Complex nested structures are preserved, and the output follows standard JSON formatting rules.

len(collection)​

Returns the number of elements in a collection.

Parameters​

  • collection - Array or map expression

Description​

The len() function returns the number of elements in arrays or maps as an integer. For arrays, it counts all elements including null values. For maps, it counts the number of key-value pairs. If the collection is null, the function returns null. Empty collections return 0.

filter_null(array)​

Removes null elements from an array.

Parameters​

  • array - Array expression of any element type

Description​

The filter_null() function returns a new array containing only the non-null elements from the input array. The order of remaining elements is preserved. If all elements are null, it returns an empty array. If the input array is null, the function returns null. This function is essential for cleaning data before further processing.