MAP_FROM_ENTRIES

Build a map from an array of key-value structs.

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

Syntax

MAP_FROM_ENTRIES(entries)

Description

## Overview Constructs a map from an array of key-value structs, where each struct has exactly two fields: the first becomes the key and the second becomes the value. MAP_FROM_ENTRIES is the canonical inverse of MAP_ENTRIES and is the most direct way to turn an ARRAY<STRUCT<K, V>> payload into a map-typed value. Typical uses include rebuilding a map after applying an array-level TRANSFORM over its entries, assembling maps from grouped key-value tables via ARRAY_AGG, and bridging between struct-based and map-based representations. ## Behavior - Returns a MAP<K, V> where K is the type of the struct's first field and V is the type of the second field. - Each struct must have exactly two fields; additional fields raise a type error. - Keys must be non-NULL; a struct with a NULL key field raises a runtime error. - Duplicate keys raise a runtime error rather than silently resolving. - 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 array returns NULL. - Empty input array returns an empty map. - NULL struct element in the input array raises an error (keys cannot be derived). - NULL key inside a struct raises an error; NULL keys are not permitted in maps. - NULL value inside a struct is preserved. ## Compatibility - Matches the array/map SQL convention for MAP_FROM_ENTRIES. MAP_ENTRIES is the inverse decomposition. - To tolerate duplicate keys with last-write-wins semantics, pre-process the entries array to keep only the desired representative per key before calling this function.

Parameters

Name	Type	Description
`entries`		Specifies an array of two-field structs; the first field becomes the map key and the second becomes the value.

Examples

-- Build a map from struct array
SELECT MAP_FROM_ENTRIES(ARRAY[('a', 1), ('b', 2), ('c', 3)]);  -- {a: 1, b: 2, c: 3}

-- Roundtrip: map -> entries -> map
SELECT MAP_FROM_ENTRIES(MAP_ENTRIES(MAP('x', 10, 'y', 20)));  -- {x: 10, y: 20}

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

-- Empty input array returns an empty map
SELECT MAP_FROM_ENTRIES(CAST(ARRAY() AS ARRAY<STRUCT<STRING, INT>>));  -- {}

-- Build a per-session attribute map from an EXPLODE-and-ARRAY_AGG pipeline
SELECT session_id,
       MAP_FROM_ENTRIES(
         ARRAY_AGG(CAST(ROW(attr_name, attr_value) AS STRUCT<STRING, STRING>))
       ) AS attributes
FROM analytics.events.user_sessions_attrs
GROUP BY session_id;

-- NULL input returns NULL
SELECT MAP_FROM_ENTRIES(CAST(NULL AS ARRAY<STRUCT<STRING, INT>>));  -- NULL

Pitfalls

Each struct must have exactly two fields. Extra fields raise a type error rather than being ignored.
Keys must be non-NULL and unique. Sanitize upstream with FILTER and ARRAY_DISTINCT if the entries array may contain duplicates or NULL keys.
NULL input array returns NULL; empty input returns an empty map. Plan for both cases separately when the column may be either.
Iteration order of the resulting map is not preserved. Sort MAP_KEYS after construction if output ordering matters.