ARRAY 運算子

Milvus 提供 ARRAY 運算子，用於篩選 ARRAY 欄位以及部分更新 ARRAY 欄位值。

Milvus 中的 ARRAY 運算子涵蓋兩種使用情境：

• 用於查詢與搜尋的篩選表達式。

• upsert 請求中的部分更新。

可用的 ARRAY 運算子

下表列出了 Milvus 中可用的 ARRAY 運算子。

運算子	適用於	說明
ARRAY_CONTAINS(識別碼, 表達式)	篩選表達式	檢查特定元素是否存在於 ARRAY 欄位中。
ARRAY_CONTAINS_ALL(識別碼, 表達式)	篩選式	檢查指定清單中的所有元素是否皆存在於 ARRAY 欄位中。
ARRAY_CONTAINS_ANY(識別碼, 表達式)	篩選表達式	檢查指定清單中的任何元素是否存在於 ARRAY 欄位中。
ARRAY_LENGTH(識別碼)	篩選表達式	返回 ARRAY 欄位中的元素個數，並可與比較運算子結合進行篩選。
ARRAY_APPEND	upsert withfield_ops	將有效載荷元素追加至現有的 ARRAY 欄位。適用於 Milvus v2.6.17 及後續版本。
ARRAY_REMOVE	upsert 與field_ops	從現有的 ARRAY 欄位中移除所有與請求有效載荷中某個值相符的元素。適用於 Milvus v2.6.17 及後續版本。

ARRAY_CONTAINS

ARRAY_CONTAINS 運算子用於檢查陣列欄位中是否存在特定元素。當您需要查找陣列中包含特定元素的實體時，此功能非常實用。

範例

假設您有一個名為 `history_temperatures` 的陣列欄位，其中包含各年份的最低氣溫紀錄。若要找出陣列中包含值 `23` 的所有實體，可使用以下篩選表達式：

filter = 'ARRAY_CONTAINS(history_temperatures, 23)'

這將回傳所有history_temperatures 陣列中包含值23 的實體。

ARRAY_CONTAINS_ALL

ARRAY_CONTAINS_ALL 運算子可確保指定清單中的所有元素均存在於陣列欄位中。當您需要篩選陣列中包含多個值的實體時，此運算子便十分實用。

範例

若要找出所有history_temperatures 陣列同時包含23 和24 的實體，可使用：

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

這將回傳所有history_temperatures 陣列同時包含上述兩個指定值的實體。

ARRAY_CONTAINS_ANY

ARRAY_CONTAINS_ANY 運算子會檢查陣列欄位中是否存在指定清單中的任何元素。當您希望匹配陣列中至少包含一個指定值的實體時，此功能非常實用。

範例

若要找出所有history_temperatures 陣列中包含23 或24 任一項的實體，可使用以下語法：

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

這將回傳所有history_temperatures 陣列中至少包含23 或24 其中一個值的實體。

ARRAY_LENGTH

ARRAY_LENGTH 會傳回陣列欄位的長度（元素數量）。它僅接受一個參數：陣列欄位識別碼。

範例

要查詢所有history_temperatures 陣列元素數少於 10 個的實體：

filter = 'ARRAY_LENGTH(history_temperatures) < 10'

這將回傳所有history_temperatures 陣列元素數少於10個的實體。

ARRAY_APPENDCompatible with Milvus 2.6.17+

ARRAY_APPEND 運算子會在執行upsert 請求時，將有效載荷元素追加至現有的 ARRAY 欄位中。它並非篩選表達式。當您希望直接向陣列新增值，而無需先查詢當前陣列值時，請使用此運算子。

以下 Python 範例將 `"premium" ` 附加至主鍵為 `1` 的實體之 `tags ` ARRAY 欄位：

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 ` 附加至欄位，可為該欄位啟用部分更新語義。有關完整工作流程、受支援的元素類型及限制，請參閱「合併模式下的 Upsert ARRAY 欄位」。

ARRAY_REMOVECompatible with Milvus 2.6.17+

ARRAY_REMOVE 運算子會在upsert 請求期間，從現有的 ARRAY 欄位中移除所有與請求載荷中值相符的元素。這並非篩選表達式。當您希望從陣列中移除相符值，且無需事先查詢當前陣列值時，請使用此運算子。

以下 Python 範例會從主鍵為1 的實體之tags ARRAY 欄位中，移除"trial" ：

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 ` 附加至欄位，可為該欄位啟用部分更新語義。有關完整工作流程、受支援的元素類型及限制，請參閱「合併模式下的 Upsert ARRAY 欄位」。