メインコンテンツまでスキップ

StructArray によるフィルター検索

このページでは、StructArray フィールドに対するベクトル検索にスカラーフィルタリングを追加する方法を説明します。StructArray フィルタリングには 2 つのレベルがあります。行レベルのフィルターは親エンティティを選択し、要素レベルのフィルターは、要素レベルのベクトル検索に参加する Struct 要素を制限します。

このページでは、StructArray フィールドを作成する の tech_articles コレクションを使用します。このコレクションには chunks という名前の StructArray フィールドがあり、section、page、quality_score、has_code などのスカラーサブフィールドと、検索用のベクトルサブフィールドがあります。

フィルタータイプを選択する​

目的使用するもの結果の動作
category などのトップレベルのスカラーフィールドでフィルターします。通常のフィルター式。検索の前または検索中に親エンティティを選択します。
要素レベルのベクトル検索を、スカラー条件に一致する Struct 要素に制限します。element_filter。一致する Struct 要素のみを検索し、一致した要素のオフセットを返すことができます。
いずれか、すべて、または指定した数の Struct 要素が述語に一致するかどうかでエンティティを選択します。MATCH_ANY、MATCH_ALL、MATCH_LEAST、MATCH_MOST、または MATCH_EXACT。行レベルのフィルタリングです。これらの演算子自体はオフセットを返しません。
Notes

このページでは、検索ワークフローで StructArray フィルターを使用する方法を説明します。完全な構文ルール、サポートされる述語タイプ、およびサポートされない述語のマトリックスについては、StructArray 演算子 を参照してください。

トップレベルフィールドでフィルターする​

条件が個々の Struct 要素ではなく親エンティティに属する場合は、通常のフィルター式を使用します。これは EmbeddingList 検索と要素レベルの検索の両方で機能します。

python
from pymilvus import MilvusClient
from pymilvus.client.embedding_list import EmbeddingList

client = MilvusClient(
    uri="YOUR_CLUSTER_ENDPOINT",
    token="YOUR_CLUSTER_TOKEN",
)

query = EmbeddingList()
query.add([0.12, 0.21, 0.32, 0.44])
query.add([0.18, 0.23, 0.29, 0.36])

results = client.search(
    collection_name="tech_articles",
    data=[query],
    anns_field="chunks[emb_list_vector]",
    filter='category == "search"',
    limit=3,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
    ],
)

上記のフィルターは、トップレベルの category フィールドが "search" であるエンティティのみを選択します。一致した 1 つの Struct 要素を特定するものではありません。

スカラー条件を、要素レベルのベクトル検索に参加する同じ Struct 要素に適用する必要がある場合は、element_filter(structArrayField, predicate) を使用します。述語内では、$[subfield] を使用して現在の Struct 要素のスカラーサブフィールドを参照します。

python
query_vector = [0.19, 0.24, 0.30, 0.37]

filter_expr = (
    'category == "search" && '
    'element_filter(chunks, '
    '$[section] == "index" && '
    '$[quality_score] > 0.9 && '
    '$[has_code] == true)'
)

results = client.search(
    collection_name="tech_articles",
    data=[query_vector],
    anns_field="chunks[emb]",
    filter=filter_expr,
    limit=5,
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[page]",
        "chunks[quality_score]",
        "chunks[has_code]",
    ],
)

for hits in results:
    for hit in hits:
        print(
            "doc_id:", hit["doc_id"],
            "distance:", hit["distance"],
            "offset:", hit.get("offset"),
            "entity:", hit["entity"],
        )

この例では、トップレベルの述語 category == "search" が候補エンティティを選択し、element_filter が要素レベルのベクトル検索を、section、quality_score、has_code がすべて同じ Struct 要素内で一致するチャンクに制限します。

Warning

トップレベルの述語と element_filter を組み合わせる場合は、element_filter を式の末尾に配置します。フィルター式に含めることができる element_filter は 1 つだけであり、別の StructArray 演算子の中に element_filter または MATCH_* をネストすることはできません。

MATCH 演算子でエンティティをフィルターする​

フィルターが、親エンティティの Struct 要素に基づいてその親エンティティが条件を満たすかどうかを決定する必要がある場合は、MATCH_* 演算子を使用します。これらの演算子は行レベルのフィルターです。エンティティを選択しますが、要素のオフセット自体は返しません。

