查询 Cortex Search 服务¶

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

The Python API
The REST API
The SQL SEARCH_PREVIEW Function

参数

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

	Parameter	Description
Required	`query`	The search query, to be searched for in the text column in the service.
Optional	`columns`	A comma-separated list of columns to return for each relevant result in the response. These columns must be included in the source query for the service. If this parameter is not provided, only the search column is returned in the response.
	`filter`	A filter object for filtering results based on data in the `ATTRIBUTES` columns. See Filter syntax for syntax.
	`scoring_config`	Configuration object for customizing search ranking behavior. See for syntax.
	`scoring_profile`	The named scoring profile to be used with the query, previously defined with ALTER CORTEX SEARCH SERVICE … ADD SCORING PROFILE. If `scoring_profile` is provided, any `scoring_config` provided is ignored.
	`limit`	Maximum number of results to return in the response, up to 1000. The default limit is 10.

Multi-index search parameters¶

In addition, the SQL and Python APIs support multi-index queries. Using multi-index parameters allows for refining results from Cortex Search and reducing query cost by limiting the number of columns searched.

Parameter Description

Parameter	Description
`multi_index_query`	The map used to determine which indexes to query. Each key in the map is the name of an indexed column, and each value is an array containing maps that define the query: If the index is a text index or a managed vector index, the query array can contain: Text queries: `{"text": "search_text"}` Vector queries, as an embedding vector: `{"vector": [vector_values]}` If the index is a user-provided vector embedding column, the query array can contain: If a `query_model` was specified at creation time for automatic embeddings, text queries: `{"text": "search_text"}`. Vector queries, as an embedding vector: `{"vector": [vector_values]}`

multi_index_query

The map used to determine which indexes to query. Each key in the map is the name of an indexed column, and each value is an array containing maps that define the query:

If the index is a text index or a managed vector index, the query array can contain:
- Text queries: {"text": "search_text"}
- Vector queries, as an embedding vector: {"vector": [vector_values]}
If the index is a user-provided vector embedding column, the query array can contain:
- If a query_model was specified at creation time for automatic embeddings, text queries: {"text": "search_text"}.
- Vector queries, as an embedding vector: {"vector": [vector_values]}

Note

Multi-index Cortex Search services can still be searched through the REST API or without the multi_index_query parameter. This causes an unrestricted search over all indexed columns, which affects query cost. For details on estimating cost for multi-index query compute, see Understanding cost for Cortex Search Services - Multi-index search.

语法

Simple queries to a Cortex Search Service use the following syntax:

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())

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>
}'

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;

Multi-index query syntax¶

Querying specific indices only or using a service with vector embeddings for a multi-index Cortex Search service uses the following syntax:

from snowflake.core import Root
from snowflake.snowpark import Session

session = Session.builder.configs( {...} ).create()
root = Root(session)

my_service = (root
  .databases["<service_database>"]
  .schemas["<service_schema>"]
  .cortex_search_services["<service_name>"]
)

resp = my_service.search(
    multi_index_query={
        "<index_name>": [
            {"text": "<search_text>"},
            {"vector": [<vector_values>]},
            ...
        ],
        ...
    },
    scoring_config={
        "weights": {
            "texts": <text_weight>,
            "vectors": <vector_weight>,
            "reranker": <reranker_weight>
        },
        "functions": {
            "vector_boosts": [
                {"weight": <weight>, "column": "<vector_column_name>"},
                ...
            ],
            "text_boosts": [
                {"weight": <weight>, "column": "<text_column_name>"},
                ...
            ]
        }
    },
    columns=["<column_name>", "<column_name>", ...],
    limit=<limit>
)

SELECT SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      '<service_name>',
      '{
        "multi_index_query": {
          "<index_name>": [
            {"text": "<search_text>"},
            {"vector": [<vector_values>]},
            ...
          ],
          ...
        },
        "columns": ["<column_name>", "<column_name>", ...],
        "limit": <limit>,
        "scoring_config": {
          "weights": {
            "texts": <text_weight>,
            "vectors": <vector_weight>,
            "reranker": <reranker_weight>
          },
          "functions": {
            "vector_boosts": [
              {"weight": <weight>, "column": "<vector_column_name>"},
              ...
            ],
            "text_boosts": [
              {"weight": <weight>, "column": "<text_column_name>"}
              , ...
            ]
          }
        }
      }'
  );

