Cortex Search Serviceにクエリする¶

Python API¶

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

pip install snowflake -U

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)

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

条件:

• <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> `_ リファレンスをご参照ください。

SQLSEARCH_PREVIEW 関数¶

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

使用上の注意¶

• ソースクエリの ``NaN``（「非数値」）値との一致は、 :doc:` 特別な価値 </sql-reference/data-types-numeric>` で説明されているように処理されます。

• 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

数値ブーストと時間減衰¶

数値やタイムスタンプのメタデータに基づいて、検索結果をブーストしたり、減衰を適用したりすることができます。この機能は、クエリ時にドキュメントの関連性を判断するのに役立つ、結果ごとの構造化されたメタデータ（例えば、人気度や新着度のシグナル）がある場合に便利です。クエリ作成時に2つのカテゴリを指定できます：

ブーストと減衰のメタデータは、 Cortex Search Serviceが作成されるソーステーブルの列から取得されます。クエリを作成するときに、ブーストまたは減衰に使用するメタデータ列を指定しますが、それらの列はCortex Searchサービスを作成するときに含める必要があります。

ブーストまたは減衰を使用したサービスのクエリ

Cortex Search Serviceをクエリする際、ブーストまたは減衰に使用する列をオプションの numeric_boosts、 time_decays、 scoring_config.functions フィールドで指定します。また、ブーストや減衰ごとにウェイトを指定することもできます。

{
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {
          "column": "<column_name>",
          "weight": <weight>
        },
        // ...
      ],
      "time_decays": [
        {
          "column": "<column_name>",
          "weight": <weight>,
          "limit_hours": <limit_hours>
        },
        // ...
      ]
    }
  }
}

プロパティ:

• numeric_boosts (配列、オプション):

  • <numeric_boost_object > (オブジェクト、オプション):

    • column_name (string): ブーストを適用する列を数値で指定します。

    • weight (float): ランキング処理において、ブーストされた列に割り当てられる重みまたは重要度を指定します。複数の列が指定されている場合、ウェイトが高いほどフィールドの影響が大きくなります。

• time_decays (配列、オプション):

  • <time_decay_object> (オブジェクト、オプション):

    • column_name (string): 減衰を適用する時間列または日付列を指定します。

    • weight (float): 順位付けプロセスにおいて、減衰した列に割り当てられる重みまたは重要度を指定します。複数の列が指定されている場合、ウェイトが高いほどフィールドの影響が大きくなります。

    • limit_hours (float): 時間がドキュメントの関連性や重要性に影響を与えなくなる境界をセットします。例えば、 limit_hours の値が240の場合、 now のタイムスタンプから240時間（10日）以上過去のタイムスタンプを持つドキュメントは大幅なブーストを受けず、直近240時間以内のタイムスタンプを持つドキュメントはより大幅なブーストを受ける必要があることを示します。

    • now (文字列、オプション): ISO-8601 形式 yyyy-MM-dd'T'HH:mm:ss.SSSXXX で減衰を計算するリファレンスタイムスタンプ。例えば、 "2025-02-19T14:30:45.123-08:00" です。指定がない場合、デフォルトは現在のタイムスタンプです。

再ランキング¶

デフォルトでは、Cortex Search Serviceへのクエリは、 セマンティック・リランキング を活用し、検索結果の関連性を向上させます。再ランキングはクエリ結果の関連性を著しく向上させますが、クエリの待ち時間も著しく増加させます。ビジネスユースケースにおいて、クエリの高速化のために、リランキングが提供する品質の利点を犠牲にできることがわかった場合、どのCortex Searchクエリでもリランキングを無効にすることができます。

リランカーなしでCortex Search Serviceをクエリする

クエリ時に scoring_config.reranker フィールドで、以下の形式で個々のクエリのリランカーを無効にすることができます。

{
  "scoring_config": {
      "reranker": "none"
}

プロパティ:

• reranker (文字列、オプション): リランカーをオフにする場合は "none" をセットするパラメーター。除外されているかNULLの場合、デフォルトのリランカーが使用されます。

所有者権限でのクエリ¶

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

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

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

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

例のセットアップ：¶

以下の例では、タイムスタンプと数値列でさまざまな機能をすために、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;

フィルターの例¶

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES"],
  "filter": {"@eq": {"REGION": "US"}},
  "limit": 5
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES"],
         "filter": {"@eq": {"REGION": "US"}},
         "limit": 5
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "business",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "filter": {"@and": [
    {"@gte": {"LIKES": 50}},
    {"@lte": {"COMMENTS": 50}}
  ]},
  "limit": 10
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "business",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "filter": {"@and": [
           {"@gte": {"LIKES": 50}},
           {"@lte": {"COMMENTS": 50}}
         ]},
         "limit": 10
      }'
  )
)['results'] as results;

スコアリングの例¶

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}
            ]
        }
    }
)

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {"column": "comments", "weight": 2},
        {"column": "likes", "weight": 1}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "scoring_config": {
           "functions": {
             "numeric_boosts": [
               {"column": "comments", "weight": 2},
               {"column": "likes", "weight": 1}
             ]
           }
         }
      }'
  )
)['results'] as results;

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"}
            ]
        }
    }
)

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "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"}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "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"}
             ]
           }
         }
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  "scoring_config": {
    "reranker": "none"
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
         "scoring_config": {
           "reranker": "none"
         }
      }'
  )
)['results'] as results;