Consulta ao Cortex Search Service¶

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.

pip install snowflake -U

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)

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

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.

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 rápida de que um serviço está preenchido corretamente e gerando resultados razoáveis.

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

Aumentos numéricos e decréscimos de tempo¶

Você pode aumentar ou aplicar decréscimos nos resultados de pesquisa com base em metadados numéricos ou de carimbo de data/hora. Esse recurso é útil quando você tem metadados estruturados (por exemplo, sinais de popularidade ou recenticidade) por resultado que podem ajudar a determinar a relevância dos documentos no momento da consulta. Você pode especificar duas categorias de sinais de classificação ao fazer uma consulta:

Os metadados de aumento e decréscimo provêm de colunas na tabela de origem das quais um Cortex Search Service é criado. Você especifica as colunas de metadados que serão usadas para aumentar ou diminuir ao fazer a consulta, mas essas colunas devem ser incluídas durante a criação do Cortex Search Service.

Consulta a um serviço com sinais de aumento ou decréscimo

Ao consultar um Cortex Search Service, especifique as colunas a serem usadas para aumento ou redução nos campos opcionais numeric_boosts e time_decays no campo scoring_config.functions. Você também pode especificar o peso de cada aumento ou decréscimo.

{
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {
          "column": "<column_name>",
          "weight": <weight>
        },
        // ...
      ],
      "time_decays": [
        {
          "column": "<column_name>",
          "weight": <weight>,
          "limit_hours": <limit_hours>
        },
        // ...
      ]
    }
  }
}

Propriedades:

• numeric_boosts (matriz, opcional):

  • <numeric_boost_object> (objeto, opcional):

    • column_name (string): especifica a coluna numérica à qual o reforço deve ser aplicado.

    • weight (float): especifica o peso ou a importância atribuída à coluna impulsionada no processo de classificação. Quando várias colunas são especificadas, um peso maior aumenta a influência do campo.

• time_decays (matriz, opcional):

  • <time_decay_object> (objeto, opcional):

    • column_name (string): especifica a coluna de data ou hora à qual o decréscimo deve ser aplicado.

    • weight (float): especifica o peso ou a importância atribuída à coluna com decréscimo no processo de classificação. Quando várias colunas são especificadas, um peso maior aumenta a influência do campo.

    • limit_hours (float): define o limite após o qual o tempo começa a ter menos efeito sobre a relevância ou a importância do documento. Por exemplo, um valor de 240 em limit_hours indica que os documentos com carimbos de data/hora com mais de 240 horas (10 dias) no passado a partir do carimbo de data/hora now não recebem um aumento significativo, enquanto os documentos com um carimbo de data/hora nas últimas 240 horas devem receber um aumento mais significativo.

    • now (cadeia de caracteres, opcional): carimbo de data/hora de referência opcional a partir do qual os decréscimos são calculados no formato ISO-8601 yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Por exemplo, "2025-02-19T14:30:45.123-08:00". O padrão é o carimbo de data/hora atual, se não for especificado.

Reclassificação¶

Por padrão, as consultas ao Cortex Search Services utilizam semantic reranking para melhorar a relevância dos resultados de pesquisa. Embora a reclassificação possa aumentar de forma mensurável a relevância do resultado, ele também pode aumentar visivelmente a latência da consulta. Você pode desativar a reclassificação em qualquer consulta do Cortex Search se descobrir que o benefício de qualidade proporcionado pela reclassificação pode ser sacrificado por velocidades de consulta mais rápidas em seu caso de uso comercial.

Consulta a um Cortex Search Service sem o reclassificador

Você pode desativar o mecanismo de classificação para uma consulta individual no momento da consulta no campo scoring_config.reranker no seguinte formato:

{
  "scoring_config": {
      "reranker": "none"
}

Propriedades:

• reranker (cadeia de caracteres, opcional): parâmetro que pode ser definido como “none” se o mecanismo de classificação for desativado. Se for excluído ou nulo, será usado o mecanismo de classificação padrão.

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.

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;

Exemplos de filtro¶

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES"],
  "filter": {"@eq": {"REGION": "US"}},
  "limit": 5
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES"],
         "filter": {"@eq": {"REGION": "US"}},
         "limit": 5
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "business",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "filter": {"@and": [
    {"@gte": {"LIKES": 50}},
    {"@lte": {"COMMENTS": 50}}
  ]},
  "limit": 10
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "business",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "filter": {"@and": [
           {"@gte": {"LIKES": 50}},
           {"@lte": {"COMMENTS": 50}}
         ]},
         "limit": 10
      }'
  )
)['results'] as results;

Exemplos de pontuação¶

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
  "scoring_config": {
    "functions": {
      "numeric_boosts": [
        {"column": "comments", "weight": 2},
        {"column": "likes", "weight": 1}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LIKES", "COMMENTS"],
         "scoring_config": {
           "functions": {
             "numeric_boosts": [
               {"column": "comments", "weight": 2},
               {"column": "likes", "weight": 1}
             ]
           }
         }
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "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"}
      ]
    }
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "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"}
             ]
           }
         }
      }'
  )
)['results'] as results;

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

curl --location https://<ACCOUNT_URL>/api/v2/databases/<DB_NAME>/schemas/<SCHEMA_NAME>/cortex-search-services/<SERVICE_NAME>:query \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
  "query": "technology",
  "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
  "scoring_config": {
    "reranker": "none"
  }
}'

SELECT PARSE_JSON(
  SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
      'business_documents_css',
      '{
         "query": "technology",
         "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP"],
         "scoring_config": {
           "reranker": "none"
         }
      }'
  )
)['results'] as results;