MAP_FROM_ARRAYS

Build a map by pairing elements of a key array and a value array.

Category: collectionReturns: MAP<K, V>Dialect: Standard

Syntax

MAP_FROM_ARRAYS(keys, values)

Description

## Overview Constructs a map by pairing the elements of a key array and a value array at matching positions. MAP_FROM_ARRAYS is the canonical way to zip two parallel arrays into a single map-typed value, useful when upstream producers emit keys and values as separate columns or arrays. Typical uses include assembling a per-row attribute map from parallel key and value arrays, turning the output of GROUP BY plus ARRAY_AGG into a map payload, and bridging between array-based representations and map-based consumers. ## Behavior - Returns a MAP<K, V> whose entries correspond to pairs (keys[i], values[i]) for i from 1 to the common length. - Both input arrays must have equal length; otherwise a runtime error is raised. - Keys must be non-NULL; a NULL element in the key array raises. - Duplicate keys are not permitted and raise a runtime error. - Iteration order of the resulting map is not guaranteed. - Values may be NULL and are stored under the paired key. ## Null and empty handling - NULL input on either array returns NULL. - Empty key and value arrays (both length 0) return an empty map. - NULL keys raise an error; this engine does not support NULL keys in maps. - Duplicate keys raise an error rather than silently resolving. - NULL values are permitted and stored. ## Compatibility - Matches the array/map SQL convention for MAP_FROM_ARRAYS with equal-length inputs and non-NULL, unique keys. - To build a map when duplicate keys must be tolerated (last-write-wins), compose with ARRAYS_ZIP and MAP_FROM_ENTRIES over a deduplicated entry array.

Parameters

Name	Type	Description
`keys`		Specifies the array of keys. Must not contain NULL elements; duplicate keys are not supported.
`values`		Specifies the array of values. Must have the same length as the keys array. NULL values are permitted.

Examples

-- Build a map from parallel arrays
SELECT MAP_FROM_ARRAYS(ARRAY['a', 'b', 'c'], ARRAY[1, 2, 3]);  -- {a: 1, b: 2, c: 3}

-- Integer keys
SELECT MAP_FROM_ARRAYS(ARRAY[1, 2, 3], ARRAY['x', 'y', 'z']);  -- {1: 'x', 2: 'y', 3: 'z'}

-- NULL values are allowed
SELECT MAP_FROM_ARRAYS(ARRAY['a', 'b'], ARRAY[1, CAST(NULL AS INT)]);  -- {a: 1, b: NULL}

-- Build a per-session attribute map from paired columns
SELECT session_id, MAP_FROM_ARRAYS(attr_names, attr_values) AS attributes
FROM analytics.events.user_sessions;

-- NULL input array returns NULL
SELECT MAP_FROM_ARRAYS(CAST(NULL AS ARRAY<STRING>), ARRAY[1, 2, 3]);  -- NULL

-- Single entry
SELECT MAP_FROM_ARRAYS(ARRAY['key'], ARRAY['val']);  -- {key: 'val'}

Pitfalls

Keys must be non-NULL and unique. A NULL or duplicate key raises at runtime; validate input arrays upstream when they originate from untrusted data.
Arrays must be the same length. Unequal lengths raise rather than padding or truncating; use ARRAYS_ZIP if NULL-padding semantics are desired.
NULL input on either array returns NULL for the whole result. Use COALESCE on each input when NULLs should degrade to empty arrays.
Iteration order of the resulting map is not defined. Do not assume positional order from the source arrays carries over.