查询 Cortex Search 服务¶

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

Python API
REST API
SQL SEARCH_PREVIEW 函数

参数¶

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

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

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

身份验证¶

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

SQL SEARCH_PREVIEW 函数¶

SNOWFLAKE.CORTEX.SEARCH_PREVIEW 函数允许您从工作表或 Snowflake 笔记本单元格等 SQL 环境内预览对 Cortex Search 服务的单个查询结果。通过该函数，可以轻松快速地验证服务是否已正确填充并提供合理的结果。

重要

此函数仅对字符串字面量查询进行操作。它不接受批处理文本数据。
此函数产生的延迟比 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

使用说明¶

对源查询中 ``NaN``（“非数字”）值的匹配按特殊值中所述进行处理。
定点数值若超过 19 位（不含前导零）时，无法与 @eq、@gte 或 @lte 运算符兼容，这些运算符将不会返回此类数值（但通过使用 @not 运算符的完整查询仍可能返回这些结果）。
TIMESTAMP 和 DATE 筛选器接受 YYYY-MM-DD 形式的值，对于时区感知型日期，可接受：YYYY- MM-DD+HH:MM。如果未指定时区偏移量，则以 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 毫秒，但延迟的确切减少量以及质量下降的程度因工作负载而异。在决定在查询中禁用重新排名之前，请并排评估使用重新排名和未使用重新排名的结果。

在不使用重排序器的情况下查询 Cortex Search Service

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

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

Copy

属性：

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

访问控制要求¶

查询 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" 参数，因为重新排名是默认行为。