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`	A comma-separated list of columns to return for each relevant result in the response. These columns must be included in the source query for the service. このパラメーターが提供されない場合は、応答で検索列のみが返されます。
	`filter`	`ATTRIBUTES` 列のデータに基づいて結果をフィルタリングするためのフィルターオブジェクト。構文についてはフィルター構文をご参照ください。
	`scoring_config`	Configuration object for customizing search ranking behavior. See Customizing Cortex Search scoring for syntax.
	`scoring_profile`	ALTER CORTEX SEARCH SERVICE ... ADD SCORING PROFILE で定義された、クエリで使用される名前付きスコアリングプロファイル。`scoring_profile` が提供された場合、すべての提供された `scoring_config` は無視されます。
	`limit`	Maximum number of results to return in the response, up to 1000. The default limit is 10.

さらに、 SQL およびPython APIs はマルチインデックスクエリをサポートしています。マルチインデックスパラメーターを使用すると、Cortex Searchからの結果を絞り込むことができ、検索される列の数を制限することでクエリコストを削減することができます。

パラメーター	説明
`multi_index_query`	クエリするインデックスを決定するために使用されるマップ。マップの各キーはインデックス付き列の名前で、各値はクエリを定義するマップを含む配列です。インデックスがテキストインデックスまたは管理ベクトルインデックスの場合、クエリ配列には以下を含めることができます。テキストクエリ: `{"text": "search_text"}` 埋め込みベクトルとしてのベクトルクエリ: `{"vector": [vector_values]}` インデックスがユーザー提供のベクトル埋め込み列である場合、クエリ配列には以下を含めることができます。 `query_model` が自動埋め込みの作成時に指定された場合、テキストクエリは `{"text": "search_text"}` になります。埋め込みベクトルとしてのベクトルクエリ: `{"vector": [vector_values]}`

パラメーター

説明

multi_index_query

クエリするインデックスを決定するために使用されるマップ。マップの各キーはインデックス付き列の名前で、各値はクエリを定義するマップを含む配列です。

インデックスがテキストインデックスまたは管理ベクトルインデックスの場合、クエリ配列には以下を含めることができます。
- テキストクエリ: {"text": "search_text"}
- 埋め込みベクトルとしてのベクトルクエリ: {"vector": [vector_values]}
インデックスがユーザー提供のベクトル埋め込み列である場合、クエリ配列には以下を含めることができます。
- query_model が自動埋め込みの作成時に指定された場合、テキストクエリは {"text": "search_text"} になります。
- 埋め込みベクトルとしてのベクトルクエリ: {"vector": [vector_values]}

注釈

マルチインデックスCortex Search Serviceは、引き続き RESTAPI を介して、または multi_index_query パラメーターを使用せずに検索できます。これにより、すべて のインデックス付き列に対して無制限の検索が行われ、クエリコストに影響します。マルチインデックスクエリコンピューティングのコスト見積もりの詳細については、 Cortex Search Serviceのコストについて - マルチインデックス検索をご参照ください。

構文¶

Simple queries to a Cortex Search Service use the following syntax:

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

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>
}'

Copy

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;

Copy

マルチインデックスのクエリ構文¶

特定のインデックスのみをクエリする場合や、マルチインデックスのCortex Search Serviceにベクトル埋め込みを使用するサービスを使用する場合は、以下の構文を使用します。

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

session = Session.builder.configs( {...} ).create()
root = Root(session)

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

resp = my_service.search(
    multi_index_query={
        "<index_name>": [
            {"text": "<search_text>"},
            {"vector": [<vector_values>]},
            ...
        ],
        ...
    },
    scoring_config={
        "weights": {
            "texts": <text_weight>,
            "vectors": <vector_weight>,
            "reranker": <reranker_weight>
        },
        "functions": {
            "vector_boosts": [
                {"weight": <weight>, "column": "<vector_column_name>"},
                ...
            ],
            "text_boosts": [
                {"weight": <weight>, "column": "<text_column_name>"},
                ...
            ]
        }
    },
    columns=["<column_name>", "<column_name>", ...],
    limit=<limit>
)

Copy

SELECT SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      '<service_name>',
      '{
        "multi_index_query": {
          "<index_name>": [
            {"text": "<search_text>"},
            {"vector": [<vector_values>]},
            ...
          ],
          ...
        },
        "columns": ["<column_name>", "<column_name>", ...],
        "limit": <limit>,
        "scoring_config": {
          "weights": {
            "texts": <text_weight>,
            "vectors": <vector_weight>,
            "reranker": <reranker_weight>
          },
          "functions": {
            "vector_boosts": [
              {"weight": <weight>, "column": "<vector_column_name>"},
              ...
            ],
            "text_boosts": [
              {"weight": <weight>, "column": "<text_column_name>"}
              , ...
            ]
          }
        }
      }'
  );

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: The method to invoke on the service; in this case, the query method.

詳細については、 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 関数¶

The SNOWFLAKE.CORTEX.SEARCH_PREVIEW function allows you to preview the results of individual queries to a Cortex Search Service from within a SQL environment such as a worksheet or Snowflake notebook cell. This function makes it easy to interactively validate that a service has populated correctly and is serving reasonable results.

重要

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

The function operates only on string literals. It does not accept batch text data.
この関数は RESTや Python APIsよりもレイテンシが高いです。

フィルター構文¶

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

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

TEXT または NUMERIC 同等: @eq
ARRAY contains: @contains
NUMERIC または DATE/TIMESTAMP 同等またはそれ以上: @gte
NUMERIC または DATE/TIMESTAMP 同等またはそれ以下: @lte
主キー等価: @primarykey

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

@and
@or
@not

使用上の注意¶

Matching against NaN ('not a number') values in the source query is handled as described in 特別な価値.
19桁（先頭のゼロを含まない）を超える固定小数点の数値は、 @eq または @gte および @lte では機能せず、これらの演算子によって返されません（ただし、@not を使用すると、クエリ全体で返される可能性があります）。
TIMESTAMP and DATE filters accept values of the form: YYYY-MM-DD and, for timezone aware dates: YYYY-MM-DD+HH:MM. If the timezone offset is not specified, the date is interpreted in 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

マルチインデックスクエリ¶

CREATE CORTEX SEARCH SERVICE ... TEXT INDEXES ... VECTOR INDEXES 構文を使用してマルチインデックスのCortex Search Serviceとして作成された場合、オプションの multi_index_query パラメーターが使用されます。このパラメーターを省略すると、すべてのインデックスが検索に使用されます。

使用上の注意¶

クエリする各インデックスは、 multi_index_query マップ内でキー値ペアとして表されます。
各クエリでは、少なくとも1つのベクトルインデックスを提供する必要があります。テキストインデックスのみをクエリするとエラーになります。
When querying a multi-index Cortex Search Service, the following behaviors apply:
- フィールドでの AND:ドキュメントが返されるには、クエリされたテキストまたはベクトルフィールドのすべてに一致する必要があります。
- テキストインデックスフィールド内の用語での OR:クエリに「wash hold」などの複数の用語が含まれている場合、ドキュメント内にクエリ用語の いずれか があれば、ドキュメントが返されます。
- テキストクエリは、Snowflakeのカスタムアナライザーを介して、ステミング、レマタイゼーション、ドメイン固有の書き換えを使用して自動的に正規化されます。これにより、「wasing」を「wash」にリンクしたり、「laundromat」を「laundry」にリンクしたりするなど、関連する用語を一致させることでリコールが向上します。
scoring_config.weights フィールドは、指定されたクエリで3つのハイレベルなスコアリング技術（ベクトル、キーワード、再ランク付け）それぞれの相対的な重みを変更します。

このフィールド内では、重みは相互に 相対的 に適用されます。たとえば、 { "texts": 3, "vectors": 2, "reranker": 1 } および { "texts": 30, "vectors": 20, "reranker": 10 } は同等です。
scoring_config.functions.vector_boosts および scoring_config.functions.text_boosts フィールドの使用:
- これらのフィールドでは、ユーザーは特定のクエリ内で、各ベクトルインデックスとテキストインデックスクエリの相対的な重みをそれぞれ変更できます。
- 各フィールド内では、 scoring_config.weights のように重みが相互に適用されます。
マルチインデックスクエリは、数値ブースト、時間減算、および再ランク付けを無効にするクエリと組み合わせることができます。これらの機能の使用に関する情報については、数値ブーストと時間減衰および再ランキングをご参照ください。
マルチインデックスサービスをクエリする場合、 query パラメーターは、サービスにユーザー指定のベクトル埋め込みを持つベクトルインデックスが含まれていない限り、すべてのフィールドに適用されるクエリを指定するために使用できます。
検索のパフォーマンスとレイテンシを最適化するため、ユーザーが指定したベクトルインデックスに対してクエリを発行した場合、ベクトル埋め込みを含む列は結果で返されません。
Snowflakeは、コストに影響するリソースの消費量を削減するために、マルチインデックスCortex Search Serviceで multi_index_query を使用するクエリを絞り込むことを推奨しています。

マルチインデックスのクエリの価格見積もりについては、マルチインデックスCortex Searchのコスト見積もりをご参照ください。

アクセス制御の要件¶

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への検索クエリから返されるレスポンスペイロードの合計サイズは、以下の制限を超えてはなりません。
- REST API および Python API:10メガバイト（MB）
- SQL SEARCH_PREVIEW 関数:300キロバイト（KB）

マルチインデックスCortex Searchには追加の制限が適用されます。これはプレビュー中に変更される可能性があります。

Snowsight UI のCortex Search Playgroundは、マルチインデックスサービスへのクエリをサポートしていません。Playgroundのマルチインデックスサービスに対するクエリは、「検索サービスをクエリできません。無効なリクエストパラメーターまたはフィルター構文です。」というメッセージを表示します。
multi_index_query パラメーターを使用するマルチインデックスサービスクエリ構文は、 Python API のバージョン1.6.0以降でのみサポートされます。

例¶

このセクションでは、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

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
}'

Copy

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;

Copy

範囲フィルター¶

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

Copy

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
}'

Copy

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;

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

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

Copy

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;

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

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

Copy

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;

Copy

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

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

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

再ランク付けの無効化¶

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

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

Copy

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"
  }
}'

Copy

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;

Copy

Tip

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

Multi-index query examples¶

This section provides examples for querying multi-index Cortex Search Services with a restriction on which indices to search, for the Python and SQL APIs.

管理されたベクトル埋め込みを使用したサービスのクエリ¶

このセクションの例では、次の business_directory および example_search_service 定義を使用します。

-- Search data
CREATE OR REPLACE TABLE business_directory (name TEXT, address TEXT, description TEXT);
INSERT INTO business_directory VALUES
    ('Joe''s Coffee', '123 Bean St, Brewtown','A cozy café known for artisan espresso and baked goods.'),
    ('Sparkle Wash', '456 Clean Ave, Sudsville', 'Eco-friendly car wash with free vacuum service.'),
    ('Tech Haven', '789 Circuit Blvd, Siliconia', 'Computer store offering the latest gadgets and tech repair services.'),
    ('Joe''s Wash n'' Fold', '456 Apple Ct, Sudsville', 'Laundromat offering coin laundry and premium wash and fold services.'),
    ('Circuit Town', '459 Electron Dr, Sudsville', 'Technology store selling used computer parts at discounted prices.')
;

-- Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE example_search_service
    TEXT INDEXES name, address
    VECTOR INDEXES description (model='snowflake-arctic-embed-m-v1.5')
    WAREHOUSE = example_wh
    TARGET_LAG = '1 hour'
    AS ( SELECT * FROM business_directory );

Copy

特定のインデックスのクエリ¶

name テキストフィールドと description ベクトルフィールドに対して example_search_service をクエリするには:

resp = business_directory.search(
    query="tech repair shop",
    columns=["name", "description"],
    limit=2
)

Copy

SELECT
  value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_search_service',
      '{
      "query": "tech repair shop",
        "columns": ["name", "description"],
        "limit": 2
      }'
  ))['results']));

Copy

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

管理されたベクトル列のみのクエリ¶

管理された埋め込みを使用して、ベクトルインデックス description で「 PCs の更新されたコンポーネント」について example_search_service をクエリするには:

resp = business_directory.search(
    multi_index_query={
        "description": [
            {"text": "refurbished components for PCs"}
        ]
    },
    columns=["name", "address", "description"],
    limit=5
)

Copy

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "description": [
              {"text": "refurbished components for PCs"}
            ]
          },
          "columns": ["name", "address", "description"],
          "limit": 5
        }'
    )
)['results']));

Copy

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Joe's Coffee        | 123 Bean St, Brewtown       | A cozy café known for artisan espresso and baked goods.                  |
| Joe's Wash n' Fold  | 456 Apple Ct, Sudsville    | Laundromat offering coin laundry and premium wash and fold services.      |
| Sparkle Wash        | 456 Clean Ave, Sudsville    | Eco-friendly car wash with free vacuum service.                          |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

Query with index weights¶

テキストインデックス name で「sparkle」について、ベクトルインデックス description で「clothing washing」について example_search_service をクエリし、テキストまたは再ランク付けよりもベクトルスコアリングに4倍高い重み付けをするには:

resp = business_directory.search(
    multi_index_query={
        "name": [
            {"text": "sparkle"}
        ],
        "description": [
            {"text": "clothing washing"}
        ]
    },
    scoring_config={
        "weights": {
            "texts": 1,
            "vectors": 4,
            "reranker": 1
        }
    },
    columns=["name", "address", "description"],
    limit=2
)

Copy

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "name": [
              {"text": "sparkle"}
            ],
            "description": [
              {"text": "clothing washing"}
            ]
          },
          "scoring_config": {
            "weights": {
              "texts": 1,
              "vectors": 4,
              "reranker": 1
            }
          },
          "columns": ["name", "address", "description"],
          "limit": 2
        }'
    )
)['results']));

Copy

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Joe's Wash n' Fold  | 456 Apple Ct, Sudsville     | Laundromat offering coin laundry and premium wash and fold services.     |
| Sparkle Wash        | 456 Clean Ave, Sudsville    | Eco-friendly car wash with free vacuum service.                          |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

description ベクトルインデックス列の重みは任意の text 列よりも高いので、「clothes washing」に最も関連するビジネスは、その名前に「sparkle」を含むビジネスの上に表示されます。

個別の重み付けされたインデックスを使用したクエリ¶

すべてのフィールドで「circuit」について example_search_service をクエリして、相対的な重み付けを適用し、 description 列ではなく name 列で一致をブーストするには:

resp = business_directory.search(
    multi_index_query={
        "name": [{"text": "circuit"}],
        "address": [{"text": "circuit"}],
        "description": [{"text": "circuit"}]
    },
    scoring_config={
        "functions": {
            "text_boosts": [
                {"column": "name", "weight": 2},
                {"column": "address", "weight": 1}
            ]
        }
    },
    columns=["name", "address", "description"],
    limit=3
)

Copy

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "name": [ {"text": "circuit"} ],
            "address": [ {"text": "circuit"} ],
            "description": [ {"text": "circuit"} ]
          },
          "scoring_config": {
              "functions": {
                "text_boosts": [{"column":"name", "weight": 2}, {"column":"address", "weight": 1}]
                }
          },
          "columns": ["name", "address", "description"],
          "limit": 3
        }'
    )
)['results']));

Copy

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Joe's Coffee        | 123 Bean St, Brewtown       | A cozy café known for artisan espresso and baked goods.                  |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

住所よりも名前をブーストすると、「Circuit Town」という名前のビジネスが、「Circuit Blvd」の住所にあるビジネスよりも上にランク付けされることに注意してください。

カスタムベクトル埋め込みを使用したサービスのクエリ¶

このセクションの例では、次の business_documents および example_search_service 定義を使用します。

-- Search data with only custom embeddings
CREATE OR REPLACE TABLE business_documents (
  document_contents VARCHAR,
  document_embedding VECTOR(FLOAT, 3)
);
INSERT INTO business_documents VALUES
  ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.', [1, 1, 1]::VECTOR(float, 3)),
  ('IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.', [2, 2, 2]::VECTOR(float, 3)),
  ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture initiatives.', [2, 3, 2]::VECTOR(float, 3)),
  ('Marketing strategy document: Target audience segmentation for upcoming product launch.', [1, -1, -1]::VECTOR(float, 3))
;

-- Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE example_search_service
  TEXT INDEXES (document_contents)
  VECTOR INDEXES (document_embedding)
  WAREHOUSE = example_wh
  TARGET_LAG = '1 minute'
  AS SELECT * FROM business_documents;

Copy

注釈

これらの例では、簡潔にするためにモック埋め込みを使用しています。実稼働のユースケースでは、 Snowflakeベクトル埋め込みモデルまたは外部ホスト埋め込みモデルを介してベクトルを生成する必要があります。

カスタム埋め込みを使用したインデックスのクエリ¶

document_contents および document_embedding 列で「 IT 」と対応する埋め込みを使用して example_search_service をクエリするには:

resp = business_directory.search(
    multi_index_query={
        "document_embedding": [ {"vector": [1, 1, 1]} ],
        "document_contents": [ {"text": "IT"} ]
    },
    columns=["document_contents"],
    limit=2
)

Copy

SELECT
    value['document_contents']::text as document_contents
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'byov_search_service',
        '{
          "multi_index_query": {
                "document_embedding": [ {"vector": [1, 1, 1] } ],
                "document_contents": [ {"text": "IT"} ]
          },
          "columns": ["document_contents"],
          "limit": 2
        }'
    )
)['results']));

Copy

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                   DOCUMENT_CONTENTS                                                                                      |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.                      |
| Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.            |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+