什么是JSON数据类型

JSON字段用于保存具有层次结构的半结构化数据，适合存储文档元数据、业务扩展属性等内容。字段值可以是JSON Object，也可以通过兼容编码写入JSON Array。

Schema定义示例如下：

1{
2    "fieldName": "metadata",
3    "fieldType": "JSON"
4}

JSON不能作为主键或分区键。

数据格式

推荐直接使用JSON Object写入：

1{
2    "metadata": {
3        "author": "alice",
4        "tags": ["database", "vector"],
5        "deleted": null
6    }
7}

当前还兼容将完整JSON Object或JSON Array序列化为JSON String后写入：

1{
2    "metadata": "{\"author\":\"alice\",\"tags\":[\"database\",\"vector\"]}"
3}

支持情况如下：

JSON Object或Array的内部成员可以为null。nullable JSON表示该字段可以在写入时省略，不表示可以显式写入顶层null。字段未写入时，读取结果中会省略该字段。

单个JSON字段的输入大小不能超过1 MiB。直接写入的Object会先压缩为紧凑JSON再检查大小；序列化JSON String按照传入字符串的字节数检查。

返回格式

查询JSON字段时，系统返回解析后的实际JSON值，而不是序列化字符串：

1{
2    "metadata": {
3        "author": "alice",
4        "tags": ["database", "vector"]
5    }
6}

如果通过序列化JSON String写入顶层Array，查询时返回JSON Array：

1{
2    "metadata": ["database", "vector"]
3}

JSON字段不保证保留写入内容的空白、排版或Object key顺序。

数据写入与读取

Insert和Upsert

Insert和Upsert均写入完整JSON值。Upsert是整行覆盖：主键已存在时，请求中的JSON字段会整体替换旧值；nullable JSON字段未出现在Upsert记录中时，不表示保留旧JSON。

Update

Update仅支持替换完整JSON字段：

1{
2    "database": "db",
3    "table": "docs",
4    "primaryKey": {
5        "id": 1
6    },
7    "update": {
8        "metadata": {
9            "author": "bob",
10            "tags": []
11        }
12    }
13}

当前不支持JSON Patch、JSON Merge Patch、按JSON Path更新，或者只增加、修改、删除某个key。ARRAY字段的append、remove更新表达式也不适用于JSON字段。

Query、BatchQuery、Select和Search

在projections中指定JSON字段名后，系统返回完整且已解析的JSON值。Projection不支持按JSON Path只返回子节点；JSON Path仅用于Filter表达式。

Delete

Delete可以使用JSON Filter筛选记录，但始终删除整行，不支持只删除JSON内部成员。

过滤表达式

JSON支持使用下标或成员访问方式定位内部值：

1metadata.author.name = 'alice'
2metadata['tags'][0] = 'database'
3metadata['count'] IN (1, 2, 3)
4metadata['deleted'] IS NULL

还可以使用以下JSON函数：

1json_path_exists(metadata, '$.author.name')
2json_extract_value(metadata, '$.author.name') = 'alice'
3json_array_contains(metadata, '$.tags', 'database')
4json_array_contains_any(metadata, '$.tags', ['database', 'vector'])
5json_array_contains_all(metadata, '$.tags', ['database', 'vector'])

使用JSON过滤表达式时需注意：

• JSON Path必须以$开始，可以访问嵌套Object成员和Array下标。
• JSON成员按照实际类型进行比较，例如字符串'true'不等于Boolean值true。
• json_path_exists在路径存在时返回true，即使该路径的值为JSON null。
• json_array_contains*的目标路径不存在或目标值不是Array时返回false。
• 不能直接比较整个JSON字段，必须指定成员或JSON Path。
• IS NULL同时匹配路径不存在和路径值为JSON null；IS NOT NULL要求路径存在且值不为null。

JSON Path中的.表示成员访问，[]表示数组下标。路径中的key包含$、.、[或]等特殊字符时，需要使用双引号，例如：

1json_extract_value(metadata, '$.keys."C-."')

双引号中的反斜杠遵循JSON转义规则。

索引

JSON支持倒排索引。倒排索引包含JSON字段时，必须在fieldsIndexAttributes中为该字段显式配置以下一种处理方式。

将完整JSON作为普通文本分析：

1{
2    "type": "ATTRIBUTE_ANALYZE_JSON_AS_PLAIN_TEXT"
3}

将JSON的key和value拼接为词项：

1{
2    "type": "ATTRIBUTE_CONCATENATE_JSON_KV_AS_TERM",
3    "concatenateSymbol": "."
4}

JSON不支持SECONDARY、PERSISTENT_BITMAP或PERSISTENT_AGGREGATED_BITMAP索引。

使用限制

• 不支持直接写入顶层JSON Array；如需写入顶层Array，应使用序列化后的JSON String。
• 不支持写入顶层JSON scalar或null。
• JSON不能作为主键或分区键。
• 不支持按JSON Path局部投影或更新。
• 不支持JSON Patch、JSON Merge Patch，以及只增加或删除内部成员。
• 不支持直接比较整个JSON字段。