Consulta ao Cortex Search Service¶

Instale a biblioteca Snowflake Python APIs.¶

Primeiro, instale a versão mais recente do pacote Snowflake Python APIs de PyPI. Consulte Instale a biblioteca Snowflake Python APIs. para obter instruções sobre como instalar este pacote do PyPI.

pip install snowflake -U

Conexão com o Snowflake¶

Conecte-se ao Snowflake usando uma Session Snowpark ou um conector Python Connection e crie um objeto Root. Consulte Conexão ao Snowflake com o Snowflake Python APIs para obter mais instruções sobre como se conectar ao Snowflake. O exemplo a seguir usa o objeto Session Snowpark e um dicionário Python para configuração.

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)

Consulta ao serviço¶

Consulte o serviço usando a seguinte sintaxe:

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

Parâmetros¶

Sintaxe do filtro¶

O Cortex Search oferece suporte à filtragem nas colunas ATTRIBUTES especificadas no comando CREATE CORTEX SEARCH SERVICE.

O Cortex Search oferece suporte a quatro operadores de correspondência:

• Igualdade da cadeia de caracteres: @eq

• A matriz contém: @contains

• Data/carimbo de data/hora maior ou igual a: @gte

• Data/carimbo de data/hora menor ou igual a: @lte

Esses operadores correspondentes podem ser compostos com vários operadores lógicos:

• @and

• @or

• @not

Os operadores @gte e @lte podem operar em ATTRIBUTES do tipo DATE ou TIMESTAMP (Tipos de dados de data e hora) e aceitam valores do tipo: YYYY-MM-DD e, para datas com conhecimento de fuso horário: YYYY-MM-DD+HH:MM. Se o deslocamento de fuso horário não for especificado, a data será interpretada em UTC. Os operadores @gte e @lte incluem os valores especificados.

Esses operadores podem ser combinados em um único objeto de filtro. Seguem alguns exemplos:

• Filtro em linhas onde a coluna do tipo cadeia de caracteres string_col é igual ao valor value.

  { "@eq": { "string_col": "value" } }
  

  Copy

• Filtro em linhas onde a coluna ARRAY array_col contém o valor value.

  { "@contains": { "array_col": "arr_value" } }
  

  Copy

• Filtragem de linhas em que a coluna TIMESTAMP timestamp_col está entre 2024-11-19 e 2024-12-19 (inclusive).

  { "@and": [
    { "@gte": { "timestamp_col": "2024-11-19" } },
    { "@lte": { "timestamp_col": "2024-12-19" } }
  ]}
  

  Copy

• Composição de filtros com operadores lógicos:

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

Configuração de autenticação da REST API¶

As REST APIs Snowflake atualmente oferecem suporte à autenticação por meio de autenticação de par de chaves e OAuth. Para obter mais detalhes, consulte Autenticando o Snowflake REST APIs com Snowflake.

Exemplo de consulta do serviço¶

Para consulta o serviço usando curl e autenticação de par de chaves:

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

Exemplo¶

O exemplo a seguir visualiza o serviço com a cadeia de caracteres de consulta preview query e analisa os resultados em um objeto VARIANT.

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;