37.MAP 相关函数深度解析:MAP_KEYS / MAP_VALUES / MAP_CONTAINS_KEY

隐于花海，等待花开

330人浏览 · 2026-04-30 10:09:22

隐于花海，等待花开 · 2026-04-30 10:09:22 发布

Hive MAP 相关函数深度解析:MAP_KEYS / MAP_VALUES / MAP_CONTAINS_KEY

函数概述
核心前置概念:Map 数据类型
MAP_KEYS 函数详解
MAP_VALUES 函数详解
MAP_CONTAINS_KEY 函数详解
实战场景:三者组合的经典用法
NULL 值与边界情况处理
跨引擎行为差异与迁移指南
- 8.1 Hive vs Spark SQL vs Presto/Trino
- 8.2 迁移检查清单
常见问题与避坑指南
总结

1. 函数概述

MAP_KEYS、MAP_VALUES 和 MAP_CONTAINS_KEY 是 Hive SQL 中专门用于操作 MAP（映射）数据类型的三个核心函数。它们分别负责提取 Map 中的所有键、所有值，以及判断指定键是否存在于 Map 中，构成了处理键值对数据的完整工具链。

函数名称：MAP_KEYS（提取键数组）、MAP_VALUES（提取值数组）、MAP_CONTAINS_KEY（判断键是否存在）
函数类型：集合函数（Collection Functions）
主要功能：
- MAP_KEYS：返回 Map 中所有键组成的数组（ARRAY）
- MAP_VALUES：返回 Map 中所有值组成的数组（ARRAY）
- MAP_CONTAINS_KEY：判断指定键是否存在于 Map 中，返回布尔值
应用场景：用户画像标签管理、动态字段过滤、键值对数据清洗、判断是否存在特定配置项、配合聚合函数统计键值分布

关键认知：MAP_KEYS 和 MAP_VALUES 返回的数组都是无序的。如果需要有序的结果，必须结合 SORT_ARRAY 函数使用。此外，这两个函数并不保证键数组和值数组的元素顺序相对应，不要依赖隐式的位置对应关系。

2. 核心前置概念：Map 数据类型

在深入理解这三个函数之前，必须先掌握 Hive 中 Map 类型的基础知识。

2.1 表结构定义

Map 类型在建表时通过 MAP<key_type, value_type> 语法定义，用于存储键值对集合。

CREATE TABLE user_attributes (
    user_id INT COMMENT '用户ID',
    attributes MAP<STRING, STRING> COMMENT '用户属性映射',
    scores MAP<STRING, INT> COMMENT '各科目成绩'
);

key_type：所有键的数据类型必须一致
value_type：所有值的数据类型必须一致
键和值的类型可以不同，例如键为 STRING，值为 INT

2.2 构造 Map 对象

通过 MAP() 函数可以动态创建 Map 对象，参数必须成对出现（奇数位为键，偶数位为值）。

-- 创建简单 Map
SELECT MAP('name', 'Alice', 'age', '25', 'city', 'Beijing') AS profile;
-- 结果: {"name":"Alice","age":"25","city":"Beijing"}

-- 从字符串转换（常用于解析配置字符串）
SELECT STR_TO_MAP('k1:v1,k2:v2,k3:v3') AS config_map;
-- 结果: {"k1":"v1","k2":"v2","k3":"v3"}

STR_TO_MAP 函数使用两个分隔符将字符串拆分为键值对：第一个分隔符（默认为逗号 ,）分割 K-V 对，第二个分隔符（默认为冒号 :）分割每个 K-V 对的键和值。

2.3 访问 Map 元素

通过 map_col['key'] 语法可以访问 Map 中指定键对应的值。

-- 获取指定键的值
SELECT 
    user_id,
    attributes['name'] AS user_name,
    scores['Math'] AS math_score
FROM user_attributes;
-- 如果键不存在，返回 NULL

3. MAP_KEYS 函数详解

3.1 语法定义

MAP_KEYS(Map<K, V> map_obj)

参数数量：1 个参数
参数说明：map_obj 为需要提取键的 Map 对象，可以是 Map 类型的表列、MAP() 函数构造的结果，或 STR_TO_MAP() 转换的结果
返回值类型：ARRAY<K>，数组元素类型与 Map 的键类型一致

