バッチCortex Search¶

バッチCortex Search関数は、クエリのバッチをCortex Search Serviceに送信できるテーブル関数です。エンティティの解決、重複排除、またはクラスタリングタスクなど、高いスループット要件を伴うオフラインのユースケースを対象としています。

:code:`CORTEX_SEARCH_BATCH`関数を使用してCortex Search Serviceに送信されたジョブは、追加のコンピューティングリソースを活用して、インタラクティブ（Python、REST、またはSEARCH_PREVIEW）なAPI検索クエリのインターフェースよりも非常に高いスループット（1秒あたりのクエリ数）を提供します。

構文¶

:code:`CORTEX_SEARCH_BATCH`テーブル関数を使用してバッチモードでCortex Search Serviceをクエリするには、次の構文を使用します。

SELECT
    q.query,
    r.*
FROM query_table AS q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => '<database>.<schema>.<cortex_search_service>',
    query => q.query,                   -- optional STRING
    multi_index_query => q.miq,         -- optional VARIANT
    filter => q.filter,                 -- optional VARIANT
    limit => 10,                        -- optional INT
    options => q.options                -- optional VARIANT
) AS r;

パラメーター¶

``CORTEX_SEARCH_BATCH``関数は以下のパラメーターをサポートしています。

service_name （文字列、必須）

クエリするCortex Search Serviceの完全修飾名。

``query``（文字列、オプション）

サービスを検索するためのクエリ文字列を含む列。

``multi_index_query``（バリアント、オプション）

サービスインデックスに対して検索を実行する1つ以上のベクトルまたはキーワードクエリ入力を指定するオブジェクト。このパラメーターを構築する方法について詳しくは、:ref:`multi_index_query<label-cortex_multi_index_search>`を参照してください。

注釈

パフォーマンス上の理由により、``multi_index_query``は現在、クエリ配列内で最大1つのベクトルインデックスエントリのみをサポートしています。

``filter``（バリアント、オプション）

検索結果に適用するフィルターオブジェクトを含む列。

``limit``（整数、オプション）

クエリごとに返す結果の最大数。デフォルト：10

``options``（バリアント、オプション）

オプションのクエリごとの設定を含む VARIANT オブジェクトを含む列。サポートされているトップレベルのキーは次のとおりです。

scoring_config （オブジェクト、オプション）:インタラクティブなCortex Searchクエリの scoring_config パラメーターと同じ構造（Python、 REST または SEARCH_PREVIEW）これを使用して、その行のバッチクエリのランキングをカスタマイズします。Cortex Searchスコアリングのカスタマイズをご参照ください。
``replicas``（整数、オプション）検索インデックスのコピーの数。その行のバッチクエリに対応。デフォルト：値なし。2.値が大きいと、スループットが向上します。サービングコストはレプリカ数に比例して増加します。
experimental （オブジェクト、オプション）:実験的またはプレビュー検索動作のために予約されているオブジェクト。フィールドとセマンティクスは警告なしに変更される場合があります。Snowflakeのドキュメントまたはサポートから、特定のキーを設定するように指示された場合にのみ使用します。

注釈

query、multi_index_query、または``filter``のうち少なくとも1つを指定する必要があります。

使用上の注意¶

バッチ検索関数のスループットは、クエリされたCortex Search Serviceでインデックス化されたデータの量と、検索クエリの複雑さによって異なる場合があります。特定のワークロードのスループットを測定するために、少数のクエリで関数を実行します。一般的に、比較的多くのフィルター条件が使用されている大規模なサービスへのクエリでは、スループットが低くなります。
バッチ検索関数のスループット（1秒あたりに処理される検索クエリの数）は、クエリに使用されるウェアハウスのサイズの影響を受けません。
バッチ検索は各ジョブを処理するために専用のリソースを起動するため、追加の起動レイテンシが発生します。2,000件未満のクエリを実行する必要がある場合は、通常、バッチ検索よりもインタラクティブなCortex Search API（PythonまたはREST API）を使用する方が早く結果を得られます。
インタラクティブなCortex Search APIとは異なり、バッチ検索関数は現在提供が一時停止されているサービスもクエリできます。
インタラクティブクエリのパフォーマンスやスループットを低下させることなく、単一のCortex Search Serviceをインタラクティブモードとバッチモードで同時にクエリできます。これは、インタラクティブクエリとバッチクエリの処理には、別々のコンピューティングリソースが使用されているためです。

