什么是MAP数据类型

MAP用于保存一组键值对，适合表示动态属性集合，或者以业务标识关联多个标量、数组或向量值。

创建MAP字段时，fieldType固定为MAP，keyType和valueType为必填参数：

1{
2    "fieldName": "attributes",
3    "fieldType": "MAP",
4    "keyType": "STRING",
5    "valueType": "STRING"
6}

当valueType为ARRAY时，还需要声明elementType；当value为向量类型或向量数组时，还需要满足对应的dimension约束。

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

数据格式

MAP在写入请求和查询结果中均使用键值对数组，而不是JSON Object：

1{
2    "attributes": [
3        ["language", "cpp"],
4        ["category", "database"]
5    ]
6}

其通用形式为：

1[[key1, value1], [key2, value2], ...]

使用时需注意：

• 最外层必须是JSON Array，每一项必须是长度为2的JSON Array。
• key和value的类型必须分别与Schema中的keyType和valueType一致。
• []是合法的空MAP。
• 不支持显式传入顶层null，键值对中的key和value也不能为null。
• nullable MAP字段可以在写入时省略。字段未写入时，读取结果中会省略该字段。
• 客户端应确保key唯一，重复key的行为未定义。
• 不应依赖键值对的返回顺序表达业务语义。

以下JSON Object形式不是合法的MAP输入：

1{
2    "attributes": {
3        "language": "cpp"
4    }
5}

MAP中的ARRAY值

MAP<K, ARRAY<T>>的value使用嵌套JSON数组：

1{
2    "attributes": [
3        ["language", ["cpp", "rust"]],
4        ["database", ["mochow"]]
5    ]
6}

每个value都必须满足ARRAY对应的elementType约束。

数据写入与读取

Insert和Upsert

Insert和Upsert均写入完整MAP值：

1{
2    "database": "db",
3    "table": "docs",
4    "rows": [
5        {
6            "id": 1,
7            "attributes": [
8                ["language", "cpp"],
9                ["category", "database"]
10            ]
11        }
12    ]
13}

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

Update

Update仅支持替换完整MAP值：

1{
2    "database": "db",
3    "table": "docs",
4    "primaryKey": {
5        "id": 1
6    },
7    "update": {
8        "attributes": [
9            ["language", "rust"]
10        ]
11    }
12}

传入"attributes": []可以清空MAP。

当前不支持按key执行put、set、remove或merge，也不支持JSON Patch、JSON Merge Patch。ARRAY字段的append、remove更新表达式不适用于MAP。

Query、BatchQuery、Select和Search

在projections中指定标量MAP字段名后，系统返回完整键值对数组：

1{
2    "projections": ["id", "attributes"]
3}

Projection不支持只返回某个MAP key。向量MAP字段还受retrieveVector及相应查询或检索接口的限制。

Delete

Delete始终删除满足条件的整行，不支持只删除MAP中的某个键值对。

过滤与索引

当前没有MAP成员过滤函数，标量MAP也不支持标量索引。因此，不能通过MAP的key或value条件筛选Select、Search或Delete记录。

MAP的value可以使用受支持的向量类型。这类MAP字段还受向量维度、retrieveVector、向量索引和Search接口的额外限制。

使用限制

• MAP必须使用键值对数组表示，不能使用JSON Object。
• MAP不能作为主键或分区键。
• 不支持按key局部读取、更新或删除。
• 不支持对MAP执行merge、JSON Patch、JSON Merge Patch或ARRAY的append、remove。
• 不支持使用MAP成员条件进行标量过滤。
• 不支持为标量MAP建立标量索引。