查询 Cortex Search 服务¶

当您创建 Cortex Search Service 时，系统会预置一个 API 端点来提供低延迟的查询。您可以使用三种 APIs 查询 Cortex Search Service：

Python API
REST API
SQL SEARCH_PREVIEW 函数

参数¶

所有 APIs 都支持相同的查询参数集：

	参数	描述
必填	`query`	搜索查询，用于在服务的文本列中进行搜索。
可选	`columns`	列的以逗号分隔列表，用于返回响应中每个相关结果的列。这些列必须包含在服务的源查询中。若未提供此参数，则响应中仅返回搜索列。
	`filter`	筛选对象，用于根据 `ATTRIBUTES` 列中的数据筛选结果。请参阅筛选器语法了解具体语法。
	`scoring_config`	用于自定义搜索排名行为的配置对象。请参阅自定义搜索排名了解语法。
	`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.

语法¶

以下示例展示如何使用所有三种不同方式查询 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

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

设置和身份验证¶

Python API¶

可使用 Snowflake Python APIs 版本 0.8.0 或更高版本来查询 Cortex Search Service。有关 Snowflake Python APIs 的更多信息，请参阅 Snowflake Python APIs：使用 Python 管理 Snowflake 对象。

安装 Snowflake Python API 库¶

首先，从 PyPI 安装最新版本的 Snowflake Python APIs 包。有关通过 PyPI 安装此包的说明，请参阅安装 Snowflake Python APIs 库。

pip install snowflake -U

Copy

连接到 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)

Copy

备注

查询 Cortex Search Service 需要使 Snowflake Python APIs 库的版本 0.8.0 或更高版本。

REST API¶

Cortex Search 在 Snowflake REST APIs 套件中提供了一个 REST API 端点。为 Cortex Search 服务生成的 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.

有关更多详细信息，请参阅有关 Cortex Search Service 的 REST API 参考。

身份验证¶

Snowflake REST APIs 支持通过编程访问令牌 (PATs) 进行身份验证、使用 JSON Web 令牌 (JWTs) 进行密钥对身份验证，以及 OAuth。详情请参阅使用 Snowflake 对 Snowflake REST APIs 进行身份验证。

SQL SEARCH_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 支持五种匹配运算符：

TEXT 或 NUMERIC 等效运算符：@eq
ARRAY 包含运算符：@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 仅适用于配置了主键的服务。筛选器的值必须为 JSON 对象，且需将每个主键列映射到其对应的值（或 NULL）。

这些运算符可以组合成一个筛选器对象。

示例¶

筛选字符串类列 string_col 等于值 value 的行。
```
{ "@eq": { "string_col": "value" } }
```
Copy
根据指定主键值筛选行：当 region 列中的值为 us-west-1 且 agent_id 列中的值为 abc123 时：
```
{ "@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 的查询会启用语义搜索和重新排序功能，以提升搜索结果的相关性。您可以通过以下多种方式自定义搜索结果的评分与排序：

基于数值型元数据列应用 数值加权
根据时间戳元数据列应用 时间衰减
禁用 重新排名 以减少查询延迟

数字提升和时间衰减¶

您可以根据数值或时间戳元数据来对搜索结果应用提升或衰减。如果每个结果都有结构化元数据（例如流行度或时效性信号），而这有助于确定查询时文档的相关性，则此功能非常有用。在执行查询时，您可以指定两类排名信号：

类型	描述	适用列类型	元数据字段示例（仅供说明使用）
数值提升	提升具有更高关注度或活跃度的结果的数值元数据。	数值数据类型	`clicks`、`likes`、`comments`
时间衰减	可提升最近结果的日期或时间元数据。时效性信号的影响会随着时间的推移而减弱。	日期和时间数据类型	`created_timestamp`、`last_opened_timestamp`、`action_date`

提升和衰减元数据来自创建 Cortex Search Service 的源表中的列。在发出查询时需要指定用于加权或衰减的元数据列，但这些列必须在创建 Cortex Search Service 时包含进去。

查询 Cortex Search Service 时，在 scoring_config.functions 字段的可选 numeric_boosts 和 time_decays 字段中指定用于提升或衰减的列。您还可以指定每次提升或衰减的权重。

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

Copy

属性：

``numeric_boosts``（数组，可选）：
- ``<numeric_boost_object>``（对象，可选）：
  - ``column_name``（字符串）：指定应该应用提升的数值列。
  - ``weight``（浮点数）：指定在排名过程中分配给提升列的权重或重要性。指定多个列时，较高的权重会增加该字段的影响力。
``time_decays``（数组，可选）：
- ``<time_decay_object>``（对象，可选）：
  - ``column_name``（字符串）：指定应该应用衰减的时间或日期列。
  - ``weight``（浮点数）：指定在排名过程中分配给衰减列的权重或重要性。指定多个列时，较高的权重会增加该字段的影响力。
  - limit_hours``（浮点数）：设置边界，此后时间对文档的相关性或重要性的影响开始减弱。例如，``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"。如果未指定，则默认为当前时间戳。

备注

数值提升以加权平均值的形式应用于返回的字段，衰减则利用对数平滑函数将不那么新的值降级。

在指定的提升或衰减字段中，权重是相对的。如果在 boosts 或 decays 数组中仅提供单个字段，则其权重值无关紧要。

如果提供了多个字段，则会相对于其他字段应用权重。例如，权重为 10 的字段对记录排名的影响是权重为 5 的字段的两倍。

重新排名¶

默认情况下，对 Cortex Search Service 的查询利用 语义重新排名 来提高搜索结果的相关性。虽然重新排名可以显著提高结果相关性，但也会明显增加查询延迟。如果在您的业务用例中，您发现可以牺牲重新排名提供的质量优势，以换取更快的查询速度，则可以在任何 Cortex Search 查询中禁用重新排名。

备注

禁用重新排名平均可将查询延迟减少 100-300 毫秒，但延迟的确切减少量以及质量下降的程度因工作负载而异。在决定在查询中禁用重新排名之前，请并排评估使用重新排名和未使用重新排名的结果。

在查询时，您可以在 scoring_config.reranker 字段中按照以下格式为单个查询禁用重新排名工具：

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

Copy

属性：

``reranker``（字符串，可选）：如果应该关闭重新排名工具，则可以将该参数设置为“none”。如果排除或为 null，则使用默认重新排名工具。

Named scoring profiles¶

提升/衰减和重新排序器设置共同形成一个 评分配置，在查询时可通过 scoring_config 参数指定。评分配置可以命名并附加到 Cortex Search Service。

使用命名评分配置文件，您可以轻松在不同应用程序和查询中使用同一评分配置，而无需每次都指定完整配置。如果您修改评分配置，只需在一个地方更新，而不必在每个查询中修改。

要向您的 Cortex Search Service 添加评分配置文件，请使用 ALTER CORTEX SEARCH SERVICE ... ADD SCORING PROFILE 命令，如下例所示：

ALTER CORTEX SEARCH SERVICE my_search_service
  ADD SCORING PROFILE heavy_comments_with_likes IF NOT EXISTS
  '{
    "functions": {
            "numeric_boosts": [
                { "column": "comments", "weight": 6 },
                { "column": "likes", "weight": 1 }
            ]
    }
  }'

