--- title: "半结构化编码 - OceanBase 数据库 V4.6.0 | OceanBase 文档中心" description: 半结构化编码 本文档主要介绍 OceanBase 数据库支持的 JSON 数据半结构化编码功能。 注意 从 V4.4.1 版本开始，表级别参数 SEMISTRUCT_ENCODING_TYPE 已废弃，使用 SEMISTRUCT_PROPERTIES 替代。 OceanBase 数据库支持 MySQL 租户下建表时开… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.6.0 # 半结构化编码 更新时间：2026-07-15 15:16:39 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.6.0/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/100.basic-elements-of-mysql-mode/100.data-type-of-mysql-mode/800.json-formatted-data-type-of-mysql-mode/600.json-semi-struct-of-mysql-mode.md) 本文档主要介绍 OceanBase 数据库支持的 JSON 数据半结构化编码功能。 #### 注意 从 V4.4.1 版本开始，表级别参数 `SEMISTRUCT_ENCODING_TYPE` 已废弃，使用 `SEMISTRUCT_PROPERTIES` 替代。 OceanBase 数据库支持 MySQL 租户下建表时开启半结构化编码，主要由表级别参数 `SEMISTRUCT_PROPERTIES` 控制，同时也要设置表的 `ROW_FORMAT=COMPRESSED`，否则会报错。 ## 注意事项 - 当 `SEMISTRUCT_PROPERTIES=(encoding_type=encoding)` 时，表被认为是半结构化表，即整张表中的 JSON 列都会启用半结构化编码； - 当 `SEMISTRUCT_PROPERTIES=(encoding_type=none)` 时，表被认为是结构化表。 - 同时，还支持通过 `freq_threshold` 参数设置频率阈值。当启用半结构化编码时，系统会分析 JSON 数据中各个路径的出现频率，将出现频率高于设定阈值的路径作为独立的子列存储，这些子列就称为频繁列。例如，假设您有一个用户表，JSON 字段存储用户信息，如果 90% 的用户都有 `name` 和 `age` 字段，那么系统会自动将 `name` 和 `age` 提取为独立的频繁列，查询时直接访问这些列而不需要解析整个 JSON，从而提升查询性能。具体语法和参数说明请参见 [CREATE TABLE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686098)。 - 当前 `encoding_type` 和 `freq_threshold` 是 Online DDL 语法，不支持 Offline DDL 语法。 ## 数据形式 把 JSON 数据按照一定的形式拆分成结构化列的方式存储，那么从 JSON 列拆分出的列被称为子列。子列可以被拆分为不同的类型，包括稀疏列和频繁列。 - 稀疏列：部分 JSON 有，部分 JSON 没有的子列，出现频率低于表级别参数 `freq_threshold` 指定的阈值。 - 频繁列：JSON 中出现频率高于表级别参数 `freq_threshold` 指定的阈值的子列，这些子列会被作为独立的列存储，以提升过滤查询性能。 例如： ```sql {"id": 1001, "name": "n1", "nickname": "nn1"} {"id": 1002, "name": "n2", "nickname": "nn2"} {"id": 1003, "name": "n3", "nickname": "nn3"} {"id": 1004, "name": "n4", "nickname": "nn4"} {"id": 1005, "name": "n5"} ``` 其中 `id` 和 `name` 是每个 JSON 都有的字段，出现频率为 100%，`nickname` 只有 4 个 JSON 有，出现频率为 80%。 如果 `freq_threshold` 定义为 100%，那么 `nickname` 就会被推导为稀疏列，`id` 和 `name` 就会被推导为频繁列；如果定义为 80%，那么 `nickname`、`id` 和 `name` 就都会被推导为频繁列。 ## 示例 1. 启用半结构化编码 #### 注意 如果启用半结构化编码功能，请务必保证集群配置项 [micro_block_merge_verify_level](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005685677) 为默认配置 `2` ，切勿关闭微块合并校验。 建表时启用的示例 修改已有表来启用半结构化编码的示例 ```sql CREATE TABLE t1( j json) ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES=(encoding_type=encoding, freq_threshold=50); ``` 更多语法说明请见 [CREATE TABLE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686098)。 ```sql CREATE TABLE t1(j json); ALTER TABLE t1 SET ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES = (encoding_type=encoding, freq_threshold=50); ``` 更多语法说明请见 [ALTER TABLE](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005686147)。 一些修改限制： - 修改频繁列阈值，如果没开启半结构化不报错，但是不生效。 - 在旁路导入或表被锁定时，`freq_threshold` 参数无法修改。 - 修改其中一个子配置项，不影响其余的子配置项。 2. 关闭半结构化编码 当 `SEMISTRUCT_PROPERTIES` 设置为 `(encoding_type=none)` 时，将关闭半结构化编码。此操作不会影响已有的数据，仅对后续写入的数据生效。以下是关闭半结构化编码的示例： ```sql ALTER TABLE t1 SET ROW_FORMAT=COMPRESSED SEMISTRUCT_PROPERTIES = (encoding_type=none); ``` 3. 查询半结构编码配置 通过 `SHOW CREATE TABLE` 语句查询半结构化编码配置。示例语句如下： ```sql SHOW CREATE TABLE t1; ``` 返回结果如下： ```shell +-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Table | Create Table | +-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | t1 | CREATE TABLE `t1` ( `j` json DEFAULT NULL ) ORGANIZATION INDEX DEFAULT CHARSET = utf8mb4 ROW_FORMAT = COMPRESSED COMPRESSION = 'zstd_1.3.8' REPLICA_NUM = 1 BLOCK_SIZE = 16384 USE_BLOOM_FILTER = FALSE ENABLE_MACRO_BLOCK_BLOOM_FILTER = FALSE TABLET_SIZE = 134217728 PCTFREE = 0 SEMISTRUCT_PROPERTIES=(ENCODING_TYPE=ENCODING, FREQ_THRESHOLD=50) | +-------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 1 row in set ``` 当 `SEMISTRUCT_PROPERTIES=(encoding_type=encoding)` 时，查询才会显示该配置项信息，表示开启了半结构化编码功能。 使用半结构化编码可以提高 [JSON_VALUE() 函数](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000005688068) 条件过滤查询的性能。基于 JSON 半结构化编码技术，OceanBase 对 `JSON_VALUE` 表达式条件过滤查询场景进行了性能优化。由于 JSON 数据已被拆分为子列，系统可以直接基于编码后的子列数据进行过滤，无需还原完整的 JSON 结构，从而显著提升查询效率。 查询示例如下： ```sql -- 查询 name 字段值为 'Devin' 的行 SELECT * FROM t WHERE JSON_VALUE(j_doc, '$.name' RETURNING CHAR) = 'Devin'; ``` 字符集注意事项如下： - OceanBase 的 JSON 使用 `utf8_bin` 编码。 - 为确保字符串白盒过滤正常工作，建议设置： ```sql SET @@collation_server = 'utf8mb4_bin'; SET @@collation_connection='utf8mb4_bin'; ``` 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线