Cortex Search Serviceにクエリする

Cortex Search Serviceを作成すると、システムは低レイテンシでクエリを処理する API エンドポイントを用意します。Cortex Search Serviceをクエリするために3つの APIs を使用できます:

  • Python API

  • REST API

  • :ref:`SQL SEARCH_PREVIEW 関数 <label-cortex_search_query_syntax_sql_preview>

パラメーター

すべての APIs で同じクエリパラメーターのセットをサポートします。

パラメーター

説明

必須

query

サービスのテキスト列で検索される検索クエリ。

オプション

columns

カンマ区切りのリストで、応答内の関連する結果ごとに返す列を指定します。これらの列は、サービスのソースクエリに含まれている必要があります。このパラメーターが提供されない場合は、応答で検索列のみが返されます。

filter

ATTRIBUTES 列のデータに基づいて結果をフィルタリングするためのフィルターオブジェクト。構文については フィルター構文 をご参照ください。

scoring_config

検索ランキングの動作をカスタマイズするための構成オブジェクト。構文については、 Cortex Searchスコアリングのカスタマイズ をご参照ください。

scoring_profile

ALTER CORTEX SEARCH SERVICE ... ADD SCORING PROFILE で定義された、クエリで使用される名前付きスコアリングプロファイル。scoring_profile が提供された場合、すべての提供された scoring_config は無視されます。

limit

応答で返す結果の最大数。最大1000。デフォルトの上限は10。

構文

次の例は、3つのサーフェスすべてを使用してCortex Search Serviceにクエリ方法を示しています。

import os
from snowflake.core import Root
from snowflake.snowpark import Session

# connect to Snowflake
CONNECTION_PARAMETERS = { ... }
session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)

# fetch service
my_service = (root
    .databases["<service_database>"]
    .schemas["<service_schema>"]
    .cortex_search_services["<service_name>"]
)

# query service
resp = my_service.search(
    query="<query>",
    columns=["<col1>", "<col2>"],
    filter={"@eq": {"<column>": "<value>"} },
    limit=5
)
print(resp.to_json())
Copy

設定と認証

Python API

Cortex Search Serviceのクエリは、バージョン0.8.0以降の Snowflake Python APIs を使用して行えます。Snowflake Python APIsの詳細情報については Snowflake Python APIs:PythonによるSnowflakeオブジェクトの管理 をご参照ください。.

Snowflake Python API ライブラリをインストールする

まず、PyPI からSnowflake Python APIs パッケージの最新バージョンをインストールします。PyPI からこのパッケージをインストールする手順については :doc:` インストールSnowflake PythonAPIs ライブラリ </developer-guide/snowflake-python-api/snowflake-python-installing>` をご参照ください。

pip install snowflake -U
Copy

Snowflakeに接続する

Snowpark Session またはPython Connector Connection のいずれかを使用してSnowflakeに接続し、 Root オブジェクトを作成します。Snowflake Python APIs を使用してSnowflakeに接続する方法については :doc:` </developer-guide/snowflake-python-api/snowflake-python-connecting-snowflake> をご参照ください。Snowflakeへの接続方法については、` をご参照ください。以下の例では、設定にSnowpark Session オブジェクトとPythonディクショナリを使用しています。

import os
from snowflake.core import Root
from snowflake.snowpark import Session

CONNECTION_PARAMETERS = {
    "account": os.environ["snowflake_account_demo"],
    "user": os.environ["snowflake_user_demo"],
    "password": os.environ["snowflake_password_demo"],
    "role": "test_role",
    "database": "test_database",
    "warehouse": "test_warehouse",
    "schema": "test_schema",
}

session = Session.builder.configs(CONNECTION_PARAMETERS).create()
root = Root(session)
Copy

注釈

Cortex Search Serviceにクエリするには、Snowflake Python APIs ライブラリのバージョン0.8.0以降が必要です。

REST に API

Cortex Searchは、 Snowflake REST APIs のスイートで REST API エンドポイントを公開しています。Cortex Search Service用に生成される REST エンドポイントの構造は以下の通りです。

https://<account_url>/api/v2/databases/<db_name>/schemas/<schema_name>/cortex-search-services/<service_name>:query
Copy

条件:

  • <account_url>:Snowflakeアカウント URL。アカウント URL を見つける手順については 、アカウントの組織名とアカウント名の検索 をご参照ください。

  • <db_name>: サービスが存在するデータベース。

  • <schema_name>: サービスが存在するスキーマ。

  • <service_name>: サービス名。

  • :query:サービスを呼びだすメソッド。この場合は query メソッド。

詳細については、 RESTCortex Search Service API` の <https://docs.snowflake.com/developer-guide/snowflake-rest-api/reference/cortex-search-service> `_ リファレンスをご参照ください。

