字典布局类型

字典可通过多种方式存储在内存中，每种方式都需要在 CPU 和 RAM 占用之间进行权衡。

布局	说明
flat	将数据存储在按键索引的扁平数组中。该布局速度最快，但键必须为 `UInt64`，且受 `max_array_size` 限制。
hashed	将数据存储在哈希表中。对键大小没有限制，支持任意数量的元素。
sparse_hashed	类似 `hashed`，但以更高的 CPU 开销换取更低的内存占用。
complex_key_hashed	类似 `hashed`，用于复合键。
complex_key_sparse_hashed	类似 `sparse_hashed`，用于复合键。
hashed_array	属性存储在数组中，并通过哈希表将键映射到数组索引。适用于属性较多且更节省内存的场景。
complex_key_hashed_array	类似 `hashed_array`，用于复合键。
range_hashed	带有有序范围的哈希表。支持按键 + 日期/时间范围进行查找。
complex_key_range_hashed	类似 `range_hashed`，用于复合键。
cache	固定大小的内存缓存。仅存储经常访问的键。
complex_key_cache	类似 `cache`，用于复合键。
ssd_cache	类似 `cache`，但将数据存储在 SSD 上，并在内存中保留索引。
complex_key_ssd_cache	类似 `ssd_cache`，用于复合键。
direct	不在内存中存储，而是针对每个请求直接查询 source。
complex_key_direct	类似 `direct`，用于复合键。
ip_trie	用于快速进行 IP 前缀查找 (基于 CIDR) 的 Trie 结构。
hierarchical	支持层级结构，使用数值键描述父子关系。
polygon	高效执行点是否位于多边形内的查找 (反向地理编码) 。
regexp_tree	将键与正则表达式树进行匹配。

推荐布局flat、hashed 和 complex_key_hashed 可提供最佳查询性能。不推荐使用缓存类布局，因为其性能可能较差，且参数调优困难——详见 cache。

基于缓存的布局无法可靠地支持写入时富集，因为已预热的条目仅保存在各个服务器本地，一旦服务器重启或被替换就会丢失。而 ClickHouse Cloud 的自动扩缩容和托管节点替换会使这种情况更容易发生。请改用完全加载的布局；详见摄取路径中的缓存字典。

指定字典布局

如果您在 ClickHouse Cloud 中使用字典，请使用 DDL 查询选项创建字典，并以 default 用户创建。此外，请在 Cloud 兼容性指南中确认受支持的字典源列表。

你可以使用 LAYOUT 子句 (用于 DDL) ，或在配置文件定义中使用 layout 设置来配置字典布局。

DDL
配置文件

CREATE DICTIONARY (...)
...
LAYOUT(LAYOUT_TYPE(param value)) -- 布局设置
...

<clickhouse>
    <dictionary>
        ...
        <layout>
            <layout_type>
                <!-- 布局设置 -->
            </layout_type>
        </layout>
        ...
    </dictionary>
</clickhouse>

另请参阅 CREATE DICTIONARY 以了解完整的 DDL 语法。布局中不包含 complex-key* 的字典，其键类型为 UInt64；complex-key* 字典则使用复合键 (复杂键，可包含任意类型) 。 数值键示例 (列 key_column 的类型为 UInt64) ：

DDL
配置文件

CREATE DICTIONARY dict_name (
    key_column UInt64,
    ...
)
PRIMARY KEY key_column

<structure>
    <id>
        <name>key_column</name>
    </id>
    ...
</structure>

复合键示例 (该键包含一个 String 类型的元素) ：

DDL
配置文件

CREATE DICTIONARY dict_name (
    country_code String,
    ...
)
PRIMARY KEY country_code

<structure>
    <key>
        <attribute>
            <name>country_code</name>
            <type>String</type>
        </attribute>
    </key>
    ...
</structure>

提高字典性能

有几种方法可以提高字典性能：

在 GROUP BY 之后调用字典相关函数。
将要提取的属性标记为 injective。如果不同的键对应不同的属性值，则该属性称为 injective。因此，当 GROUP BY 使用按键获取属性值的函数时，该函数会自动从 GROUP BY 中移出。

对于字典错误，ClickHouse 会生成异常。错误示例包括：

正在访问的字典无法加载。
查询 cached 字典时出错。

你可以在 system.dictionaries 表中查看字典列表及其状态。

SQL 参考文档

数据类型

引擎

函数

格式

设置

系统表

数据湖

字典布局类型