Copy

评分配置文件的定义语法与查询时 scoring_config 参数使用的架构相同。

评分配置文件创建后无法修改；要更改配置文件，请删除后使用新的评分配置重新创建。要删除命名评分配置文件，请使用 ALTER CORTEX SEARCH SERVICE ... DROP SCORING PROFILE。

要使用命名评分配置文件查询 Cortex Search Service，请在查询时在 scoring_profile 参数中指定配置文件名称，如下例所示：

results = svc.search(
    query="technology",
    columns=["comments", "likes"],
    scoring_profile="heavy_comments_with_likes",
    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": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_profile": "heavy_comments_with_likes,
  "limit": 10
}'

Copy

SELECT SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
  'my_search_service',
  '{
    "query": "technology",
    "columns": ["comments", "likes"],
    "scoring_profile": "heavy_comments_with_likes",
    "limit": 10
  }'
);

Copy

要查看服务存储的评分配置文件，请查询 INFORMATION_SCHEMA 架构中的 CORTEX_SEARCH_SERVICE_SCORING_PROFILES 视图，如下例所示：

SELECT *
  FROM my_db.INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICE_SCORING_PROFILES
  WHERE service_name = 'my_search_service';

Copy

备注

DESCRIBE CORTEX SEARCH SERVICE 和 SHOW CORTEX SEARCH SERVICE 的结果包含一列名为 scoring_profile_count，显示每个服务的评分配置文件数量。

访问控制要求¶

查询 Cortex Search 服务的角色必须拥有以下权限才能检索结果：

权限	对象
USAGE	Cortex Search 服务
USAGE	Cortex Search 服务所在的数据库
USAGE	Cortex Search 服务所在的架构

使用所有者权限进行查询¶

Cortex Search 服务使用所有者权限执行搜索，并与使用所有者权限运行的其他 Snowflake 对象遵循相同的安全模型。

