Query a Cortex Search Service

When you create a Cortex Search Service, a REST API endpoint is provisioned to serve queries to the service. You have two options for querying a Cortex Search Service:

  • Use the Snowflake Python APIs

  • Use a client of your choice to query the REST endpoint directly

Snowflake Python APIs

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.

Install the Snowflake Python APIs library

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
Copy

Connect to 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)
Copy

Query the service

Query the service using the following syntax:

# 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

Note

Version 0.8.0 or later of the Snowflake Python APIs library is required to query a Cortex Search Service.

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
Copy

Where:

  • <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. The following describes the parameters and filter syntax to use when querying the service.

Parameters

Parameter

Description

query

Your search query, to search over the text column in the service.

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.

filter

A filter object for filtering results based on data in the ATTRIBUTES columns. See Filter syntax.

limit

Maximum number of results to return in the response.
Maximum accepted value is 1000.
Default value is 10.

Filter syntax

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

Cortex Search supports two matching operators:

  • String equality: @eq

  • Array contains: @contains

These matching operators can be composed with various logical operators:

  • @and

  • @or

  • @not

These operators can be combined into a single filter object. Examples follow:

  • Filtering on rows where string-like column string_col is equal to value value.

    { "@eq": { "string_col": "value" } }
    
    Copy
  • Filtering on rows where ARRAY column array_col contains value value.

    { "@contains": { "array_col": "arr_value" } }
    
    Copy
  • Composing filters with logical operators:

    // 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

Configure REST API Authentication

Snowflake REST APIs currently support authentication via key pair authentication and OAuth. For details, see Authenticating Snowflake REST APIs with Snowflake.

Example of querying the service

To query the service using curl and key pair authentication:

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>\:query \
--header 'X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $CORTEX_SEARCH_JWT" \
--data '{
  "query": "<search_query>",
  "columns": ["col1", "col2"],
  "filter": <filter>
  "limit": <limit>
}'
Copy

Note

When querying the REST API using JWT authentication, the user’s default role is used. Thus, default role of the user querying the service must have USAGE on the database and schema in which the service resides, and on the service itself. The querying user role does not necessarily need privileges on the data in the source query. See User roles for more details on user roles.

Preview Service with SQL System Function

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 quickly validate that a service is populated correctly and serving reasonable results.

Example

The following example previews the service with the preview query query string and parses the results into a VARIANT object.

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;
Copy

Access Control Requirements

The role that is querying the Cortex Search Service must have the following privileges to retrieve results:

Privilege

Object

USAGE

The Cortex Search Service

USAGE

The database in which the Cortex Search Service resides

USAGE

The schema in which the Cortex Search Service resides