認証

Snowflake REST APIs は、プログラムのアクセストークン（PATs）による認証、 JSON ウェブトークン（JWTs）を使用したキーペア認証 および OAuth をサポートしています。詳細については、 Snowflakeの認証 REST APIs Snowflakeを使用した をご参照ください

SQLSEARCH_PREVIEW 関数

SNOWFLAKE.CORTEX.SEARCH_PREVIEW 関数により、ワークシートやSnowflakeノートブックのセルなどの SQL 環境内から、Cortex Search Serviceに対する個々のクエリの結果をプレビューすることができます。この関数により、サービスが正しく入力され、妥当な結果を提供していることを簡単に検証できます。

重要

SEARCH_PREVIEW 機能は、Cortex Search Servicesのテストと検証のために提供されます。エンドユーザーアプリケーションで検索クエリを提供するためのものではありません。

  • この関数は文字列リテラルに対してのみ動作します。バッチテキストデータは受け入れません。

  • この関数はRESTや Python APIsよりもレイテンシが高いです。

フィルター構文

Cortex Searchは、CREATE CORTEX SEARCH SERVICE コマンドで指定された ATTRIBUTES 列でのフィルタリングをサポートします。

Cortex Searchは4つのマッチング演算子をサポートしています。

これらのマッチング演算子は、さまざまな論理演算子と組み合わせることができます。

  • @and

  • @or

  • @not

使用上の注意

  • ソースクエリの NaN （「非数値」）値との一致は、 特別な価値 で説明されているように処理されます。

  • 19桁（先頭のゼロを含まない）を超える固定小数点の数値は、 @eq または @gte および @lte では機能せず、これらの演算子によって返されません（ただし、@not を使用すると、クエリ全体で返される可能性があります ）。

  • TIMESTAMP および DATE フィルターは YYYY-MM-DD 、タイムゾーンを考慮した日付の場合 YYYY-MM-DD+HH:MM の形式の値を受け入れます。 タイムゾーンオフセットを指定しない場合、日付は UTC で解釈されます。

  • @primarykey は 主キー で構成されたサービスでのみサポートされます。フィルターの値は、すべての主キー列を対応する値（または NULL）にマッピングする JSON オブジェクトである必要があります。

これらの演算子は1つのフィルターオブジェクトにまとめることができます。