设置和身份验证

Python API¶

Cortex Search Services may be queried using version 0.8.0 or later of the Snowflake Python APIs. See Snowflake Python APIs: Managing Snowflake objects with Python for more information on the Snowflake Python APIs.

安装 Snowflake Python API 库¶

First, install the latest version of the Snowflake Python APIs package from PyPI. See Install the Snowflake Python APIs library for instructions on installing this package from PyPI.

pip install snowflake -U

连接到 Snowflake¶

Connect to Snowflake using either a Snowpark Session or a Python Connector Connection and create a Root object. See Connect to Snowflake with the Snowflake Python APIs for more instructions on connecting to Snowflake. The following example uses the Snowpark Session object and a Python dictionary for configuration.

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)

Note

查询 Cortex Search Service 需要使 Snowflake Python APIs 库的版本 0.8.0 或更高版本。

REST API¶

Cortex Search exposes a REST API endpoint in the suite of Snowflake REST APIs. The REST endpoint generated for a Cortex Search Service is of the following structure:

https://<account_url>/api/v2/databases/<db_name>/schemas/<schema_name>/cortex-search-services/<service_name>:query

其中：

<account_url>: Your Snowflake Account URL. See Finding the organization and account name for an account for instructions on finding your account URL.
<db_name>: Database in which the service resides.
<schema_name>: Schema in which the service resides.
<service_name>: Name of the service.
:query: The method to invoke on the service; in this case, the query method.

For additional details, see the REST API reference for Cortex Search Service.

身份验证

Snowflake REST APIs support authentication via programmatic access tokens (PATs), key pair authentication using JSON Web Tokens (JWTs), and OAuth. For details, see Authenticating Snowflake REST APIs with Snowflake.

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.

Important

The SEARCH_PREVIEW function is provided for testing and validation of Cortex Search Services. It is not intended for serving search queries in an end-user application.

该函数仅对字符串字面量操作。它不接受批处理文本数据。
该函数的延迟高于 REST 和 Python APIs。

筛选器语法

Cortex Search supports filtering on the ATTRIBUTES columns specified in the CREATE CORTEX SEARCH SERVICE command.

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

TEXT or NUMERIC equality: @eq
ARRAY contains: @contains
NUMERIC or DATE/TIMESTAMP greater than or equal to: @gte
NUMERIC or DATE/TIMESTAMP less than or equal to: @lte
Primary key equality: @primarykey

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

@and
@or
@not

使用说明

Matching against NaN (‘not a number’) values in the source query is handled as described in Special values.
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 (although they could still be returned by the overall query with the use of @not).
TIMESTAMP filters accept values of the form: YYYY-MM-DDTHH:MM:SS.sss+HH:MM. If the timezone offset is not specified, the date is interpreted in UTC.
DATE filters accept values of the form YYYY-MM-DD. If time or timezones are specified, they will be truncated.
@primarykey is only supported for services configured with a primary key. The value of the filter must be a JSON object mapping every primary key column to its corresponding value (or NULL).

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

示例