特别是，这意味着任何有足够权限来查询 Cortex Search 服务的角色都可以查询该服务已索引的任何数据，而不管该角色对服务源查询引用的基础对象（例如表和视图）的权限如何。

例如，对于引用具有行级掩码策略的表的 Cortex Search 服务，该服务的查询用户将能够从所有者角色具有读取权限的行查看搜索结果，即使查询用户的角色无法读取源表中的这些行。

例如，在将对 Cortex Search 服务具有 USAGE 权限的角色授予给其他 Snowflake 用户时，请注意。

已知限制¶

Cortex Search Service 的查询受到以下限制：

响应大小：从搜索查询返回给 Cortex Search Service 的响应有效负载的总大小不得超过以下限制：
- REST API 和 Python API：10 兆字节 (MB)
- SQL SEARCH_PREVIEW 函数：300 千字节 (KB)

示例¶

本节提供了使用所有三种 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

评分示例¶

数值加权¶

对 likes 和 comments 列同时应用数值加权，其中 comments 列的加权值是 likes 列的两倍。

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

在结果中，请注意：

通过加权后，尽管文档与查询“technology”的相关性略低，但由于其大量的 likes 和 comments，“Product roadmap 2024:...”文档仍排在首位。

在没有任何加权的情况下，该查询的首个结果是“IT manual for employees:...”。

时间衰减¶

根据 LAST_MODIFIED_TIMESTAMP 列应用时间衰减，其中：

相对于当前时间戳，具有较新 LAST_MODIFIED_TIMESTAMP 值的文档会获得加权。

LAST_MODIFIED_TIMESTAMP 值距离当前时间戳超过 240 小时的文档，获得的加权很少。

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

在结果中，请注意：

通过时间衰减后，尽管文档与查询“technology”的相关性略低，但由于其接近当前时间戳，“Product roadmap 2024:...” 文档仍排在首位。

在没有任何时间衰减的情况下，该查询的首个结果是“IT manual for employees:...”。

禁用重新排名¶

要禁用重新排名，请执行以下操作：

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

小技巧

要使用重新排名工具查询服务，请忽略 scoring_config 对象中的 "reranker": "none" 参数，因为重新排名是默认行为。

Cortex Search Component Scores¶

使用 Cortex Search Component Scores 可访问搜索结果的详细评分信息。组件分数可帮助开发者了解搜索排名如何确定，并调试搜索性能。每个结果的分数在每个检索“组件”（文本、向量）的 @scores 字段中返回。组件分数在以下场景中非常有用：

建立阈值：使用组件分数判断何时将结果传递给下游流程，例如代理。
调试搜索排名：了解为什么某些文档在搜索结果中的排名高于其他文档。

响应格式¶

启用组件分数后，所有 Cortex Search 查询将返回以下评分信息。有关 Cortex Search 查询语法的更多信息，请参阅查询 Cortex Search 服务。

{
  "results": [
    {
      "@scores": {
        "cosine_similarity": <cosine_similarity_score>,
        "text_match": <text_match_score>,
        "function_scores": {
          "text_boost": {
            "column_scores": {
              "name": {
                "score": <text_boost_score>,
                "weight": <text_boost_weight>
              }
            },
            "weighted_score": <text_boost_weighted_score>
          },
          "vector_boost": {
            "column_scores": {
              "description": {
                "score": <vector_boost_score>,
                "weight": <vector_boost_weight>
              }
            },
            "weighted_score": <vector_boost_weighted_score>
          }
        }
      }
    }
  ]
}

评分字段：

@scores.cosine_similarity：选择使用时默认使用的角色和仓库。查询与向量索引值之间的余弦相似度分数，范围 [-1, 1]。
@scores.text_match：选择使用时默认使用的角色和仓库。查询与文本索引值之间的文本匹配分数。该分数没有上限，其范围取决于查询。
@scores.function_scores：选择使用时默认使用的角色和仓库。嵌套对象，包含详细的提升函数评分（仅在查询中指定 functions 时存在）：
- text_boost.column_scores.column_name.score：选择使用时默认使用的角色和仓库。文本提升中指定列的单独分数。
- text_boost.column_scores.column_name.weight：选择使用时默认使用的角色和仓库。文本提升中指定列的应用权重。
- text_boost.weighted_score：选择使用时默认使用的角色和仓库。文本提升函数的最终加权分数。该分数范围为 [0, 1.1]。
- vector_boost.column_scores.column_name.score：选择使用时默认使用的角色和仓库。向量提升中指定列的单独分数。
- vector_boost.column_scores.column_name.weight：选择使用时默认使用的角色和仓库。向量提升中指定列的应用权重。
- vector_boost.weighted_score：选择使用时默认使用的角色和仓库。向量提升函数的最终加权分数。该分数范围为 [0, 1]。

