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¶

Configuração de autenticação de RESTAPI¶

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

Exemplo de consulta do serviço¶

Para consultar o serviço usando curl:

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": "<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;

Exemplo¶

• 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 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": "val1" } },
        { "@contains": { "array_col": "val1" } }
    ]
  }
  

  Copy

Consulta de um serviço com sinais de aumento ou diminuição¶

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.

Exemplo¶

Criação de dados de amostra e o Cortex Search Service

Este exemplo usa uma tabela chamada business_documents que tem duas colunas de carimbo de data/hora (last_modified e created_timestamp) e duas colunas de números inteiros (likes e columns) que podem ser usadas para aumentos e decréscimos nos resultados de pesquisa.

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. Highlights include strategic investments in marketing and technology.',
     '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 and software guides and commonly asked tech questions.',
     '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 initiatives. Includes new guidelines on hybrid working models.',
     '2024-02-10 15:00:00', '2024-02-05 14:30:00', 85, 10),

    ('Marketing strategy document: Target audience segmentation for upcoming product launch. Detailed plans for social media, influencer partnerships, and content creation.',
     '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 of new features, bug fixes, and performance improvements.',
     '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 evaluations, set goals, and provide constructive feedback.',
     '2024-05-02 09:30:00', '2024-05-01 08:45:00', 60, 5);

Em seguida, crie um Cortex Search Service nomeado business_documents_css na coluna document_contents da tabela business_documents.

CREATE OR REPLACE CORTEX SEARCH SERVICE business_documents_css
    ON document_contents
    WAREHOUSE = <warehouse_name>
    TARGET_LAG = '1 minute'
AS SELECT * FROM business_documents;

Consulte o serviço com aumentos numéricos

A consulta abaixo aplica aumentos numéricos às colunas likes e comments, com o dobro do peso do reforço nos valores comments em relação aos valores de likes. A consulta usa a função SQL SEARCH_PREVIEW para pesquisar “technology”.

SELECT
    index,
    value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
    value['LIKES']::int as LIKES,
    value['COMMENTS']::int as COMMENTS,
FROM TABLE(FLATTEN(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'] ))

Nos resultados, observe:

• Com os reforços, 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 nenhum reforço, o principal resultado para a consulta é "IT manual for employees:..."

Consulta do serviço usando decréscimos de tempo

A consulta a seguir aplica decréscimos de tempo com base na coluna LAST_MODIFIED_TIMESTAMP, onde:

• Os documentos com 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

SELECT
  value['DOCUMENT_CONTENTS']::string as DOCUMENT_CONTENTS,
  value['LAST_MODIFIED_TIMESTAMP']::timestamp as LAST_MODIFIED_TIMESTAMP
FROM TABLE(FLATTEN(PARSE_JSON(SNOWFLAKE.CORTEX.SEARCH_PREVIEW(
    'business_documents_css',
    '{
      "query": "technology",
      "columns": ["DOCUMENT_CONTENTS", "LAST_MODIFIED_TIMESTAMP", "CREATED_TIMESTAMP", "LIKES", "COMMENTS"],
      "scoring_config": {
          "functions": {
              "time_decays": [
                {"column": "LAST_MODIFIED_TIMESTAMP", "weight": 1, "limit_hours": 240, "now": "2024-04-23T00:00:00.000-08:00"}
              ]
            }
        }
    }'
))['results'] ));

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 nenhum decréscimo, o principal resultado da consulta é "IT manual for employees:..."

Consulta a um Cortex Search Service sem o mecanismo de classificação¶

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.

Exemplos¶

Consultando um serviço de pesquisa sem o mecanismo de classificação (Python)

O código a seguir consulta o serviço sem a etapa de reclassificação usando a Python API:

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

Consulta a um serviço sem o mecanismo de classificação (SQL)

A instrução SQL a seguir consulta o serviço sem a etapa de reclassificação usando a função SEARCH_PREVIEW.

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

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.