数据字典--ByteHouse云数仓版-火山引擎

文档中心

ByteHouse云数仓版

数据建模

数据字典

ByteHouse CDW 数据字典支持内部预定义字典内容。本文介绍了如何创建和使用数据字典。

创建字典表

您可以直接在 SQL 工作台使用 DDL 语句来新建字典表。

CREATE DICTIONARY [IF NOT EXISTS] [db.]dictionary_name
(
    key1 type1  [DEFAULT|EXPRESSION expr1] [HIERARCHICAL|INJECTIVE|IS_OBJECT_ID],
    key2 type2  [DEFAULT|EXPRESSION expr2] [HIERARCHICAL|INJECTIVE|IS_OBJECT_ID],
    attr1 type2 [DEFAULT|EXPRESSION expr3],
    attr2 type2 [DEFAULT|EXPRESSION expr4]
)
PRIMARY KEY key1, key2
SOURCE(SOURCE_NAME([param1 value1 ... paramN valueN]))
LAYOUT(LAYOUT_NAME([param_name param_value]))
LIFETIME({MIN min_val MAX max_val | max_val})

参数说明

参数名称	是否必填	说明
IF NOT EXISTS	否	可选关键字，存在同名字典时不报错。
[db.]dictionary_name	是	设置字典所属数据库和字典名称。
keyN typeN	是	字典键字段及类型，用于唯一标识条目。示例：`key1 UInt64, key2 String`
DEFAULT	EXPRESSION expr	否
HIERARCHICAL	INJECTIVE	IS_OBJECT_ID HIERARCHICAL：层级关系 INJECTIVE：唯一映射 IS_OBJECT_ID：对象 ID 特性
attrN typeN	是	字典属性字段及类型，存储关联数据。
PRIMARY KEY key1, key2	是	指定哪些键组合作为主键。
SOURCE(SOURCE_NAME(...))	是	数据源类型及参数，支持内部数据源，配置详情请参考数据源配置示例。
LAYOUT(LAYOUT_NAME(...))	是	字典数据存储布局，支持 flat、hashed 等。
LIFETIME({MIN min_val MAX max_val	max_val})	是 MIN：最小刷新间隔 (秒) MAX：最大刷新间隔 (秒)

数据源配置示例

SOURCE 配置详情如下：

SOURCE(CLICKHOUSE(
    user 'default'
    [db 'dbName']
    table 'ids'
    where 'id=10'
))

参数说明：

user：固定为 default。
db：可选，数据源表所在的数据库名称。
table: 作为数据源的具体表名。
where: 可选，用于过滤源表数据的 SQL WHERE 子句条件。

使用字典表

您可以执行查询字典数据、删除数据、查询字典、查询创建字典的语句等操作。

查询字典数据

您可以使用一些函数来获取字典的信息，常用的函数可以参考 ClickHouse 社区字典函数。
例如，通过使用dictGet / dictGetOrDefault 语句和函数获取数据字典中的数据：

dictGet('db.dict_name', 'attr_name', id_expr)
dictGetOrDefault('db.dict_name', 'attr_name', id_expr, default_value_expr)

说明

dictGet 函数的第一个参数的格式必须类似于 db.dict_name，因为字典缓存通过该字段来索引。

检查字典中是否存在某个键id_expr：

dictHas('db.dict_name', id_expr)

删除字典

执行该操作后，ByteHouse 将删除 Catalog 中该字典的记录。

DROP DICTIONARY [IF EXISTS] [db.]dictionary_name;

查询字典

注意

执行 SHOW DICTIONARIES 需要 AccountAdmin 角色的 *.* 全局权限。请确保您具备此权限。如需配置，请联系管理员，参考角色管理授予权限。

SHOW DICTIONARIES [FROM <db>];

如果未指定 FROM 子句，则查询将返回当前数据库中的词典列表。

查询创建字典语句

SHOW CREATE DICTIONARY [db.] dictionary_name

该查询语句将返回一个字符串类型的 “statement” 列，该列的值为创建字典的 CREATE 语句，示例如下：

最佳实践：创建并使用数据字典

创建数据库。
```
Create Database test_db;
```

创建数据表。

CREATE TABLE `test_db`.`range_key_dictionary_source_table` (
    `key` UInt64,
    `start_date` Date,
    `end_date` Date,
    `value` String,
    `value_nullable` Nullable(String)
)
ENGINE = CnchMergeTree()
PRIMARY KEY (`key`, `start_date`) 
ORDER BY (`key`, `start_date`, `end_date`)
COMMENT='demo';

创建字典。

CREATE DICTIONARY test_db.range_key_dictionary
(
  `key` UInt64,
  `start_date` Date,
  `end_date` Date,
  `value` String,
  `value_nullable` String
)
PRIMARY KEY `key`
SOURCE(CLICKHOUSE(USER 'default' DB 'test_db' TABLE 'range_key_dictionary_source_table'))
LIFETIME(MIN 10 MAX 20)
LAYOUT(COMPLEX_KEY_HASHED());

查询字典内容。
```
SHOW DICTIONARIES FROM test_db; 
```
输出结果示例如下：

（可选）删除字典。

DROP dictionary test_db.range_key_dictionary;

最近更新时间：2025.08.01 18:22:20

这个页面对您有帮助吗？

有用

无用

ByteHouse云数仓版

参数说明 #

数据源配置示例 #

查询字典数据 #

删除字典 #