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
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)
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())
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
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, thequery
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 |
---|---|
|
Your search query, to search over the text column in the service. |
|
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. |
|
A filter object for filtering results based on data in the |
|
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 valuevalue
.{ "@eq": { "string_col": "value" } }
Filtering on rows where ARRAY column
array_col
contains valuevalue
.{ "@contains": { "array_col": "arr_value" } }
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" } } ] }
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>
}'
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;
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