例

  • 文字列のような列 string_col が値 value と等しい行に対するフィルタリング。

    { "@eq": { "string_col": "value" } }
    Copy

  • 指定された主キー値 us-west-1 内の region 列と abc123 内の agent_id 列を持つ行へのフィルタリング：

    { "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
    Copy

  • ARRAY 列 array_col に値 value が含まれる行のフィルタリング。

    { "@contains": { "array_col": "arr_value" } }
    Copy

  • NUMERIC 列 numeric_col が 10.5 から 12.5 (含む) の間の行のフィルター:

    {
  "@and": [
    { "@gte": { "numeric_col": 10.5 } },
    { "@lte": { "numeric_col": 12.5 } }
  ]
}
    Copy

  • TIMESTAMP 列 timestamp_col が 2024-11-19 と 2024-12-19 の間にある行のフィルタリング。

    {
  "@and": [
    { "@gte": { "timestamp_col": "2024-11-19" } },
    { "@lte": { "timestamp_col": "2024-12-19" } }
  ]
}
    Copy

  • 論理演算子でフィルターを構成する

    // Rows where the "array_col" column contains "arr_value" and the "string_col" column equals "value"
{
  "@and": [
    { "@contains": { "array_col": "arr_value" } },
    { "@eq": { "string_col": "value" } }
  ]
}

// Rows where the "string_col" column does not equal "value"
{
  "@not": { "@eq": { "string_col": "value" } }
}

// Rows where the "array_col" column contains at least one of "val1", "val2", or "val3"
{
  "@or": [
    { "@contains": { "array_col": "val1" } },
    { "@contains": { "array_col": "val2" } },
    { "@contains": { "array_col": "val3" } }
  ]
}
    Copy

アクセス制御の要件

Cortex Search Serviceをクエリするロールは、結果を取得するために以下の権限を持っている必要があります。

権限

オブジェクト

USAGE

Cortex Search Service

USAGE

Cortex Search Serviceが存在するデータベース。

USAGE

Cortex Search Serviceが存在するスキーマ。

所有者権限でのクエリ

Cortex Search Serviceは、 所有者権限 で検索を実行し、所有者権限で実行される他のSnowflakeオブジェクトと同じセキュリティモデルに従います。

特に、これは、Cortex Search Serviceにクエリするのに十分な権限を持つロールであれば、サービスのソースクエリで参照される基になるオブジェクト（テーブルやビューなど）に対する権限に関係なく、サービスがインデックスしたデータをクエリできることを意味します。

例えば、行レベルマスキングポリシーを持つテーブルをリファレンスとするCortex Search Serviceでは、クエリユーザーのロールがソーステーブルの行を読めなくても、所有者のロールが読み取り権限を持つ行の検索結果を、クエリユーザーは見ることができます。

例えば、Cortex Search Serviceの USAGE 権限を持つロールを別のSnowflakeユーザーにGrantする場合は注意してください。

既知の制限

Cortex Search Serviceへのクエリには、以下の制限があります：

  • レスポンスサイズ：Cortex Search Serviceへの検索クエリから返されるレスポンスペイロードの合計サイズは、以下の制限を超えてはなりません。

例

このセクションでは、3つの API メソッドすべてにわたってCortex Search Serviceをクエリするための包括的な例を示します。

例のセットアップ：

以下の例では、タイムスタンプと数値列でさまざまな機能をすために、business_documents という名前のテーブルを使用しています。

CREATE OR REPLACE TABLE business_documents (
    document_contents VARCHAR,
    last_modified_timestamp TIMESTAMP,
    created_timestamp TIMESTAMP,
    likes INT,
    comments INT
);

INSERT INTO business_documents (document_contents, last_modified_timestamp, created_timestamp, likes, comments)
VALUES
    ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable.',
     '2024-01-12 10:00:00', '2024-01-10 09:00:00', 10, 20),

    ('IT manual for employees: Instructions for usage of internal technologies, including hardware.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch.',
     '2024-03-15 12:00:00', '2024-03-12 11:15:00', 150, 32),

    ('Product roadmap 2024: Key milestones for tech product development, including the launch.',
     '2024-04-22 17:30:00', '2024-04-20 16:00:00', 200, 45),

    ('Annual performance review process guidelines: Procedures for managers to conduct employee.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

CREATE OR REPLACE CORTEX SEARCH SERVICE business_documents_css
    ON document_contents
    WAREHOUSE = <warehouse_name>
    TARGET_LAG = '1 minute'
AS SELECT * FROM business_documents;
Copy

フィルターの例

等価フィルターを使用した単純なクエリ

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES"],
    filter={"@eq": {"REGION": "US"}},
    limit=5
)
Copy

範囲フィルター

resp = business_documents_css.search(
    query="business",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    filter={"@and": [
        {"@gte": {"LIKES": 50}},
        {"@lte": {"COMMENTS": 50}}
    ]},
    limit=10
)
Copy

スコアリングの例

数値ブースト

お気に入り列とコメント列の両方に数値ブーストを適用し、お気に入り値の値に対するコメント値の2倍の強化重みを適用します。

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    scoring_config={
        "functions": {
            "numeric_boosts": [
                {"column": "comments", "weight": 2},
                {"column": "likes", "weight": 1}
            ]
        }
    }
)
Copy

結果では、以下のことに注目してください。

  • ブーストの効果により、「プロダクトロードマップ 2024」ドキュメントは「技術」というクエリとの関連性が若干低いにもかかわらず、お気に入りおよびコメントの数が多いため、上位の結果になります。

  • ブーストなしでは、クエリの最上位結果は「 従業員向け IT マニュアル:..."」です。

時間は経過します

LAST_MODIFIED_TIMESTAMP 列に基づいて時間減算を適用します。

  • 現在のタイムスタンプから比較して、最新の LAST_MODIFIED_TIMESTAMP 値があるドキュメントは強化されます

  • 現在のタイムスタンプから240時間より大きい LAST_MODIFIED_TIMESTAMP 値を使用したドキュメントはほとんど強化されません

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    scoring_config={
        "functions": {
            "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
            ]
        }
    }
)
Copy

結果では、以下のことに注目してください。

  • 減衰を適用すると、「製品ロードマップ2024:...」ドキュメントは「技術」クエリへの関連性が若干低くなりますが、現在のタイムスタンプへの更新性により上位の結果になります

  • 減衰を適用しない場合、クエリの最上位結果は「従業員向け IT マニュアル:...」です

再ランク付けの無効化

再ランク付けを無効にするには

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    limit=5,
    scoring_config={
        "reranker": "none"
    }
)
Copy

Tip

リランキングはデフォルトの動作であるため、 scoring_config オブジェクトから "reranker": "none" パラメーターを省略し、リランカー で サービスをクエリします。

言語: 日本語