ARRAY Operators

Milvus 提供 ARRAY operators，可用于过滤 ARRAY 字段以及部分更新 ARRAY 字段值。

说明

数组中的所有元素必须是同一类型，数组中的嵌套结构将被视为纯字符串。因此，在使用 ARRAY 字段时，最好避免过深的嵌套，并确保数据结构尽可能扁平，以获得最佳性能。

Milvus 中的 ARRAY operators 覆盖两类使用场景：

• 用于 query 和 search 的过滤表达式。

• upsert 请求中的部分更新。

可用的 ARRAY operators

下表列出了 Milvus 中可用的 ARRAY operators。

Operator	用途	说明
ARRAY_CONTAINS(identifier, expr)	Filter expression	检查 ARRAY 字段中是否存在特定元素。
ARRAY_CONTAINS_ALL(identifier, expr)	Filter expression	检查指定列表中的所有元素是否都存在于 ARRAY 字段中。
ARRAY_CONTAINS_ANY(identifier, expr)	Filter expression	检查指定列表中的任一元素是否存在于 ARRAY 字段中。
ARRAY_LENGTH(identifier)	Filter expression	返回 ARRAY 字段中的元素数量，可与比较运算符结合使用以进行过滤。
ARRAY_APPEND	与 field_ops 配合用于 upsert	将 payload 元素追加到现有 ARRAY 字段。适用于 Milvus v2.6.17 及以上版本。
ARRAY_REMOVE	与 field_ops 配合用于 upsert	从现有 ARRAY 字段中移除与请求 payload 中某个值匹配的所有元素。适用于 Milvus v2.6.17 及以上版本。

ARRAY_CONTAINS

ARRAY_CONTAINS 运算符用于检查数组字段中是否存在特定元素。当您想查找数组中存在给定元素的实体时，它非常有用。

示例

假设有一个数组字段 history_temperatures，其中包含不同年份的最低气温记录。要查找数组中包含值 23 的所有实体，可以使用以下过滤表达式：

Python

filter = 'ARRAY_CONTAINS(history_temperatures, 23)'

这将返回 history_temperatures 数组包含 23 值的所有实体。

array_contains_all

ARRAY_CONTAINS_ALL 运算符可确保指定列表中的所有元素都出现在数组字段中。当您要匹配数组中包含多个值的实体时，此运算符非常有用。

示例

如果要查找 history_temperatures 数组同时包含 23 和 24 的所有实体，可以使用 ：

Python

filter = 'ARRAY_CONTAINS_ALL(history_temperatures, [23, 24])'

这将返回 history_temperatures 数组同时包含指定值的所有实体。

array_contains_any

ARRAY_CONTAINS_ANY 运算符会检查数组字段中是否存在指定列表中的任何元素。当您想匹配数组中至少包含一个指定值的实体时，此操作非常有用。

示例

要查找 history_temperatures 数组包含 23 或 24 的所有实体，可以使用 ：

Python

filter = 'ARRAY_CONTAINS_ANY(history_temperatures, [23, 24])'

这将返回 history_temperatures 数组包含 23 或 24 中至少一个值的所有实体。

ARRAY_LENGTH

ARRAY_LENGTH 返回数组字段的长度（元素个数）。它只接受一个参数：数组字段标识符。

示例

查找 history_temperatures 数组中元素少于 10 个的所有实体：

Python

filter = 'ARRAY_LENGTH(history_temperatures) < 10'

这将返回 history_temperatures 数组中元素少于 10 个的所有实体。

ARRAY_APPEND | Milvus 2.6.17+

ARRAY_APPEND operator 会在 upsert 请求期间将 payload 元素追加到现有 ARRAY 字段。它不是 Filter 表达式。当你希望在不先查询当前数组值的情况下向数组添加值时，可以使用它。

以下 Python 示例会将 "premium" 追加到主键为 1 的 Entity 的 tags ARRAY 字段：

Python

from pymilvus import FieldOp, MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

client.upsert(
    collection_name="users",
    data=[{"pk": 1, "tags": ["premium"]}],
    field_ops={"tags": FieldOp.array_append()},
)

通过 field_ops 将 ARRAY_APPEND 附加到字段，可为该字段启用局部更新语义。完整工作流、支持的元素类型和限制，请参阅 以 merge 模式 Upsert ARRAY 字段。

ARRAY_REMOVE | Milvus 2.6.17+

ARRAY_REMOVE 运算符会在 upsert 请求期间，从现有 ARRAY 字段中移除与请求 payload 中某个值匹配的所有元素。它不是过滤表达式。当你想在不先查询当前数组值的情况下移除数组中的匹配值时，可以使用它。

以下 Python 示例从主键为 1 的 Entity 的 tags ARRAY 字段中移除 "trial"：

Python

from pymilvus import FieldOp, MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus"
)

client.upsert(
    collection_name="users",
    data=[{"pk": 1, "tags": ["trial"]}],
    field_ops={"tags": FieldOp.array_remove()},
)

通过 field_ops 将 ARRAY_REMOVE 附加到字段后，该字段即可具备部分更新语义。有关完整流程、支持的元素类型和限制，请参阅 以 merge mode Upsert ARRAY 字段。