Cortex Search Serviceにクエリする¶

Snowflake Python APIs ライブラリのインストール¶

まず、最新版の Snowflake Python APIs パッケージを PyPI からインストールします。PyPI からこのパッケージをインストールする手順については、 Snowflake Python APIs ライブラリのインストール をご参照ください。

pip install snowflake -U

Snowflakeに接続する¶

Snowpark Session またはPython Connector Connection のいずれかを使用してSnowflakeに接続し、 Root オブジェクトを作成します。Snowflakeへの接続方法については、 Snowflake Python APIs による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)

サービスをクエリする¶

以下の構文でサービスをクエリします。

# 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())

パラメーター¶

REST API 認証の構成¶

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

サービスをクエリする例¶

curl:を使ってサービスにクエリするには

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": "<search_query>",
  "columns": ["col1", "col2"],
  "filter": <filter>
  "limit": <limit>
}'

例¶

次の例では、 preview query のクエリ文字列でサービスをプレビューし、結果を VARIANT オブジェクトにパースしています。

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'my_search_service',
      '{
         "query": "preview query",
         "columns":[
            "col1",
            "col2"
         ],
         "filter": {"@eq": {"col1": "filter value"} },
         "limit":10
      }'
  )
)['results'] as results;

例¶

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

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

  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": "val1" } },
        { "@contains": { "array_col": "val1" } }
    ]
  }
  

  Copy

ブーストシグナルまたは減衰シグナルを含むサービスのクエリ¶

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の作成

この例では、 business_documents というテーブルを使用しています。 last_modified, created_timestamp という2つのタイムスタンプ列と、 likes, columns という2つの整数列があり、検索結果のブーストと減衰に使用できます。

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. Highlights include strategic investments in marketing and technology.',
     '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 and software guides and commonly asked tech questions.',
     '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 initiatives. Includes new guidelines on hybrid working models.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch. Detailed plans for social media, influencer partnerships, and content creation.',
     '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 of new features, bug fixes, and performance improvements.',
     '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 evaluations, set goals, and provide constructive feedback.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

次に、 business_documents テーブルの document_contents 列に business_documents_css というCortex Search Serviceを作成します。

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

数値ブーストでサービスにクエリ

以下のクエリは、 likes と comments 列の両方に数値ブーストを適用し、 likes の値に対する comments の値のブーストウェイトを2倍にしています。このクエリは SQL SEARCH_PREVIEW 関数 を使って「テクノロジー」を検索します。

SELECT
    index,
    value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
    value['LIKES']::int as LIKES,
    value['COMMENTS']::int as COMMENTS,
FROM TABLE(FLATTEN(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'] ))

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

• クエリ "technology" との関連性は若干低いものの、「いいね！」とコメントが大容量であるため、ブーストを使用すると、 "Product roadmap 2024:..." のドキュメントがトップ結果になります。

• ブーストなしで、クエリのトップ結果は "IT manual for employees:..." です。

時間減衰を利用したサービスのクエリ

以下のクエリは、 LAST_MODIFIED_TIMESTAMP 列に基づいて時間減衰を適用します。

• now のタイムスタンプに対して、より新しい LAST_MODIFIED_TIMESTAMP の値を持つドキュメントがブーストされます。

• now タイムスタンプから240時間を超える LAST_MODIFIED_TIMESTAMP 値を持つドキュメントは、ほとんどブーストされません。

SELECT
  value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
  value['LAST_MODIFIED_TIMESTAMP']::timestamp as LAST_MODIFIED_TIMESTAMP
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP", "CREATED_TIMESTAMP", "LIKES", "COMMENTS"],
      "scoring_config": {
          "functions": {
              "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
              ]
            }
        }
    }'
))['results'] ));

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

• 減衰では、 "Product roadmap 2024:..." のドキュメントが、クエリ "technology" との関連性が若干低いにもかかわらず、 now のタイムスタンプに最新であるため、トップの結果となります。

• 減衰がない場合、クエリのトップ結果は "IT manual for employees:..." になります。

リランカーなしでCortex Search Serviceをクエリします。¶

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

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

プロパティ:

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

例¶

リランカーを使わない検索サービスへのクエリ（Python）

次のコードは、 Python API を使用して、再ランキングステップなしでサービスにクエリします：

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

リランカーなしでサービスにクエリ (SQL)

次の SQL ステートメントは、 SEARCH_PREVIEW 関数 を使用して、リランキングステップなしでサービスをクエリします。

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

所有者権限でのクエリ¶

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

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

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

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