查询 Cortex Search 服务

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

参数

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

参数

描述

必填

query

搜索查询，用于在服务的文本列中进行搜索。

可选

columns

列的以逗号分隔列表，用于返回响应中每个相关结果的列。这些列必须包含在服务的源查询中。若未提供此参数，则响应中仅返回搜索列。

filter

筛选对象，用于根据 ATTRIBUTES 列中的数据筛选结果。请参阅 筛选器语法 了解具体语法。

scoring_config

Configuration object for customizing search ranking behavior. See 自定义 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.

语法

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

设置和身份验证

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

这些匹配运算符可以由各种逻辑运算符组成：

  • @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 服务的角色必须拥有以下权限才能检索结果：

权限

对象

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 的响应有效负载的总大小不得超过以下限制：

示例

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

范围筛选

resp = business_documents_css.search(
    query="business",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    filter={"@and": [
        {"@gte": {"LIKES": 50}},
        {"@lte": {"COMMENTS": 50}}
    ]},
    limit=10
)
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

在结果中，请注意：

  • 通过加权后，尽管文档与查询“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

在结果中，请注意：

  • 通过时间衰减后，尽管文档与查询“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

小技巧

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

语言: 中文