查询 Cortex Search 服务¶

安装 Snowflake Python APIs 库¶

首先，从 PyPI 安装最新版本的 Snowflake Python APIs 包。有关从 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 (https://curl.se/) 查询服务，请执行以下操作：

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 时，在 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>
        },
        // ...
      ]
    }
  }
}

属性：

• ``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"。如果未指定，则默认为当前时间戳。

示例¶

创建样本数据和 Cortex Search Service

此示例使用名为 business_documents 的表，该表具有两个时间戳列（last_modified、created_timestamp）和两个整数列（likes、columns），这些列可用于搜索结果的提升和衰减。

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 列应用数值提升，其中 comments 值的提升权重是 likes 值的两倍。该查询使用 SQL SEARCH_PREVIEW 函数 来搜索“technology”。

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

在结果中，请注意：

• 应用提升后，"Product roadmap 2024:..." 文档是最佳结果，因为尽管它与查询 "technology" 的相关性略低，但由于其点赞和评论数量众多，因此排名靠前

• 如果未应用任何提升，查询的最佳结果是 "IT manual for employees:..."

使用时间衰减查询服务

以下查询将根据 LAST_MODIFIED_TIMESTAMP 列应用时间衰减，其中：

• 相对于 now 时间戳，具有较新 LAST_MODIFIED_TIMESTAMP 值的文档会得到提升

• LAST_MODIFIED_TIMESTAMP 值比 now 时间戳晚 240 小时以上的文档几乎不会得到提升

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)

以下代码使用 :ref:` Python API <label-cortex_search_query_syntax_python>`，在不执行重新排名步骤的情况下查询服务：

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 服务使用 所有者权限 执行搜索，并与使用所有者权限运行的其他 Snowflake 对象遵循相同的安全模型。

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

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

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