Batch Cortex Search¶

Sintaxe¶

Use a seguinte sintaxe para consultar um Cortex Search Service no modo de lote usando a função de tabela CORTEX_SEARCH_BATCH:

SELECT
    q.query,
    r.*
FROM query_table AS q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => '<database>.<schema>.<cortex_search_service>',
    query => q.query,                   -- optional STRING
    multi_index_query => q.miq,         -- optional VARIANT
    filter => q.filter,                 -- optional VARIANT
    limit => 10,                        -- optional INT
    options => q.options                -- optional VARIANT
) AS r;

Parâmetros¶

A função CORTEX_SEARCH_BATCH oferece suporte aos seguintes parâmetros:

service_name (cadeia de caracteres, obrigatório)

Nome totalmente qualificado do Cortex Search Service a ser consultado.

query (cadeia de caracteres, opcional)

Coluna contendo a cadeia de caracteres de consulta para a pesquisa do serviço.

multi_index_query (variante, opcional)

Um objeto que especifica uma ou mais entradas de consulta de vetor ou palavra-chave para pesquisar no índice de serviço. Consulte multi_index_query para obter detalhes sobre como construir este parâmetro.

Nota

Por motivos de desempenho, o multi_index_query oferece suporte a no máximo uma entrada de índice vetorial na matriz de consulta.

filter (variante, opcional)

Coluna contendo objetos de filtro a serem aplicados aos resultados da pesquisa.

limit (inteiro, opcional)

Número máximo de resultados a serem retornados por consulta. Padrão: sem valor. 10

options (variante, opcional)

Coluna contendo um objeto VARIANT com configurações opcionais por consulta. As chaves de nível superior compatíveis incluem:

• scoring_config (objeto, opcional): mesma estrutura que o parâmetro scoring_config para consultas interativas do Cortex Search (Python, REST ou SEARCH_PREVIEW). Use-o para personalizar a classificação da consulta em lote dessa linha. Consulte Personalizando a pontuação do Cortex Search.

• replicas (inteiro, opcional): quantas cópias do índice de pesquisa atendem à consulta em lote dessa linha. Padrão: sem valor. 2. Valores mais altos podem melhorar a taxa de transferência; o custo de atendimento aumenta proporcionalmente à contagem de réplicas.

• experimental (objeto, opcional): objeto reservado para comportamento de pesquisa experimental ou de versão preliminar. Os campos e a semântica podem mudar sem aviso prévio. Use somente quando a documentação ou o suporte Snowflake orientarem você a definir chaves específicas.

Notas de uso¶

• A taxa de transferência da função de pesquisa em lote pode variar dependendo da quantidade de dados indexados no Cortex Search Service consultado e da complexidade das consultas de pesquisa. Execute a função em um pequeno número de consultas para medir a taxa de transferência da sua carga de trabalho específica. Em geral, as consultas em serviços maiores com mais condições de filtro têm uma taxa de transferência menor.

• A taxa de transferência da função de pesquisa em lote, o número de consultas de pesquisa processadas por segundo, não é influenciada pelo tamanho do warehouse usado para a consulta.

• Como a pesquisa em lote ativa recursos dedicados para processar cada trabalho, ela incorre em latência de inicialização adicional. Se você precisa executar menos de 2.000 consultas, normalmente obtém resultados mais rápidos usando a Cortex Search API interativa (Python ou API REST) em vez da pesquisa em lote.

• Diferente da Cortex Search API interativa, a função de pesquisa em lote pode consultar serviços que estão suspensos.

• Um único Cortex Search Service pode ser consultado no modo interativo e em lote simultaneamente sem qualquer degradação no desempenho ou na taxa de transferência da consulta interativa. Recursos de computação separados são usados para processar consultas interativas e em lote.

Considerações sobre custo¶

A pesquisa em lote tem três componentes de custo:

Custo de processamento

Uma cobrança baseada no tamanho dos dados do índice de pesquisa e na duração do trabalho de pesquisa em lote, excluindo o tempo de inicialização. Também reflete o valor replicas em options (padrão 2); consulte a opção replicas acima.

Custo de incorporação de consulta

Uma cobrança pelo número de tokens incorporados como resultado das consultas de entrada. Ao contrário do Cortex Search interativo, a incorporação de consulta não é gratuita para pesquisa em lote.

Custo do warehouse virtual

Uma cobrança pela computação do warehouse virtual usada para executar o trabalho em lote.

Para rastreamento de uso, consulte a visualização do uso da conta CORTEX_SEARCH_BATCH_QUERY_USAGE_HISTORY. Para obter mais informações sobre os custos do Cortex Search, consulte Considerações sobre custo.

Disponibilidade regional¶

A pesquisa em lote está disponível em todas as regiões onde o Cortex Search está disponível. Consulte Disponibilidade regional para conferir a lista completa das regiões compatíveis.

Exemplo de uso¶

Neste exemplo, combine os produtos em um formulário de pedido enviado pelo usuário com um catálogo de produtos «ouro». A chamada CORTEX_SEARCH_BATCH usa options para que as incorporações sejam computadas sem o prefixo de consulta de pesquisa padrão; consulte Desabilitando o prefixo de consulta para incorporações de vetores. Use essa configuração somente quando você tiver avaliado o impacto na qualidade do resultado.

-- Create the golden product catalog with canonical product names
CREATE OR REPLACE TABLE golden_catalog (product_name TEXT);
INSERT INTO golden_catalog VALUES
  ('Wireless Bluetooth Headphones'),
  ('Wireless Noise-Canceling Earbuds'),
  ('USB-C Charging Cable 6ft'),
  ('Portable Power Bank 10000mAh');

-- Create Cortex Search Service on the golden catalog
CREATE CORTEX SEARCH SERVICE golden_product_service
ON product_name
WAREHOUSE = <warehouse_name>
TARGET_LAG = '1 day'
AS
SELECT product_name FROM golden_catalog;

-- Create a table of user-submitted products (may contain variations or typos)
CREATE OR REPLACE TABLE submitted_products (product TEXT);
INSERT INTO submitted_products VALUES
  ('bluetooth headphones wireless'),
  ('usb c cable');

-- For each user-submitted product, query the service for the two closest golden results
SELECT
  q.product, s.*
FROM submitted_products AS q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => 'golden_product_service',
    query => q.product,
    limit => 2,
    options => OBJECT_CONSTRUCT(
        'scoring_config', OBJECT_CONSTRUCT(
            'disable_vector_embedding_query_prefix', true
        )
    )
) AS s;

O exemplo a seguir usa multi_index_query para enviar incorporações pré-computadas como entrada de consulta em vez de texto bruto. Aqui, a tabela de origem my_db.my_schema.product_embeddings contém uma coluna embedding com vetores pré-computados, e o Cortex Search Service my_db.my_schema.golden_product_service foi criado com uma configuração «traga seu próprio vetor» (Bring-Your-Own-Vector, BYOV). Para obter detalhes sobre a construção de multi_index_query, consulte multi_index_query.

SELECT
    q.product_name,
    s.*
FROM (
    SELECT
        product_name,
        embedding::ARRAY AS emb_arr
    FROM my_db.my_schema.product_embeddings
    LIMIT 100000
) q,
LATERAL CORTEX_SEARCH_BATCH(
    service_name => 'my_db.my_schema.golden_product_service',
    multi_index_query => OBJECT_CONSTRUCT(
        'EMBEDDING', ARRAY_CONSTRUCT(
            OBJECT_CONSTRUCT('vector', q.emb_arr)
        )
    ),
    limit => 5
) s;