什么是ARRAY数据类型

ARRAY用于保存一组有序且类型相同的元素，适合表示标签、类别、关键词等一对多属性。数组会保留元素的写入顺序和重复值。

创建ARRAY字段时，fieldType固定为ARRAY，并通过elementType声明元素类型。还可以通过maxCapacity限制数组最大长度。

1{
2    "fieldName": "tags",
3    "fieldType": "ARRAY",
4    "elementType": "STRING",
5    "maxCapacity": 20
6}

ARRAY不能作为主键或分区键。elementType支持BOOL、各类整数和浮点数、DATE、DATETIME、TIMESTAMP、UUID、STRING、BINARY、TEXT、TEXT_GBK、TEXT_GB18030及FLOAT_VECTOR。ARRAY<FLOAT_VECTOR>还需要配置向量维度。

数据格式

ARRAY字段在写入请求和查询结果中均使用JSON数组表示。例如，ARRAY<STRING>字段可以写为：

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

使用时需注意：

• 每个元素的类型必须与Schema中的elementType一致。
• []是合法的空数组。
• 不支持显式传入顶层null，数组元素也不能为null。
• 数组长度不能超过maxCapacity；未配置maxCapacity时不限制长度。
• nullable ARRAY字段可以在写入时省略。字段未写入时，读取结果中会省略该字段；字段存在时返回完整数组，包括空数组。

数据写入与读取

Insert和Upsert

Insert和Upsert均写入完整数组：

1{
2    "database": "db",
3    "table": "docs",
4    "rows": [
5        {
6            "id": 1,
7            "tags": ["database", "vector"]
8        }
9    ]
10}

Upsert是整行覆盖。主键已存在时，新数组会整体替换旧数组；nullable ARRAY字段未出现在Upsert记录中时，不表示保留旧数组。只修改ARRAY字段时，请使用Update。

Update

直接传入新数组可以替换字段的完整值：

1{
2    "database": "db",
3    "table": "docs",
4    "primaryKey": {
5        "id": 1
6    },
7    "update": {
8        "tags": ["new", "values"]
9    }
10}

传入"tags": []可以清空数组。

ARRAY还支持通过更新表达式追加或删除元素。追加元素：

1{
2    "update": {
3        "tags": {
4            "operator": "append",
5            "value": ["database", "vector"]
6        }
7    }
8}

按值删除元素：

1{
2    "update": {
3        "tags": {
4            "operator": "remove",
5            "value": ["old", "deprecated"]
6        }
7    }
8}

append和remove遵循以下规则：

• value可以是与elementType匹配的单个值，也可以是由该类型元素组成的非空数组。
• value: []不合法；清空数组应使用完整值替换。
• append按照请求顺序追加元素，允许产生重复值；更新后仍需满足maxCapacity限制。
• remove删除数组中所有等于目标值的元素；目标值不存在时，数组保持不变。
• 增量操作要求字段已经存在数组值。字段尚未写入时，应先通过完整值替换赋值。
• Update要求目标记录已经存在，否则返回Row Key Not Found。

ARRAY当前不支持按下标更新、在指定位置插入、pop或自动去重。

Query、BatchQuery、Select和Search

在projections中指定ARRAY字段名，即可返回完整数组：

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

Projection不支持只返回指定下标的元素。retrieveVector只控制向量字段，不影响ARRAY<STRING>等非向量数组；ARRAY<FLOAT_VECTOR>还受向量返回及检索接口的相关限制。

Delete

Delete始终删除满足条件的整行记录。若只需删除ARRAY中的指定值，应使用Update的remove操作。

过滤表达式

ARRAY支持以下按值过滤函数：

1array_contains(tags, 'database')
2array_contains_any(tags, ['database', 'vector'])
3array_contains_all(tags, ['database', 'vector'])

• array_contains：数组包含指定元素。
• array_contains_any：数组至少包含给定列表中的一个元素。
• array_contains_all：数组包含给定列表中的全部元素。

ARRAY还支持按下标访问元素：

1tags[1] = 'vector'

数组下标从0开始。越界下标在普通比较中不匹配；使用IS NULL时，字段缺失或下标越界均满足条件。

过滤表达式可以用于Select、Search、Hybrid Search和Delete，但仍受对应检索接口及索引的Filter限制。ARRAY<STRING>使用精确字符串匹配，不进行分词。

索引与全文检索

ARRAY可建立的索引取决于元素类型：

• 除ARRAY<FLOAT_VECTOR>以外的ARRAY字段可以用于FILTERING索引。
• ARRAY字段可以用于PERSISTENT_BITMAP索引。
• ARRAY<TEXT>可以建立倒排索引，用于全文检索。
• ARRAY<FLOAT_VECTOR>可以建立受支持的向量索引。

ARRAY<STRING>的array_contains*属于精确匹配，不等同于基于ARRAY<TEXT>的全文检索。

使用限制

• ARRAY不能作为主键或分区键。
• 完整数组或数组元素不能显式传入null。
• Projection不能只返回指定下标的元素。
• 不支持按下标更新、指定位置插入、pop或自动去重。
• Delete不能只删除数组中的元素。
• append、remove为版本相关能力，使用旧版本或混合版本部署时，请先确认目标实例版本支持对应更新表达式。