演算子使用する場合例
MATCH_ANY少なくとも 1 つの Struct 要素が述語を満たす必要があります。MATCH_ANY(chunks, $[section] == "index")
MATCH_ALLすべての Struct 要素が述語を満たす必要があります。MATCH_ALL(chunks, $[quality_score] > 0.5)
MATCH_LEAST少なくとも N 個の Struct 要素が述語を満たす必要があります。MATCH_LEAST(chunks, $[has_code] == true, threshold=2)
MATCH_MOST最大で N 個の Struct 要素が述語を満たす必要があります。MATCH_MOST(chunks, $[section] == "appendix", threshold=1)
MATCH_EXACTちょうど N 個の Struct 要素が述語を満たす必要があります。MATCH_EXACT(chunks, $[section] == "summary", threshold=1)
python
from pymilvus.client.embedding_list import EmbeddingList

query = EmbeddingList()
query.add([0.12, 0.21, 0.32, 0.44])
query.add([0.18, 0.23, 0.29, 0.36])

filter_expr = (
    'category == "search" && '
    'MATCH_ANY(chunks, $[section] == "index" && $[quality_score] > 0.9)'
)

results = client.search(
    collection_name="tech_articles",
    data=[query],
    anns_field="chunks[emb_list_vector]",
    filter=filter_expr,
    limit=3,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

ここでは、EmbeddingList 検索結果がエンティティレベルであるため、MATCH_ANY を使用します。フィルターでは、エンティティ内の少なくとも 1 つのチャンクが高品質の "index" チャンクである必要がありますが、検索結果自体は引き続き親エンティティを表します。

ハイブリッド検索では、条件を適用する場所に StructArray フィルターを適用します。トップレベルのフィルターは、ハイブリッド検索全体で共有できます。element_filter は、要素レベルの制約が必要な StructArray 要素レベルのリクエストにアタッチする必要があります。

python
from pymilvus import AnnSearchRequest, RRFRanker

query_vector = [0.19, 0.24, 0.30, 0.37]

title_req = AnnSearchRequest(
    data=[query_vector],
    anns_field="title_vector",
    param={},
    limit=10,
    expr='category == "search"',
)

chunk_req = AnnSearchRequest(
    data=[query_vector],
    anns_field="chunks[emb]",
    param={},
    limit=10,
    expr='category == "search" && element_filter(chunks, $[section] == "index" && $[quality_score] > 0.9)',
)

results = client.hybrid_search(
    collection_name="tech_articles",
    reqs=[title_req, chunk_req],
    ranker=RRFRanker(),
    limit=5,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

filter 引数はトップレベルのエンティティ条件を適用し、chunk_req の expr は StructArray 要素レベルのベクトルリクエストのみを制限します。サポートされるハイブリッド検索の組み合わせとバージョン固有の制限については、StructArray を使用したハイブリッド検索 および StructArray の制限 を参照してください。

述語のサポート概要​

StructArray の述語ではスカラーサブフィールドを使用します。ベクトルサブフィールドはスカラー述語の入力ではありません。

サブフィールドタイプ述語の一般的な例
BOOL$[has_code] == true, !($[has_code] == true)
整数型$[page] >= 2, $[page] in [1, 2, 3]
FLOAT, DOUBLE$[quality_score] > 0.9, 0.7 < $[quality_score] < 0.95
VARCHAR$[section] == "index", $[text] like "range%"
ベクトルサブフィールド$[...] のスカラー述語入力としてはサポートされません。代わりに、ベクトル検索を通じてベクトルサブフィールドを使用します。

JSON パス、配列コンテナ関数、テキスト一致関数、$[...] に対する null 述語、Geometry 関数、Timestamptz 式、汎用関数呼び出しなど、サポートされないケースについては、StructArray 演算子 を参照してください。

よくある間違い​

  • element_filter または MATCH_* の外で $[subfield] を使用しないでください。

  • element_filter(chunks, $[section] == "index") などの StructArray 演算子構文の代わりに chunks.section を使用しないでください。

  • 行レベルのフィルタリングのみが必要な場合は、element_filter を使用しないでください。エンティティを選択するだけでよい場合は、代わりに MATCH_ANY を使用します。

  • MATCH_* が要素のオフセットを返すと期待しないでください。これらの演算子はエンティティを選択するものであり、単独では一致した 1 つの要素を特定しません。

  • $[has_code] のような裸のブール述語を記述しないでください。$[has_code] == true のような明示的な比較を使用します。

  • 同じフィルター式内で、トップレベルの述語より前に element_filter を配置しないでください。

次のステップ​

  1. StructArray フィルターの完全な構文を確認するには、StructArray 演算子 を参照してください。

  2. 最初にフィルターなしのベクトル検索を実行するには、StructArray を使用した基本的なベクトル検索 を参照してください。

  3. 頻繁に使用する StructArray フィルターのスカラーインデックスを作成するには、StructArray フィールドのインデックス作成 を参照してください。

  4. バージョン固有のフィルターと検索の制限を確認するには、StructArray の制限 を参照してください。

このページは役に立ちましたか？
Ctrl I