类别：

字符串和二进制函数 (AI Functions)

SEARCH_PREVIEW (SNOWFLAKE.CORTEX)

给定 Cortex Search 服务名称和查询，从指定的服务返回响应。

语法

SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    '<service_name>',
    '<query_parameters_object>'
)
Copy

实参

service_name

Cortex Search 服务的名称。如果服务位于与当前会话不同的架构中，则使用完全限定名称。

query_parameters_object

STRING 包含 JSON 对象，该对象指定用于调用服务的查询参数。

键

类型

描述

默认值

query

字符串

您的搜索查询，用于搜索服务中的文本列。

这是必需的。

columns

数组

列的以逗号分隔列表，用于返回响应中每个相关结果的列。这些列必须包含在服务的源查询中。

创建服务时指定的搜索列。

filter

对象

筛选对象，用于根据 ATTRIBUTES 列中的数据筛选结果。有关详细语法，请参阅 筛选器语法。

空对象

limit

整数

要在响应中返回的最大结果数。

10

筛选器语法

Cortex Search 支持对 CREATE CORTEX SEARCH SERVICE 命令中指定的 ATTRIBUTES 列进行筛选。

Cortex Search 支持五种匹配运算符：

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

  • @and

  • @or

  • @not

以下使用说明适用：

  • 对源查询中 ``NaN``（“非数字”）值的匹配按 特殊值 中所述进行处理。

  • Fixed-point numeric values with more than 19 digits (not including leading zeroes) do not work with @eq, @gte, or @lte and will not be returned by these operators.

    • 例如，如果源查询中存在一个很大的值，使用 @eq 匹配该精确值将不返回任何结果。

    • 通过使用 @not，整体过滤器仍可能返回这些大值（例如，虽然 @eq X 对于某些大数值 X 不返回任何值，但 @not @eq Y 会将其返回）。

  • TIMESTAMP 和 DATE 筛选器接受 YYYY-MM-DD 形式的值，对于时区感知型日期，可接受：YYYY-MM-DD+HH:MM。如果未指定时区偏移量，则以 UTC 解析日期。

  • @primarykey 仅适用于配置了 主键 的服务。筛选器的值必须为 JSON 对象，且需将每个主键列映射到其对应的值（或 NULL）。

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

示例

  • 筛选字符串类列 string_col 等于值 value 的行。

    { "@eq": { "string_col": "value" } }
    Copy

  • 筛选到具有指定主键的行。

    { "@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": "val1" } },
      { "@contains": { "array_col": "val1" } }
  ]
}
    Copy

返回

返回 OBJECT，其中包含 Cortex Search 服务的查询结果和唯一请求 ID。请参阅 `示例`_ 中的示例输出。

使用说明

  • This function is designed for testing and validation, and incurs more latency than using the REST or Python APIs. Use other methods to serve search queries in an end-user application that requires low latency.

  • This function only operates on constant arguments. It does not accept table columns as input.

  • 如果搜索结果超过 300kB，此函数将截断结果。REST 界面允许的最大响应大小为 10MB。

示例

此示例使用 test query 查询名为 sample_service 的服务。该示例返回五个结果（最多），并包括 col1 和 col2 列中的数据。

SELECT
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW (
      'mydb.mysch.sample_service',
      '{
          "query": "test query",
          "columns": ["col1", "col2"],
          "limit": 3
      }'
  );
Copy
{
  "results":[
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"}
  ],
  "request_id":"a27d1d85-e02c-4730-b320-74bf94f72d0d"
}
语言: 中文