3.2 核心特性：无序性

这是 MAP_KEYS 最容易被忽视的特性：返回的数组是无序的（unordered）。这意味着：

不能依赖键在数组中的顺序，它可能与插入顺序、字典序或任何其他逻辑顺序无关
如果需要有序的键列表，必须结合 SORT_ARRAY 函数显式排序

-- 无序的键（每次执行顺序可能不同）
SELECT MAP_KEYS(MAP('b', 2, 'a', 1, 'c', 3));
-- 结果可能是: ["b","a","c"] 或 ["a","c","b"] 等

-- 有序的键
SELECT SORT_ARRAY(MAP_KEYS(MAP('b', 2, 'a', 1, 'c', 3)));
-- 结果: ["a","b","c"] （升序排序）

3.3 使用示例

-- 1. 基础键提取
SELECT MAP_KEYS(STR_TO_MAP('k1:v1,k2:v2,k3:v3')) AS keys_array;
-- 结果: ["k1","k2","k3"]

-- 2. 提取表列中的所有键
SELECT user_id, MAP_KEYS(attributes) AS attr_keys
FROM user_attributes;

-- 3. 判断 Map 中是否包含某个键（结合 ARRAY_CONTAINS）
SELECT 
    user_id,
    ARRAY_CONTAINS(MAP_KEYS(attributes), 'vip_level') AS has_vip
FROM user_attributes;

-- 4. 结合 LATERAL VIEW EXPLODE 将键展开为多行
SELECT user_id, key_name
FROM user_attributes
LATERAL VIEW EXPLODE(MAP_KEYS(attributes)) t AS key_name;

4. MAP_VALUES 函数详解

4.1 语法定义

MAP_VALUES(Map<K, V> map_obj)

参数数量：1 个参数
返回值类型：ARRAY<V>，数组元素类型与 Map 的值类型一致

4.2 核心特性：与 MAP_KEYS 的隐式对应关系

与 MAP_KEYS 一样，MAP_VALUES 返回的数组也是无序的。更重要的是：MAP_KEYS 和 MAP_VALUES 返回的数组在顺序上没有保证的对应关系。

-- 不要这样写：假设 keys[0] 对应的值就是 values[0]
-- ❌ 错误示例
SELECT MAP_KEYS(m)[0] AS key_0, MAP_VALUES(m)[0] AS value_0 FROM table;

-- ✅ 正确做法：使用 map['key'] 直接获取值
SELECT key_name, m[key_name] AS value FROM table LATERAL VIEW EXPLODE(MAP_KEYS(m)) t AS key_name;

4.3 使用示例

-- 1. 基础值提取
SELECT MAP_VALUES(STR_TO_MAP('k1:v1,k2:v2,k3:v3')) AS values_array;
-- 结果: ["v1","v2","v3"]

-- 2. 对所有值进行聚合计算（最大值、总和等）
SELECT 
    user_id,
    AVG(score) AS avg_score,
    MAX(score) AS max_score
FROM user_attributes
LATERAL VIEW EXPLODE(MAP_VALUES(scores)) t AS score
GROUP BY user_id;

-- 3. 结合 SIZE 函数统计 Map 中键值对的个数
SELECT 
    user_id,
    SIZE(scores) AS total_subjects,
    SIZE(MAP_KEYS(scores)) AS key_count,
    SIZE(MAP_VALUES(scores)) AS value_count
FROM user_attributes;
-- key_count 和 value_count 必然相等（Map 中键值对一一对应）

5. MAP_CONTAINS_KEY 函数详解

5.1 语法定义

MAP_CONTAINS_KEY(Map<K, V> map_obj, K key)

参数数量：2 个参数
参数说明：第一个参数为待检查的 Map 对象，第二个参数为需要查询的键
返回值类型：BOOLEAN（true 或 false）
功能：判断 Map 中是否包含指定的键。当键存在时返回 true，否则返回 false

5.2 核心原理与性能优势

MAP_CONTAINS_KEY 基于哈希表查找，时间复杂度为 O(1)。与 ARRAY_CONTAINS(MAP_KEYS(map), key) 相比：

