类别：: :doc:`/sql-reference/functions-string`（AI 函数）

SEARCH_PREVIEW (SNOWFLAKE.CORTEX)¶

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

语法¶

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

实参¶

service_name

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

query_parameters_object

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


键	类型	描述	默认值
`query`	字符串	您的搜索查询，用于搜索服务中的文本列。	这是必需的。
`columns`	数组	列的以逗号分隔列表，用于返回响应中每个相关结果的列。这些列必须包含在服务的源查询中。	创建服务时指定的搜索列。
`filter`	对象	筛选对象，用于根据 `ATTRIBUTES` 列中的数据筛选结果。有关详细语法，请参阅筛选器语法。	空对象
`limit`	整数	要在响应中返回的最大结果数。	10

筛选器语法¶

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 运算符兼容，这些运算符将不会返回此类数值。
- 例如，如果源查询中存在一个很大的值，使用 @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" } }
```

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

{ "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }

筛选 ARRAY 列 array_col 包含值 value 的行。
```
{ "@contains": { "array_col": "arr_value" } }
```
在 NUMERIC 列 numeric_col 处于 10.5 和 12.5（含）之间的行上进行筛选：
```
{ "@and": [
  { "@gte": { "numeric_col": 10.5 } },
  { "@lte": { "numeric_col": 12.5 } }
]}
```
在 TIMESTAMP 列 timestamp_col 处于 2024-11-19 和 ``2024-12-19``（含）之间的行上进行筛选。
```
{ "@and": [
  { "@gte": { "timestamp_col": "2024-11-19" } },
  { "@lte": { "timestamp_col": "2024-12-19" } }
]}
```

用逻辑运算符组成筛选器：

// 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" } }
  ]
}

返回¶

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

使用说明¶

此函数专为测试和验证而设计，其产生的延迟高于使用 REST 或 Python APIs。在需要低延迟的最终用户应用程序中，请使用其他方法提供搜索查询服务。
此函数仅对常量实参进行操作。它不接受表列作为输入。
如果搜索结果超过 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
      }'
  );

{
  "results":[
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"},
      {"col1":"text", "col2":"text"}
  ],
  "request_id":"a27d1d85-e02c-4730-b320-74bf94f72d0d"
}