コストの考慮事項¶

バッチ検索には次の3つのコスト構成要素があります。

サービングコスト: 検索インデックスデータのサイズとバッチ検索ジョブの時間（起動時間を除く）に基づく料金。また、 options の replicas の値（デフォルト2）も反映します。上記の replicas オプションを参照してください。
クエリの埋め込みコスト: 入力クエリの結果として埋め込まれたトークンの数に対する料金。インタラクティブなCortex Searchとは異なり、バッチ検索ではクエリの埋め込みは無料ではありません。
仮想ウェアハウスのコスト: バッチジョブの実行に使用されるバーチャルウェアハウスコンピューティングに対する料金。

使用状況の追跡については、:doc:`CORTEX_SEARCH_BATCH_QUERY_USAGE_HISTORY</sql-reference/account-usage/cortex_search_batch_query_usage_history>`のアカウント使用状況ビューを参照してください。Cortex Searchのコストについて詳しくは、:ref:`label_cortex_search_cost_considerations`を参照してください。

リージョンの可用性¶

バッチ検索は、Cortex Searchが利用可能なすべての地域で利用できます。サポート対象の地域の完全なリストについては、:ref:`label-cortex_search_overview_regional_availability`を参照してください。

使用例¶

この例では、ユーザーが送信した注文フォームの製品を「ゴールデン」製品カタログと照合します。CORTEX_SEARCH_BATCH 呼び出しは options を使用するため、埋め込みはデフォルトの検索クエリプレフィックスなしで計算されます。ベクトル埋め込み用クエリプレフィックスの無効化をご参照ください。その設定は、結果品質への影響を評価した場合にのみ使用してください。

-- Create the golden product catalog with canonical product names
CREATE OR REPLACE TABLE golden_catalog (product_name TEXT);
INSERT INTO golden_catalog VALUES
  ('Wireless Bluetooth Headphones'),
  ('Wireless Noise-Canceling Earbuds'),
  ('USB-C Charging Cable 6ft'),
  ('Portable Power Bank 10000mAh');

-- Create Cortex Search Service on the golden catalog
CREATE CORTEX SEARCH SERVICE golden_product_service
ON product_name
WAREHOUSE = <warehouse_name>
TARGET_LAG = '1 day'
AS
SELECT product_name FROM golden_catalog;

-- Create a table of user-submitted products (may contain variations or typos)
CREATE OR REPLACE TABLE submitted_products (product TEXT);
INSERT INTO submitted_products VALUES
  ('bluetooth headphones wireless'),
  ('usb c cable');

-- For each user-submitted product, query the service for the two closest golden results
SELECT
  q.product, s.*
FROM submitted_products AS q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => 'golden_product_service',
    query => q.product,
    limit => 2,
    options => OBJECT_CONSTRUCT(
        'scoring_config', OBJECT_CONSTRUCT(
            'disable_vector_embedding_query_prefix', true
        )
    )
) AS s;

次の例では、``multi_index_query``を使用して、生のテキストではなく、事前に計算された埋め込みをクエリ入力として送信します。ソーステーブル``my_db.my_schema.product_embeddings``には事前計算されたベクトルを持つ列``embedding``が含まれており、Cortex Search Service ``my_db.my_schema.golden_product_service``は独自のベクトルを使用する（BYOV）構成で作成されています。``multi_index_query``の構築の詳細については、:ref:`multi_index_query<label-cortex_multi_index_search>`を参照してください。

SELECT
    q.product_name,
    s.*
FROM (
    SELECT
        product_name,
        embedding::ARRAY AS emb_arr
    FROM my_db.my_schema.product_embeddings
    LIMIT 100000
) q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => 'my_db.my_schema.golden_product_service',
    multi_index_query => OBJECT_CONSTRUCT(
        'EMBEDDING', ARRAY_CONSTRUCT(
            OBJECT_CONSTRUCT('vector', q.emb_arr)
        )
    ),
    limit => 5
) s;