Usage Notes¶

cosine_similarity 分数为：
- 对包含 VECTOR INDEX 的查询返回。
- 范围 [-1, 1]，可在不同查询间比较。
- 在大多数情况下，每个查询前添加前缀后计算，可以提高搜索质量。此前缀因模型而异，但通常为：Represent this sentence for searching relevant passages: {query}。返回的余弦相似度分数是带前缀查询与向量索引值之间的余弦相似度。
text_match 分数为：
- 对包含 TEXT INDEX 的查询返回。text_match 分数无限制。
- 不能在不同的查询之间进行比较。例如，对于给定查询结果的文本匹配分数 0.95，不可与同一服务不同查询结果的 0.95 分数比较。
@scores 值不受 weights 参数影响。权重仅影响结果的最终排序。
function_scores 为：
- 仅在查询中指定 functions 时返回。
- 界限范围 [0, 1.1]。

了解组件分数¶

组件分数提供 Cortex Search 计算每个搜索结果最终相关性分数的详细分解。评分系统由多个组件组成：

余弦相似度: 基于查询与向量索引之间语义相似度的分数。分数越高表示使用向量嵌入的概念或语义匹配越强。
文字匹配: 基于查询与文本索引之间关键字/词汇相似度的分数。分数越高表示精确或模糊关键字匹配越强。
函数分数: 应用提升函数时提供的额外详细评分信息（例如 text_boosts、vector_boosts、数值提升、时间衰减）。包含每种提升类型的嵌套对象（如 text_boost 和 vector_boost），显示各列分数、权重及加权总分。有助于理解不同字段的匹配如何影响文档的最终评分。

示例¶

检索查询在服务 svc 单索引下的组件：

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

session = Session.builder.configs({ ... }).create()
root = Root(session)
svc = (root
    .databases["<database>"]
    .schemas["<schema>"]
    .cortex_search_services["<service_name>"]
)

resp = svc.search(
    query="wash",
    columns=["name", "address", "description"],
    limit=2
)

pprint(resp.results)

Copy

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description,
    value['@scores']['cosine_similarity']::float as cosine_similarity, value['@scores']['text_match']::float as text_match
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
        "query": "wash",
        "columns": ["name", "address", "description"],
        "limit": 2
        }'
    )
)['results']));

Copy

示例输出：

[
  {
    "@scores": {
      "cosine_similarity": 0.43767208,
      "text_match": 3.3225928e-07
    },
    "address": "456 Apple Ct, Sudsville",
    "description": "Laundromat offering coin laundry and premium wash and fold services.",
    "name": "Joe's Wash n' Fold"
  },
  {
    "@scores": {
      "cosine_similarity": 0.43241996,
      "text_match": 0.1144074
    },
    "address": "456 Clean Ave, Sudsville",
    "description": "Eco-friendly car wash with free vacuum service.",
    "name": "Sparkle Wash"
  }
]

检索查询在服务 svc 三个索引下的组件分数：

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

session = Session.builder.configs({ ... }).create()
root = Root(session)
svc = (root
    .databases["<database>"]
    .schemas["<schema>"]
    .cortex_search_services["<service_name>"]
)

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

pprint(resp.results)

Copy

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description,
    value['@scores'] as scores,
    value['@scores']['cosine_similarity']::float as cosine_similarity, value['@scores']['text_match']::float as text_match,
    value['@scores']['function_scores']::variant as function_scores
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "name": [ {"text": "wash"} ],
            "address": [ {"text": "wash"} ],
            "description": [ {"text": "wash"} ]
          },
          "columns": ["name", "address", "description"],
          "scoring_config": {
            "weights": {
              "texts": 1,
              "vectors": 2,
              "reranker": 1
            }
          },
          "limit": 2
        }'
    )
)['results']));

Copy

示例输出：

[
    {
        '@scores': {
            'cosine_similarity': 0.43767208,
            'text_match': 3.3225928e-07
        },
        'address': '456 Apple Ct, Sudsville',
        'description': 'Laundromat offering coin laundry and premium wash and fold services.',
        'name': "Joe's Wash n' Fold"
    },
    {
        '@scores': {
            'cosine_similarity': 0.43241996,
            'text_match': 0.1144074
        },
        'address': '456 Clean Ave, Sudsville',
        'description': 'Eco-friendly car wash with free vacuum service.',
        'name': 'Sparkle Wash'
    }
]

Known Limitations¶

对于用户提供的向量嵌入索引，不返回余弦相似度分数。