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 个Struct元素满足该谓词。 |
MATCH_EXACT(field, predicate, threshold=N) | 恰有N 个Struct元素满足该谓词。 |
MATCH_ANY element_filter 均可表示至少有一个 Struct 元素满足该谓词。当仅需行级过滤时，请使用 。当需要元素级约束时（例如过滤哪些 Struct 元素参与元素级向量搜索），请使用 。MATCH_ANY 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 。
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_contains、json_contains_all或json_contains_any等JSON函数。数组容器函数，例如
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。