ARRAY_CONTAINS(MAP_KEYS(...), ...) 需要先将 Map 的所有键提取为一个数组（O(n) 的内存和遍历开销），再对数组进行线性扫描（O(n)）
MAP_CONTAINS_KEY 直接基于哈希定位，无需构建数组、无需遍历，性能显著更优

-- 性能较差的写法：需要构建完整键数组
SELECT * FROM user_attributes
WHERE ARRAY_CONTAINS(MAP_KEYS(attributes), 'vip_level');

-- 性能更优的写法：直接使用 MAP_CONTAINS_KEY
SELECT * FROM user_attributes
WHERE MAP_CONTAINS_KEY(attributes, 'vip_level');

5.3 使用示例

-- 1. 基础判断
SELECT MAP_CONTAINS_KEY(MAP('a', 1, 'b', 2), 'a');  -- 结果: true
SELECT MAP_CONTAINS_KEY(MAP('a', 1, 'b', 2), 'c');  -- 结果: false

-- 2. 在 WHERE 子句中过滤包含特定键的记录
SELECT user_id, attributes
FROM user_attributes
WHERE MAP_CONTAINS_KEY(attributes, 'email');

-- 3. 在 CASE WHEN 中生成标志位
SELECT 
    user_id,
    CASE 
        WHEN MAP_CONTAINS_KEY(attributes, 'phone') 
            AND MAP_CONTAINS_KEY(attributes, 'email') 
        THEN 'complete'
        WHEN MAP_CONTAINS_KEY(attributes, 'phone') 
            OR MAP_CONTAINS_KEY(attributes, 'email') 
        THEN 'partial'
        ELSE 'incomplete'
    END AS profile_status
FROM user_attributes;

6. 实战场景：三者组合的经典用法

6.1 用户画像与标签筛选

利用 Map 存储用户的多值标签，通过这三个函数进行灵活的条件筛选和统计。

-- 查询同时拥有 'premium' 和 'high_value' 标签的用户
SELECT user_id, tags
FROM user_tags_map
WHERE MAP_CONTAINS_KEY(tags, 'premium')
  AND MAP_CONTAINS_KEY(tags, 'high_value');

-- 查询标签数量超过 5 个的用户
SELECT user_id, SIZE(tags) AS tag_count, MAP_KEYS(tags) AS tag_list
FROM user_tags_map
WHERE SIZE(tags) > 5;

6.2 统计键值对个数与分布

结合 SIZE 和 MAP_KEYS/MAP_VALUES，可以对 Map 数据进行宏观统计。

-- 统计每个用户拥有的属性数量分布
SELECT 
    attr_count,
    COUNT(*) AS user_cnt
FROM (
    SELECT user_id, SIZE(attributes) AS attr_count
    FROM user_attributes
) t
GROUP BY attr_count
ORDER BY attr_count;

6.3 动态字段过滤与数据清洗

在 ETL 过程中，利用 MAP_CONTAINS_KEY 判断数据完整性。

-- 只保留包含所有必需字段的记录
WITH required_keys AS (
    SELECT ARRAY('name', 'age', 'email', 'phone') AS required
)
SELECT a.*
FROM user_attributes a CROSS JOIN required_keys r
WHERE (
    SELECT COUNT(*) 
    FROM (SELECT EXPLODE(r.required) AS k) keys 
    WHERE MAP_CONTAINS_KEY(a.attributes, k)
) = SIZE(r.required);

7. NULL 值与边界情况处理

场景	行为	说明
`MAP_KEYS(NULL)`	返回 `NULL`	符合 SQL 三值逻辑
`MAP_VALUES(NULL)`	返回 `NULL`	符合 SQL 三值逻辑
`MAP_CONTAINS_KEY(NULL, key)`	返回 `NULL`	第一个参数为 `NULL` 时结果为 `NULL`
空 Map `{}`	`MAP_KEYS` 返回 `[]`（空数组），`MAP_VALUES` 返回 `[]`，`MAP_CONTAINS_KEY` 返回 `false`	空 Map 不包含任何元素
键不存在	`MAP_CONTAINS_KEY` 返回 `false`	不会返回 `NULL`
Map 中值为 `NULL` 的键	键仍存在，`MAP_CONTAINS_KEY` 返回 `true`	只判断键的存在性，不关心值是否为 `NULL`

