跳到主要内容
版本：v3.0.x

StructArray Operators

StructArray operators 通过评估 StructArray 字段内标量子字段上的谓词来过滤实体。本页可作为 element_filter 和 MATCH_* operator family 的语法参考。

StructArray filtering 包含两个 operator family：

Operator family主要用途结果行为
element_filter匹配满足标量谓词的 Struct 元素。在 element-level search 中，匹配命中可以包含元素偏移量。在 row-level query 或 filtered search 中，结果形态取决于 API 和输出字段。
MATCH_*根据满足标量谓词的 Struct 元素数量选择实体。Row-level filtering。这些运算符本身不会返回元素偏移量。

在 StructArray operators 中使用标量子字段。向量子字段用于向量搜索路径，不作为标量谓词输入。

何时使用哪个 Operator​

目标使用
将元素级向量搜索限制在符合标量条件的元素上。element_filter
在同一个 Struct 元素内匹配多个标量条件。element_filter
仅返回至少有一个 Struct 元素满足谓词的 Entity。MATCH_ANY
仅返回所有 Struct 元素都满足谓词的 Entity。MATCH_ALL
仅返回至少、至多或恰好 N 个 Struct 元素满足谓词的 Entity。MATCH_LEAST、MATCH_MOST 或 MATCH_EXACT

Element Filter​

使用 element_filter(structArrayField, predicate) 匹配 StructArray 字段中的 Struct 元素。

在 predicate 中，使用 $[subfield] 引用当前 Struct 元素的标量子字段。

Text
element_filter(chunks, $[section] == "index")
Text
element_filter(chunks, $[text] LIKE "Red%")

在 predicate 中使用多个条件时，所有 $[subfield] 引用都作用于同一个 Struct 元素：

Text
element_filter(chunks, $[section] == "index" && $[quality_score] > 0.9)

当你将实体级 predicate 与 element_filter 组合使用时，请将 element_filter 放在表达式末尾：

Text
# Correct
category == "index" && element_filter(chunks, $[quality_score] > 0.9)

# Incorrect
element_filter(chunks, $[quality_score] > 0.9) && category == "index"
Text
# correct
id > 0 && element_filter(chunks, $[x] > 1)

# incorrect, resulting errors
element_filter(chunks, $[x] > 1) && id > 0

element_filter 在一个过滤表达式中只能出现一次。不要在另一个 element_filter 中嵌套 element_filter 或 MATCH_*。

Match Family Operators​

当需要根据有多少 Struct 元素满足某个 predicate 来选择 Entity 时，使用 MATCH_* 运算符。

运算符含义
MATCH_ANY(field, predicate)至少一个 Struct 元素满足该 predicate。
MATCH_ALL(field, predicate)所有 Struct 元素都满足该 predicate。
MATCH_LEAST(field, predicate, threshold=N)至少 N 个 Struct 元素满足该 predicate。
MATCH_MOST(field, predicate, threshold=N)最多 N 个 Struct 元素满足该 predicate。
MATCH_EXACT(field, predicate, threshold=N)恰好 N 个 Struct 元素满足该 predicate。

MATCH_ANY 和 element_filter 都可以表达至少一个 Struct 元素满足某个 predicate。仅需要行级过滤时，使用 MATCH_ANY。需要元素级约束时，使用 element_filter，例如过滤哪些 Struct 元素参与元素级向量搜索。

MATCH_ANY​

如果 StructArray 中至少有一个元素满足谓词，MATCH_ANY 的计算结果为 true。

Text
MATCH_ANY(chunks, $[section] == "index")
Text
MATCH_ANY(chunks, $[text] LIKE 'Red%')

对于空的 StructArray，MATCH_ANY 返回 false。

MATCH_ALL​

如果 StructArray 中的每个元素都满足谓词，MATCH_ALL 的求值结果为 true。

Text
MATCH_ALL(chunks, $[has_code] == true)

对于空的 StructArray，MATCH_ALL 返回 true。

Text
MATCH_ALL(chunks, $[text] LIKE 'Red%')

MATCH_LEAST​

如果满足谓词的元素数量大于或等于 threshold，MATCH_LEAST 的计算结果为 true。

Text
MATCH_LEAST(chunks, $[quality_score] > 0.9, threshold=2)
Text
MATCH_LEAST(chunks, $[text] LIKE 'Red%', 3)

对于 MATCH_LEAST，threshold 必须是正整数。

MATCH_MOST​

如果满足谓词的元素数量小于或等于 threshold，MATCH_MOST 的求值结果为 true。

Text
MATCH_MOST(chunks, $[has_code] == true, threshold=1)
Text
MATCH_MOST(chunks, $[text] LIKE 'Red%', 3)

对于 MATCH_MOST，threshold 可以为 0 或正整数。

MATCH_EXACT​

如果满足谓词的元素数量恰好等于 threshold，MATCH_EXACT 的计算结果为 true。

Text
MATCH_EXACT(chunks, $[section] == "filter", threshold=1)
Text
MATCH_EXACT(chunks, $[text] LIKE 'Red%', 3)

对于 MATCH_EXACT，threshold 可以为 0 或正整数。

支持的谓词​

$[...] 语法表示当前 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、=~、!~，以及逻辑组合。
Vector 子字段不支持作为 $[...] 标量谓词输入。请改用 EmbeddingList search 或元素级 vector search 使用 vector 子字段。

&&、\|\| 和 ! 等逻辑运算符适用于谓词表达式。例如，应写作 !($[has_code] == true)，而不是 !$[has_code]。

不支持的谓词​

元素级 $[...] 谓词不支持：

  • 文本匹配函数，例如 text_match(field, "...") 或 phrase_match(field, "...")。

  • JSON path 语法、JSON path 上的 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。

  • Geometry / GIS 函数。

  • Timestamptz 表达式。

  • random_sample(...)。

  • 字段级向量谓词。

  • 通用过滤函数调用，除非特定函数签名和执行路径明确支持 StructArray 元素级谓词。

Syntax rules​

  • MATCH_* 运算符名称不区分大小写。

  • 仅在 element_filter 或 MATCH_* 谓词中使用 $[subfield]。

  • 不要将 $[subfield] 用作 JSON path、array 容器或 vector field 引用。

  • 不要在另一个 StructArray 运算符中嵌套 element_filter 或 MATCH_*。

  • 对于 MATCH_LEAST、MATCH_MOST 和 MATCH_EXACT，使用具名参数 threshold=N。

  • 对空 StructArray 使用 MATCH_ANY 会返回 false。

  • 对空 StructArray 使用 MATCH_ALL 会返回 true。

另请参阅​