Consulta ao Cortex Search Service

Quando você cria um Cortex Search Service, o sistema provisiona um ponto de extremidade de API para processar as consultas em baixa latência. Você pode usar três APIs para consultar um Cortex Search Service:

Parâmetros

Todas as APIs oferecem suporte ao mesmo conjunto de parâmetros de consulta:

Parâmetro

Descrição

Obrigatório

query

A consulta que será pesquisada na coluna de texto no serviço.

Opcional

columns

Uma lista de colunas separadas por vírgulas a serem retornadas para cada resultado relevante na resposta. Essas colunas devem ser incluídas na consulta de origem do serviço. Se esse parâmetro não for fornecido, apenas a coluna de pesquisa será retornada na resposta.

filter

Um objeto de filtro para filtrar resultados com base nos dados nas colunas ATTRIBUTES. Consulte Sintaxe do filtro para ver a sintaxe.

scoring_config

Objeto de configuração para personalizar o comportamento da classificação de pesquisa. Consulte Personalização da pontuação do Cortex Search para sintaxe.

scoring_profile

O perfil de pontuação nomeado a ser usado com a consulta, previamente definido com ALTER CORTEX SEARCH SERVICE … ADD SCORING PROFILE. Se scoring_profile for fornecido, qualquer scoring_config fornecido será ignorado.

limit

Número máximo de resultados a serem retornados na resposta, até 1000. O limite padrão é 10.

Sintaxe

Os seguintes exemplos mostram como consultar um Cortex Search Service usando todas as três superfícies:

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

Configuração e autenticação

API de Python

Os Cortex Search Services podem ser consultados usando a versão 0.8.0 ou posterior das Snowflake Python APIs. Consulte Snowflake Python APIs: Gerenciamento de objetos Snowflake com Python para obter mais informações sobre as Snowflake Python APIs.

Instalação da biblioteca da Snowflake Python API

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

pip install snowflake -U
Copy

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 as 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)
Copy

Nota

A versão 0.8.0 ou posterior da biblioteca Snowflake Python APIs é necessária para consultar um Cortex Search Service.

REST API

O Cortex Search expõe um ponto de extremidade da API REST no conjunto de APIs REST do Snowflake. O ponto de extremidade REST gerado para um Cortex Search Service tem a seguinte estrutura:

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

Onde:

  • <account_url>: O URL da sua conta Snowflake. Consulte Como encontrar o nome da conta e organização de uma conta para obter instruções sobre como encontrar o URL da sua conta.

  • <db_name>: o banco de dados no qual o serviço reside.

  • <schema_name>: esquema no qual o serviço reside.

  • <service_name>: nome do serviço.

  • :query: O método a ser invocado no serviço; neste caso, o método query.

Para obter detalhes adicionais, consulte a referência do RESTAPI do Cortex Search Service.

Autenticação

As Snowflake REST APIs oferecem suporte à autenticação por meio de tokens de acesso programático (Programmatic Access Tokens, PATs), autenticação com par de chaves usando JSON Web Tokens (JWTs) e OAuth. Para obter detalhes, consulte Autenticação das Snowflake REST APIs com Snowflake.

Função SQL SEARCH_PREVIEW

A função SNOWFLAKE.CORTEX.SEARCH_PREVIEW permite que você versão os resultados de consultas individuais em um Cortex Search Service de dentro de um ambiente SQL, como uma planilha ou uma célula do Snowflake Notebook. Essa função facilita a validação interativa de que um serviço foi preenchido corretamente e está apresentando resultados razoáveis.

Importante

A função SEARCH_PREVIEW é fornecida para teste e validação do Cortex Search Services. Ela não se destina a atender consultas de pesquisa em um aplicativo de usuário final.

  • A função opera somente em literais de cadeia de caracteres. Ela não aceita dados de texto em lote.

  • A função tem latência maior que as APIs REST e Python.

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 cinco operadores de correspondência:

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

  • @and

  • @or

  • @not

Notas de uso

  • A correspondência com valores NaN («não é um número») na consulta de origem é tratada conforme descrito em Valores especiais.

  • Os valores numéricos de ponto fixo com mais de 19 dígitos (sem incluir zeros iniciais) não funcionam com @eq, @gte ou @lte e não serão retornados por esses operadores (embora ainda possam ser retornados pela consulta geral com o uso de @not).

  • Os filtros TIMESTAMP e DATE aceitam valores no formato: 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.

  • @primarykey só é compatível com serviços configurados com uma chave primária. O valor do filtro deve ser um objeto JSON que mapeia cada coluna de chave primária para seu valor correspondente (ou NULL).

