StructArray 運算子
StructArray 運算子會透過評估 StructArray 欄位內部的標量子欄位之謂詞，來篩選實體。請將本頁作為 `element_filter ` 及 `MATCH_* ` 運算子家族的語法參考。
StructArray 篩選包含兩個運算子家族：
| 運算子家族 | 主要用途 | 結果行為 |
|---|---|---|
element_filter | 匹配滿足標量謂詞的 Struct 元素。 | 在元素層級搜尋中，匹配結果可能包含元素偏移量。在列層級查詢或篩選搜尋中，結果的形狀取決於 API 及輸出欄位。 |
MATCH_* | 根據滿足標量判別式的 Struct 元素數量來選取實體。 | 列級篩選。這些運算子本身不會回傳元素偏移量。 |
在 StructArray 運算子中使用標量子欄位。向量子欄位用於向量搜尋路徑，並非標量謂詞的輸入。
何時使用哪種運算子
| 目標 | 用途 |
|---|---|
| 將元素層級向量搜尋限制為符合標量條件的元素。 | element_filter |
| 在同一個 Struct 元素內匹配多個標量條件。 | element_filter |
| 僅回傳至少有一個 Struct 元素滿足某個謂詞的實體。 | MATCH_ANY |
| 僅回傳所有 Struct 元素均滿足某個謂詞的實體。 | MATCH_ALL |
僅回傳至少、至多或恰好有N 個 Struct 元素滿足某個謂詞的實體。 | MATCH_LEAST、MATCH_MOST ，或MATCH_EXACT |
元素篩選器
使用 `element_filter(structArrayField, predicate) ` 來匹配 `StructArray` 欄位中的 `Struct` 元素。
在謂詞內部，使用$[subfield] 來引用當前 Struct 元素的標量子欄位。
element_filter(chunks, $[section] == "index")
當在謂詞內部使用多個條件時，所有$[subfield] 引用均適用於同一個 Struct 元素：
element_filter(chunks, $[section] == "index" && $[quality_score] > 0.9)
當您將實體層級的謂詞與 `element_filter` 結合使用時，請將 `element_filter ` 置於表達式的末尾：
# Correct
category == "index" && element_filter(chunks, $[quality_score] > 0.9)
# Incorrect
element_filter(chunks, $[quality_score] > 0.9) && category == "index"
element_filter 在篩選表達式中只能出現一次。請勿將 `element_filter ` 或 `MATCH_* ` 嵌套在另一個 `element_filter` 之中。
匹配家族運算子
當需根據滿足某個謂詞的 Struct 元素數量來選取實體時，請使用MATCH_* 運算子。
| 運算子 | 含義 |
|---|---|
MATCH_ANY(field, predicate) | 至少有一個 Struct 元素滿足該謂詞。 |
MATCH_ALL(field, predicate) | 所有 Struct 元素皆滿足該謂詞。 |
MATCH_LEAST(field, predicate, threshold=N) | 至少有N 個 Struct 元素滿足該謂詞。 |
MATCH_MOST(field, predicate, threshold=N) | 至多有N 個結構體元素滿足該謂詞。 |
MATCH_EXACT(field, predicate, threshold=N) | 恰有N 個 Struct 元素滿足該謂詞。 |
MATCH_ANY 而 `element_filter ` 兩者皆可表示至少有一個 Struct 元素滿足該謂詞。當您僅需進行列級篩選時，請使用 `MATCH_ANY `；當您需要元素級約束（例如篩選哪些 Struct 元素參與元素級向量搜尋）時，請使用 `element_filter `。
MATCH_ANY
MATCH_ANY 若 StructArray 中至少有一個元素滿足該謂詞，則其評估結果為true 。
MATCH_ANY(chunks, $[section] == "index")
對於空的 StructArray，MATCH_ANY 會傳回false 。
MATCH_ALL
MATCH_ALL 若 StructArray 中的每個元素都滿足該謂詞，則評估結果為true 。
MATCH_ALL(chunks, $[has_code] == true)
對於空的 StructArray，MATCH_ALL 會傳回true 。
若 StructArray 中滿足該謂詞的元素個數大於或等於 xml-ph-0001@deepl.internal，則 MATCH_LEAST
MATCH_LEAST 若滿足該謂詞的元素個數大於或等於threshold ，則true 的評估結果為 。
MATCH_LEAST(chunks, $[quality_score] > 0.9, threshold=2)
對於MATCH_LEAST ，threshold 必須為正整數。
MATCH_MOST
MATCH_MOST 若滿足該謂詞的元素個數小於或等於threshold ，則評估結果為true 。
MATCH_MOST(chunks, $[has_code] == true, threshold=1)
對於MATCH_MOST ，threshold 可以是零或正整數。
MATCH_EXACT
MATCH_EXACT 若滿足該謂詞的元素個數恰好等於threshold ，則true 的評估結果為 。
MATCH_EXACT(chunks, $[section] == "filter", threshold=1)
對於MATCH_EXACT ，threshold 可以是零或正整數。
受支援的謂詞
$[...] 語法代表當前 Struct 元素的標量值。敘述子是否受支援取決於標量子欄位的類型。
| 子欄位類型 | 元素層級的謂詞支援 |
|---|---|
BOOL | 如$[has_code] == true 或!($[has_code] == true) 等標量謂詞。請避免使用如$[has_code] 這類未加引號的布林表達式。 |
INT8、INT16 、INT32 、INT64 | 比較運算、鏈式範圍、in 、not in 、包含+ 、- 、* 、/ 或% 並後接比較運算的算術表達式，以及邏輯組合。 |
FLOAT,DOUBLE | 比較、鏈式範圍、in 、not in 、以+ 、- 、* 或/ 開頭並後接比較運算的算術表達式，以及邏輯組合。% 運算子不適用於浮點數子欄位。 |
VARCHAR | 字串比較、鏈式範圍、in 、not in 、like 、=~ 、!~ 以及邏輯組合。 |
| 向量子欄位 | 不支援作為$[...] 標量謂詞的輸入。請改用 EmbeddingList 搜尋或元素層級向量搜尋來處理向量子欄位。 |
邏輯運算子（例如&& 、\|\| 及! ）適用於謂詞表達式。例如，請寫作!($[has_code] == true) 而非!$[has_code] 。
不支援的謂詞
元素層級的$[...] 謂詞不支援：
文字比對函式，例如
text_match(field, "...")或phrase_match(field, "...")。JSON 路徑語法、針對 JSON 路徑的
exists，或 JSON 函式（例如json_contains、json_contains_all或json_contains_any）。陣列容器函式，例如
array_contains、array_contains_all、array_contains_any或array_length。$[subfield] is null或$[subfield] is not null。幾何／GIS 函數。
timestamptz 表達式。
random_sample(...).欄位層級的向量判別式。
通用篩選函數呼叫，除非特定函數的簽名與執行路徑明確支援 StructArray 元素層級的謂詞。
語法規則
MATCH_*運算子名稱不區分大小寫。僅在
element_filter或MATCH_*謂詞中使用$[subfield]。請勿將 `
$[subfield]` 用作 JSON 路徑、陣列容器或向量欄位參考。請勿將 `
element_filter` 或 `MATCH_*` 嵌套在另一個 `StructArray` 運算子之中。請使用命名過的
threshold=N來表示MATCH_LEAST、MATCH_MOST以及MATCH_EXACT。MATCH_ANY若對空的 StructArray 進行操作，則會傳回false。MATCH_ALL對空的 StructArray 呼叫時，會傳回true。