Filtering on rows where string-like column string_col is equal to value value.
```
{ "@eq": { "string_col": "value" } }
```
Filtering to a row with the specified primary key values us-west-1 in the region column and abc123 in the agent_id column:
```
{ "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
```
Filtering on rows where ARRAY column array_col contains value value.
```
{ "@contains": { "array_col": "arr_value" } }
```
Filtering on rows where NUMERIC column numeric_col is between 10.5 and 12.5 (inclusive):
```
{
  "@and": [
 { "@gte": { "numeric_col": 10.5 } },
 { "@lte": { "numeric_col": 12.5 } }
  ]
}
```
Filtering on rows where TIMESTAMP column timestamp_col is between 2024-11-19 and 2024-12-19 (inclusive).
```
{
  "@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": "val2" } },
 { "@contains": { "array_col": "val3" } }
  ]
}

Multi-index queries¶

When created as a multi-index Cortex Search service with the CREATE CORTEX SEARCH SERVICE … TEXT INDEXES … VECTOR INDEXES syntax, the optional multi_index_query parameter is used. When omitting this parameter, all indices are used in the search.

使用说明

Each index to query is represented as a key-value pair in the multi_index_query map.
At least one vector index must be supplied in each query. Querying only text indexes is an error.
When querying a multi-index Cortex Search Service, the following behaviors apply:
- AND across fields: A match in all of the queried text or vector fields is required for a document to be returned.
- OR across terms within a text index field: When a query contains multiple terms such as “wash fold”, a document is returned if any of the query terms are found within the document.
- Text queries are automatically normalized using stemming, lemmatization, and domain-specific rewrites via Snowflake’s custom analyzer. This improves recall by matching related terms, such as linking “washing” to “wash” and “laundromat” to “laundry”.
The scoring_config.weights field modifies the relative weight of each of the 3 high-level scoring techniques (vector, keyword, reranking) in a given query.

Within this field, weights are applied relative to each other. For example, { "texts": 3, "vectors": 2, "reranker": 1 } and { "texts": 30, "vectors": 20, "reranker": 10 } are equivalent.
Using the scoring_config.functions.vector_boosts and scoring_config.functions.text_boosts fields:
- These fields allow users to modify the relative weight of each vector index and text index query, respectively, in a given query.
- Within each field, weights are applied relative to each other, as in scoring_config.weights.
Multi-index queries can be combined with numeric boosts, time decays, and queries that disable reranking. For information on using those features, see Numeric boosts and time decays and Reranking.
When querying a multi-index service, the query parameter can be used to specify a query to be applied to all fields, unless the service contains a vector index with user-provided vector embeddings.
To optimize search performance and latency, columns containing vector embeddings are not returned in results when issuing a query to a user-provided vector index.
Snowflake recommends refining your queries to use the multi_index_query on multi-index Cortex Search services to reduce the amount of resources consumed, which affects cost.

For information on estimating pricing for multi-index queries, see Estimating costs for multi-index Cortex Search.

访问控制要求

查询 Cortex Search 服务的角色必须拥有以下权限才能检索结果：

权限	对象
USAGE	Cortex Search 服务
USAGE	Cortex Search 服务所在的数据库
USAGE	Cortex Search 服务所在的架构

使用所有者权限进行查询

Cortex Search Services perform searches with owner’s rights and follow the same security model as other Snowflake objects that run with owner’s rights.

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

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

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

已知限制

Cortex Search Service 的查询受到以下限制：

Response size: The total size of the response payload returned from a search query to a Cortex Search Service must not exceed the following limits:
- REST API and Python API: 10 Megabytes (MB)
- SQL SEARCH_PREVIEW Function: 300 Kilobytes (KB)

Multi-index Cortex Search is subject to additional limitations, which may change during preview:

The Cortex Search Playground in the Snowsight UI does not support queries to multi-index services. Queries to multi-index services in the Playground display the message “Unable to query search service. Invalid request parameters or filter syntax.”
The multi-index serving query syntax with the multi_index_query parameter is supported only in versions 1.6.0 or later of the Python API.

示例

本节提供了使用所有三种 API 方法查询 Cortex Search Service 的完整示例。

示例设置

The following examples use a table named business_documents with timestamp and numeric columns for demonstrating various features:

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;

筛选示例

带有相等性过滤器的简单查询

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LIKES"],
    filter={"@eq": {"REGION": "US"}},
    limit=5
)

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
}'

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;

范围筛选

resp = business_documents_css.search(
    query="business",
    columns=["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
    filter={"@and": [
        {"@gte": {"LIKES": 50}},
        {"@lte": {"COMMENTS": 50}}
    ]},
    limit=10
)

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
}'

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;

评分示例

数值加权

对 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}
            ]
        }
    }
)

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

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;

在结果中，请注意：

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

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

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;

在结果中，请注意：

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

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"
  }
}'

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;

Tip

To query a service with the reranker, omit the "reranker": "none" parameter from the scoring_config object, as reranking is the default behavior.

Multi-index query examples¶

This section provides examples for querying multi-index Cortex Search Services with a restriction on which indices to search, for the Python and SQL APIs.

Query a service with managed vector embeddings¶

Examples in this section use the following business_directory and example_search_service definitions:

-- Search data
CREATE OR REPLACE TABLE business_directory (name TEXT, address TEXT, description TEXT);
INSERT INTO business_directory VALUES
    ('Joe''s Coffee', '123 Bean St, Brewtown','A cozy café known for artisan espresso and baked goods.'),
    ('Sparkle Wash', '456 Clean Ave, Sudsville', 'Eco-friendly car wash with free vacuum service.'),
    ('Tech Haven', '789 Circuit Blvd, Siliconia', 'Computer store offering the latest gadgets and tech repair services.'),
    ('Joe''s Wash n'' Fold', '456 Apple Ct, Sudsville', 'Laundromat offering coin laundry and premium wash and fold services.'),
    ('Circuit Town', '459 Electron Dr, Sudsville', 'Technology store selling used computer parts at discounted prices.')
;

-- Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE example_search_service
    TEXT INDEXES name, address
    VECTOR INDEXES description (model='snowflake-arctic-embed-m-v1.5')
    WAREHOUSE = example_wh
    TARGET_LAG = '1 hour'
    AS ( SELECT * FROM business_directory );

Query specific indexes¶

To query example_search_service over the name text field and description vector field:

resp = business_directory.search(
    query="tech repair shop",
    columns=["name", "description"],
    limit=2
)

SELECT
  value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_search_service',
      '{
      "query": "tech repair shop",
        "columns": ["name", "description"],
        "limit": 2
      }'
  ))['results']));

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

Query a managed vector column only¶

To query example_search_service for “refurbished components for PCs” over the vector index description, using managed embeddings:

resp = business_directory.search(
    multi_index_query={
        "description": [
            {"text": "refurbished components for PCs"}
        ]
    },
    columns=["name", "address", "description"],
    limit=5
)

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "description": [
              {"text": "refurbished components for PCs"}
            ]
          },
          "columns": ["name", "address", "description"],
          "limit": 5
        }'
    )
)['results']));

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Joe's Coffee        | 123 Bean St, Brewtown       | A cozy café known for artisan espresso and baked goods.                  |
| Joe's Wash n' Fold  | 456 Apple Ct, Sudsville    | Laundromat offering coin laundry and premium wash and fold services.      |
| Sparkle Wash        | 456 Clean Ave, Sudsville    | Eco-friendly car wash with free vacuum service.                          |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

Query with index weights¶

To query the example_search_service for “sparkle” over the text index name and “clothing washing” over the vector index description, weighting vector scoring as four times more relevant than text or reranking:

resp = business_directory.search(
    multi_index_query={
        "name": [
            {"text": "sparkle"}
        ],
        "description": [
            {"text": "clothing washing"}
        ]
    },
    scoring_config={
        "weights": {
            "texts": 1,
            "vectors": 4,
            "reranker": 1
        }
    },
    columns=["name", "address", "description"],
    limit=2
)

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "name": [
              {"text": "sparkle"}
            ],
            "description": [
              {"text": "clothing washing"}
            ]
          },
          "scoring_config": {
            "weights": {
              "texts": 1,
              "vectors": 4,
              "reranker": 1
            }
          },
          "columns": ["name", "address", "description"],
          "limit": 2
        }'
    )
)['results']));

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Joe's Wash n' Fold  | 456 Apple Ct, Sudsville     | Laundromat offering coin laundry and premium wash and fold services.     |
| Sparkle Wash        | 456 Clean Ave, Sudsville    | Eco-friendly car wash with free vacuum service.                          |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

Note that because the weight of the description vector index colum is higher than the weight of any text column, the business most associated with “clothes washing” appears above the business containing “sparkle” in its name.

Query with individually weighted indexes¶

To query example_search_service with “circuit” over all fields, applying a relative weight to boost matches in the name column over the description column:

resp = business_directory.search(
    multi_index_query={
        "name": [{"text": "circuit"}],
        "address": [{"text": "circuit"}],
        "description": [{"text": "circuit"}]
    },
    scoring_config={
        "functions": {
            "text_boosts": [
                {"column": "name", "weight": 2},
                {"column": "address", "weight": 1}
            ]
        }
    },
    columns=["name", "address", "description"],
    limit=3
)

SELECT
    value['name']::text as name, value['address']::text as address, value['description']::text as description
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'business_search_service',
        '{
          "multi_index_query": {
            "name": [ {"text": "circuit"} ],
            "address": [ {"text": "circuit"} ],
            "description": [ {"text": "circuit"} ]
          },
          "scoring_config": {
              "functions": {
                "text_boosts": [{"column":"name", "weight": 2}, {"column":"address", "weight": 1}]
                }
          },
          "columns": ["name", "address", "description"],
          "limit": 3
        }'
    )
)['results']));

+---------------------+-----------------------------+--------------------------------------------------------------------------+
|        NAME         |           ADDRESS           |                            DESCRIPTION                                   |
|---------------------+-----------------------------+--------------------------------------------------------------------------|
| Circuit Town        | 459 Electron Dr, Sudsville  | Technology store selling used computer parts at discounted prices.       |
| Tech Haven          | 789 Circuit Blvd, Siliconia | Computer store offering the latest gadgets and tech repair services.     |
| Joe's Coffee        | 123 Bean St, Brewtown       | A cozy café known for artisan espresso and baked goods.                  |
+---------------------+-----------------------------+--------------------------------------------------------------------------+

Note that boosting the name over address ranks the business named “Circuit Town” above the business located at an address on “Circuit Blvd”.

Query a service with custom vector embeddings¶

Examples in this section use the following business_documents and example_search_service definitions:

-- Search data with only custom embeddings
CREATE OR REPLACE TABLE business_documents (
  document_contents VARCHAR,
  document_embedding VECTOR(FLOAT, 3)
);
INSERT INTO business_documents VALUES
  ('Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.', [1, 1, 1]::VECTOR(float, 3)),
  ('IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.', [2, 2, 2]::VECTOR(float, 3)),
  ('Employee handbook 2024: Updated policies on remote work, health benefits, and company culture initiatives.', [2, 3, 2]::VECTOR(float, 3)),
  ('Marketing strategy document: Target audience segmentation for upcoming product launch.', [1, -1, -1]::VECTOR(float, 3))
;

-- Cortex Search Service
CREATE OR REPLACE CORTEX SEARCH SERVICE example_search_service
  TEXT INDEXES (document_contents)
  VECTOR INDEXES (document_embedding)
  WAREHOUSE = example_wh
  TARGET_LAG = '1 minute'
  AS SELECT * FROM business_documents;

Note

These examples use mock embeddings for simplicity. In a production use-case, vectors should be generated through a Snowflake vector embedding model or an externally-hosted embedding model.

Query an index with custom embeddings¶

To query example_search_service with “IT” and a corresponding embedding over the document_contents and document_embedding column:

resp = business_directory.search(
    multi_index_query={
        "document_embedding": [ {"vector": [1, 1, 1]} ],
        "document_contents": [ {"text": "IT"} ]
    },
    columns=["document_contents"],
    limit=2
)

SELECT
    value['document_contents']::text as document_contents
FROM TABLE(FLATTEN(PARSE_JSON(
    SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
        'byov_search_service',
        '{
          "multi_index_query": {
                "document_embedding": [ {"vector": [1, 1, 1] } ],
                "document_contents": [ {"text": "IT"} ]
          },
          "columns": ["document_contents"],
          "limit": 2
        }'
    )
)['results']));

+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                   DOCUMENT_CONTENTS                                                                                      |
|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| IT manual for employees: Instructions for usage of internal technologies, including hardware and software guides and commonly asked tech questions.                      |
| Quarterly financial report for Q1 2024: Revenue increased by 15%, with expenses stable. Highlights include strategic investments in marketing and technology.            |
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+