Esses operadores podem ser combinados em um único objeto de filtro.

Exemplo

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

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

  • Filtragem para uma linha com os valores de chave primária especificados us-west-1 na coluna region e abc123 na coluna agent_id:

    { "@primarykey": { "region": "us-west-1", "agent_id": "abc123" } }
    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 NUMERIC numeric_col está entre 10,5 e 12,5 (inclusive):

    {
  "@and": [
    { "@gte": { "numeric_col": 10.5 } },
    { "@lte": { "numeric_col": 12.5 } }
  ]
}
    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": "val2" } },
    { "@contains": { "array_col": "val3" } }
  ]
}
    Copy

Requisitos de controle de acesso

A função que está consultando o Cortex Search Service deve ter os seguintes privilégios para recuperar resultados:

Privilégio

Objeto

USAGE

O Cortex Search Service

USAGE

O banco de dados no qual o Cortex Search Service reside

USAGE

O esquema no qual o Cortex Search Service reside

Consulta com direitos de proprietário

O Cortex Search Services realiza buscas com os direitos do proprietário e seguem o mesmo modelo de segurança de outros objetos Snowflake executados com os direitos do proprietário.

Em particular, isso significa que qualquer função com privilégios suficientes para consultar um Cortex Search Service pode consultar qualquer dado que o serviço tenha indexado, independentemente dos privilégios dessa função nos objetos subjacentes (como tabelas e exibições) referenciados na consulta de origem do serviço.

Por exemplo, para um Cortex Search Service que faz referência a uma tabela com políticas de mascaramento em nível de linha, os usuários consultores desse serviço poderão ver os resultados da pesquisa de linhas nas quais a função do proprietário tem permissão de leitura, mesmo que a função do usuário consultor não possa ler essas linhas na tabela de origem.

Tenha cuidado, por exemplo, ao conceder uma função com privilégios USAGE em um Cortex Search Service a outro usuário do Snowflake.

Limitações conhecidas

A consulta a um Cortex Search Service está sujeita às seguintes limitações:

  • Tamanho da resposta: o tamanho total da carga útil da resposta retornada de uma consulta de pesquisa para um serviço Cortex Search Service não deve exceder os seguintes limites:

Exemplos

Esta seção apresenta exemplos abrangentes para consultar os Cortex Search Services em todos os três métodos de API.

Configuração para os exemplos

Os exemplos a seguir usam uma tabela chamada business_documents com carimbo de data/hora e colunas numéricas para demonstrar vários recursos:

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

Exemplos de filtro

Consulta simples com filtro de igualdade

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

Filtro de intervalo

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

Exemplos de pontuação

Aumentos numéricos

Aplique aumentos numéricos às colunas de curtidas e comentários, com o dobro do peso de aumento nos valores de comentários em relação aos valores de curtidas.

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

Nos resultados, observe:

  • Com os aumentos, o documento «Product roadmap 2024:…» é o principal resultado devido ao seu grande número de curtidas e comentários, embora tenha uma relevância ligeiramente menor para a consulta «technology»

  • Sem os aumentos, o resultado principal da consulta é «IT manual for employees:…»

Decréscimos de tempo

Aplique decréscimos de tempo com base na coluna LAST_MODIFIED_TIMESTAMP, em que:

  • Os documentos com os valores LAST_MODIFIED_TIMESTAMP mais recentes, em relação ao carimbo de data/hora «now», são aumentados

  • Os documentos com um valor LAST_MODIFIED_TIMESTAMP superior a 240 horas a partir do carimbo de data/hora «now» recebem pouco aumento

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"}
            ]
        }
    }
)
Copy

Nos resultados, observe:

  • Com os decréscimos, o documento «Product roadmap 2024:…» é o principal resultado devido à sua recenticidade em relação ao carimbo de data/hora «now», embora tenha uma relevância ligeiramente inferior para a consulta de «technology»

  • Sem os decréscimos, o resultado principal da consulta é «IT manual for employees:…»

Desabilitação da reclassificação

Para desabilitar a reclassificação:

resp = business_documents_css.search(
    query="technology",
    columns=["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
    limit=5,
    scoring_config={
        "reranker": "none"
    }
)
Copy

Dica

Para consultar um serviço com o mecanismo de classificação, omita o parâmetro "reranker": "none" do objeto scoring_config, pois a reclassificação é o comportamento padrão.

Linguagem: Português