Query a Cortex Search Service¶

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

Parameters¶

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 only via JWT tokens. To query the REST endpoint for a Cortex Search Service using a JWT token, you must first set up key pair authentication. See the Using key pair authentication for instructions.

Example of querying the service¶

To query the service using curl:

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

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;