-- 演示：Map 中值为 NULL 的键仍然被认为"存在"
SELECT MAP_CONTAINS_KEY(MAP('a', NULL, 'b', 2), 'a');
-- 结果: true （键 'a' 存在，即使其值为 NULL）

8. 跨引擎行为差异与迁移指南

8.1 Hive vs Spark SQL vs Presto/Trino

引擎	`MAP_KEYS` 支持	`MAP_VALUES` 支持	`MAP_CONTAINS_KEY` 支持	关键差异
Hive	✅ 内置支持	✅ 内置支持	✅ 内置支持	语法如本文档所述，返回数组无序
Spark SQL	✅ 内置支持	✅ 内置支持	✅ 内置支持	与 Hive 高度兼容。早期 Spark 2.0 曾回退到 Hive 执行，现已完全原生支持
Presto/Trino	✅ 内置支持	✅ 内置支持	❌ 不支持同名函数	使用 `ELEMENT_AT(map, key) IS NOT NULL` 替代；Map 取值使用 `ELEMENT_AT`
MySQL	❌ 不支持 Map 类型	-	-	无原生 Map 类型，可使用 JSON 函数替代

8.2 迁移检查清单

迁移方向	需检查事项	改写建议
Hive → Spark SQL	高度兼容	无需改写，直接迁移
Hive → Presto/Trino	`MAP_CONTAINS_KEY` 不支持	改为 `ELEMENT_AT(map, key) IS NOT NULL`
Hive → Presto/Trino	数组索引起点差异	Hive 从 0 开始，Presto 从 1 开始
Hive → Presto/Trino	获取 Map 大小函数不同	`SIZE(map)` → `CARDINALITY(map)`
Presto/Trino → Hive	`ELEMENT_AT` → `map['key']`	改回标准方括号语法

9. 常见问题与避坑指南

问题	原因	解决方案
`MAP_KEYS` 返回的数组顺序每次不同	Map 的键本身是无序的，函数返回的数组也是无序的	使用 `SORT_ARRAY(MAP_KEYS(map))` 进行排序
使用 `MAP_KEYS(map)[0]` 和 `MAP_VALUES(map)[0]` 取出的键值不匹配	两个函数返回的数组在顺序上没有保证的对应关系	使用 `map['key']` 直接获取指定键的值
`ARRAY_CONTAINS(MAP_KEYS(map), key)` 性能差	需要先构建完整键数组再线性扫描	改用 `MAP_CONTAINS_KEY(map, key)`
Map 的键类型与判断条件类型不一致	Hive 的类型检查较严格	使用 `CAST` 统一类型
`STR_TO_MAP` 解析失败	分隔符与数据格式不匹配	指定正确的分隔符，如 `STR_TO_MAP(str, ';', '=')`
Map 中存在重复键	`MAP()` 函数中重复的键会被后者覆盖	注意数据源中不要有重复的键

10. 总结

MAP_KEYS：返回 Map 中所有键组成的无序数组。配合 SORT_ARRAY 可获有序列表。
MAP_VALUES：返回 Map 中所有值组成的无序数组。与 MAP_KEYS 一样，数组元素顺序无保证。
MAP_CONTAINS_KEY：O(1) 时间复杂度判断键是否存在，性能远优于 ARRAY_CONTAINS(MAP_KEYS(...), key)。
顺序陷阱：MAP_KEYS 和 MAP_VALUES 返回的数组均无序，且两者之间无隐式的位置对应关系。需要按位置对应取值时应改用 LATERAL VIEW EXPLODE(MAP_KEYS(map)) 展开后处理。
性能优化：优先使用 MAP_CONTAINS_KEY 而非 ARRAY_CONTAINS(MAP_KEYS(...), ...) 判断键是否存在，避免不必要的数组构建开销。
跨引擎迁移：Hive 与 Spark SQL 语法完全兼容；迁移至 Presto/Trino 时需注意 MAP_CONTAINS_KEY 不支持，改用 ELEMENT_AT(map, key) IS NOT NULL。
最佳实践：在数据仓库建模时，合理利用 Map 类型存储稀疏属性或动态字段，配合这三个函数可实现灵活、高效的半结构化数据处理。