StructArray 演算子
StructArray演算子は、StructArrayフィールド内のスカラーサブフィールドに対して述語を評価することで、エンティティをフィルタリングします。このページは、element_filter およびMATCH_* 演算子ファミリーの構文リファレンスとしてご利用ください。
StructArrayのフィルタリングには、2つの演算子ファミリーがあります：
| 演算子ファミリー | 主な目的 | 結果の挙動 |
|---|---|---|
element_filter | スカラー述語を満たすStruct要素に一致させます。 | 要素レベルの検索では、一致したヒットに要素のオフセットが含まれる場合があります。行レベルのクエリまたはフィルタリング検索では、結果の形状はAPIおよび出力フィールドによって異なります。 |
MATCH_* | スカラー述語を満たす Struct 要素の数に基づいてエンティティを選択します。 | 行レベルのフィルタリング。これらの演算子は、それ自体では要素オフセットを返しません。 |
StructArray 演算子では、スカラーサブフィールドを使用します。ベクトルサブフィールドはベクトル検索パスで使用され、スカラー述語の入力にはなりません。
どの演算子をいつ使用するか
| 目的 | 使用方法 |
|---|---|
| 要素レベルのベクトル検索を、スカラー条件に一致する要素に限定する。 | element_filter |
| 同じ Struct 要素内で複数のスカラー条件に一致させる。 | element_filter |
| 少なくとも1つの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 は、フィルタ式内で1回のみ使用できます。element_filter やMATCH_* を、別のelement_filter の内部にネストしないでください。
マッチファミリー演算子
MATCH_* 演算子は、述語を満たすStruct要素の数に基づいてエンティティを選択する必要がある場合に使用します。
| 演算子 | 意味 |
|---|---|
MATCH_ANY(field, predicate) | 少なくとも 1 つの 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 はどちらも、少なくとも 1 つの Struct 要素が述語を満たすことを表現できます。行レベルのフィルタリングのみが必要な場合は、MATCH_ANY を使用してください。要素レベルの制約（たとえば、要素レベルのベクトル検索に参加する Struct 要素のフィルタリングなど）が必要な場合は、element_filter を使用してください。
MATCH_ANY
MATCH_ANY StructArray内の少なくとも1つの要素が述語を満たす場合、true として評価されます。
MATCH_ANY(chunks, $[section] == "index")
StructArrayが空の場合、MATCH_ANY はfalse を返します。
MATCH_ALLは、StructArray内のすべての要素が述語を満たす場合、xml-ph-0000@deepl.internalを返します。
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は、述語を満たす要素の数が xml-ph-0001@deepl.internal 以下の場合、xml-ph-0000@deepl.internal と評価されます。
MATCH_MOST は、述語を満たす要素の数がthreshold 以下である場合に、true と評価されます。
MATCH_MOST(chunks, $[has_code] == true, threshold=1)
MATCH_MOST の場合、threshold は 0 または正の整数です。
MATCH_EXACT
MATCH_EXACT は、述語を満たす要素の数がthreshold と正確に等しい場合、true と評価されます。
MATCH_EXACT(chunks, $[section] == "filter", threshold=1)
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 、=~ 、!~ 、および論理演算の組み合わせ。 |
| ベクトルサブフィールド | $[...] のスカラー述語の入力としてはサポートされていません。代わりに、EmbeddingList検索または要素レベルのベクトル検索を通じてベクトルサブフィールドを使用してください。 |
&& 、\|\| 、! などの論理演算子は、述語式に適用されます。たとえば、!$[has_code] の代わりに!($[has_code] == true) と記述します。
サポートされていない述語
要素レベルの$[...] 述語では、以下はサポートされていません：
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_*演算子の名前は大文字と小文字を区別しません。$[subfield]は、element_filterまたはMATCH_*述語内でのみ使用してください。$[subfield]を JSON パス、配列コンテナ、またはベクトルフィールドの参照として使用しないでください。element_filterやMATCH_*を、別の StructArray 演算子の内部にネストしないでください。MATCH_LEAST、MATCH_MOST、およびMATCH_EXACTには、名前付きthreshold=Nを使用してください。MATCH_ANY空の StructArray に対して呼び出すと、falseを返します。MATCH_ALL空の StructArray に対して呼び出すと、trueを返します。
