Visão geral da consulta

Esta página descreve a função SEARCH e o modo de consulta aprimorado, que são usados para executar consultas de pesquisa de texto completo em tabelas do Spanner.

Consultar um índice de pesquisa

O Spanner fornece a função SEARCH para usar em consultas de índice de pesquisa. Um exemplo de caso de uso seria um aplicativo em que os usuários inserem texto em uma caixa de pesquisa, e o aplicativo envia a entrada do usuário diretamente para a função SEARCH. A função SEARCH usaria um índice de pesquisa para encontrar esse texto.

A função SEARCH requer dois argumentos:

  • Um nome de índice de pesquisa
  • Uma consulta de pesquisa

A função SEARCH só funciona quando um índice de pesquisa é definido. A função SEARCH pode ser combinada com qualquer construção SQL arbitrária, como filtros, agregações ou mesclagens.

A função SEARCH não pode ser usada com consultas de transação.

A consulta a seguir usa a função SEARCH para retornar todos os álbuns que têm friday ou monday no título:

GoogleSQL 

SELECT AlbumId
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, 'friday OR monday')

PostgreSQL

Este exemplo usa spanner.search.

SELECT albumid
FROM albums
WHERE spanner.search(albumtitle_tokens, 'friday OR monday')

Consulta de pesquisa

As consultas de pesquisa usam a sintaxe da consulta de pesquisa bruta por padrão. Sintaxes alternativas podem ser especificadas usando o argumento dialect SEARCH.

Dialeto de rquery

O dialeto padrão é a consulta de pesquisa bruta. O Spanner usa uma linguagem específica de domínio (DSL) chamada rquery.

A linguagem rquery segue as mesmas regras do tokenizer de texto simples ao dividir a consulta de pesquisa de entrada em termos distintos. Isso inclui a segmentação de idiomas asiáticos.

Para informações sobre como usar o rquery, consulte Sintaxe do rquery.

dialeto de palavras

O Dialecto de palavras é como o rquery, mas mais simples. Ele não usa operadores especiais. Por exemplo, OR é tratado como um termo de pesquisa em vez de um operador de disjunção. As aspas duplas são tratadas como pontuação em vez de uma pesquisa de frase e são ignoradas.

Com o dialeto de palavras, AND é aplicado implicitamente a todos os termos e é necessário durante a correspondência. Ele segue as mesmas regras do tokenizer de texto simples ao dividir a consulta de pesquisa de entrada em termos.

Para informações sobre como usar o dialeto de palavras, consulte sintaxe de palavras.

words_phrase dialect

O dialeto words_phrase não usa operadores especiais, e todos os termos são tratados como uma frase, o que significa que os termos precisam ser adjacentes e na ordem especificada.

Assim como o rquery, o dialeto words_phrase segue as mesmas regras do tokenizer de texto simples ao dividir a consulta de pesquisa de entrada em termos.

Para saber como usar o dialeto words_phrase, consulte sintaxe de frase de palavras.

Modo de consulta aprimorado

O Spanner oferece dois modos de pesquisa de texto completo: uma pesquisa básica baseada em token e um modo mais avançado chamado enhance_query. Quando ativado, enhance_query expande a consulta de pesquisa para incluir termos e sinônimos relacionados, aumentando a probabilidade de encontrar resultados relevantes.

Para ativar essa opção, defina o argumento opcional enhance_query=>true na função SEARCH. Por exemplo, a consulta de pesquisa hotl cal corresponde ao álbum Hotel California.

GoogleSQL 

SELECT AlbumId
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, 'hotl cal', enhance_query=>true)

PostgreSQL 

SELECT albumid
FROM albums
WHERE spanner.search(albumtitle_tokens, 'hotl cal', enhance_query=>true)

O modo enhance_query é uma opção de consulta. Isso não afeta a tokenização. É possível usar o mesmo índice de pesquisa com ou sem enhance_query.

O Google está sempre melhorando os algoritmos de aprimoramento de consultas. Como resultado, uma consulta com enhance_query == true pode gerar resultados um pouco diferentes ao longo do tempo.

Quando o modo enhance_query está ativado, ele pode aumentar o número de termos que a função SEARCH está procurando, o que pode aumentar um pouco a latência.

Por exemplo, a consulta a seguir usa um tempo limite de três segundos e falha se enhance_query estiver indisponível:

GoogleSQL 

@{require_enhance_query=true, enhance_query_timeout_ms=3000}
SELECT AlbumId
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, 'fast car', enhance_query=>true)

PostgreSQL 

/*@require_enhance_query=true, enhance_query_timeout_ms=3000*/
SELECT albumid
FROM albums
WHERE spanner.search(albumtitle_tokens, 'fast car', enhance_query=>true)

Requisitos de consulta SQL

Há várias condições que uma consulta SQL precisa atender para usar um índice de pesquisa. Se essas condições não forem atendidas, a consulta vai usar um plano de consulta alternativo ou falhar se nenhum plano alternativo existir.

As consultas precisam atender aos seguintes requisitos:

  • As funções SEARCH e SEARCH_SUBSTRING exigem um índice de pesquisa. O Spanner não oferece suporte a essas funções em consultas à tabela base ou aos índices secundários.

  • Os índices particionados precisam ter todas as colunas de partição vinculadas por uma condição de igualdade na cláusula WHERE da consulta.

    Por exemplo, se um índice de pesquisa for definido como PARTITION BY x, y, a consulta precisará ter uma conjunção na cláusula WHERE de x = <parameter or constant> AND y = <parameter or constant>. Esse índice de pesquisa não é considerado pelo otimizador de consulta se essa condição estiver ausente.

  • Todas as colunas TOKENLIST referenciadas pelos operadores SEARCH e SEARCH_SUBSTRING precisam ser indexadas no mesmo índice de pesquisa.

    Por exemplo, considere a seguinte definição de tabela e índice:

    GoogleSQL 

    CREATE TABLE Albums (
    AlbumId STRING(MAX) NOT NULL,
    AlbumTitle STRING(MAX),
    AlbumStudio STRING(MAX),
    AlbumTitle_Tokens TOKENLIST AS (TOKENIZE_FULLTEXT(AlbumTitle)) HIDDEN,
    AlbumStudio_Tokens TOKENLIST AS (TOKENIZE_FULLTEXT(AlbumStudio)) HIDDEN
) PRIMARY KEY(AlbumId);

CREATE SEARCH INDEX AlbumsTitleIndex ON Albums(AlbumTitle_Tokens);
CREATE SEARCH INDEX AlbumsStudioIndex ON Albums(AlbumStudio_Tokens);

    PostgreSQL 

    CREATE TABLE albums (
    albumid character varying NOT NULL,
    albumtitle character varying,
    albumstudio character varying,
    albumtitle_tokens spanner.tokenlist GENERATED ALWAYS AS (spanner.tokenize_fulltext(albumtitle)) VIRTUAL HIDDEN,
    albumstudio_tokens spanner.tokenlist GENERATED ALWAYS AS (spanner.tokenize_fulltext(albumstudio)) VIRTUAL HIDDEN,
PRIMARY KEY(albumid));

CREATE SEARCH INDEX albumstitleindex ON albums(albumtitle_tokens);
CREATE SEARCH INDEX albumsstudioindex ON albums(albumstudio_tokens);

    A consulta a seguir falha porque não há um único índice de pesquisa que indexe AlbumTitle_Tokens e AlbumStudio_Tokens:

    GoogleSQL 

    SELECT AlbumId
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, @p1)
    AND SEARCH(AlbumStudio_Tokens, @p2)

    PostgreSQL

    Este exemplo usa os parâmetros de consulta $1 e $2, que são vinculados a "fast car" e "blue note", respectivamente.

    SELECT albumid
FROM albums
WHERE spanner.search(albumtitle_tokens, $1)
    AND spanner.search(albumstudio_tokens, $2)

  • Se a coluna de ordem de classificação for anulável, o esquema e a consulta precisarão excluir linhas em que a coluna de ordem de classificação for NULL. Para mais detalhes, consulte Ordem de classificação do índice de pesquisa.

  • Se o índice de pesquisa for filtrado por NULL, a consulta precisará incluir a mesma expressão de filtragem por NULL usada em um índice. Consulte Índices de pesquisa filtrados por NULL para mais detalhes.

  • Índices de pesquisa e funções de pesquisa não são compatíveis com DML, DML particionada ou consultas particionadas.

  • Os índices de pesquisa e as funções de pesquisa geralmente são usados em transações somente leitura. Se os requisitos do aplicativo permitirem resultados desatualizados, será possível melhorar a latência executando consultas de pesquisa com uma duração desatualizada de 10 segundos ou mais. Para mais informações, consulte Ler dados desatualizados. Isso é especialmente útil para consultas de pesquisa que se dividem em muitas divisões de índice.

Índices de pesquisa e funções de pesquisa não são recomendados em transações de leitura e gravação. Durante a execução, as consultas de pesquisa bloqueiam uma partição de índice inteira. Como resultado, uma alta taxa de consultas de pesquisa em transações de leitura e gravação pode causar conflitos de bloqueio que levam a picos de latência. Por padrão, os índices de pesquisa não são selecionados automaticamente em transações de leitura e gravação. Se uma consulta for forçada a usar um índice de pesquisa em uma transação de leitura e gravação, ela falhará por padrão. Ela também falha se a consulta contiver qualquer uma das funções de pesquisa. Esse comportamento pode ser substituído com a sugestão no nível da instrução @{ALLOW_SEARCH_INDEXES_IN_TRANSACTION=TRUE} do GoogleSQL, mas as consultas ainda estão sujeitas a conflitos de bloqueio.

Depois que as condições de qualificação do índice são atendidas, o otimizador de consulta tenta acelerar as condições de consulta que não são de texto (como Rating > 4). Se o índice de pesquisa não incluir a coluna TOKENLIST adequada, a condição não será acelerada e permanecerá como uma condição residual.

Parâmetros de consulta

Os argumentos de pesquisa são especificados como um literal ou um parâmetro de consulta. Recomendamos usar parâmetros de consulta para pesquisa de texto completo em vez de literais de string quando os argumentos permitirem o valor do parâmetro de consulta.

Seleção de índice

O Spanner normalmente seleciona o índice mais eficiente para uma consulta usando a modelagem baseada em custo. No entanto, a sugestão FORCE_INDEX instrui explicitamente o Spanner a usar um índice de pesquisa específico. Por exemplo, o seguinte mostra como forçar o Spanner a usar o AlbumsIndex:

GoogleSQL 

SELECT AlbumId
FROM Albums @{FORCE_INDEX=AlbumsIndex}
WHERE SEARCH(AlbumTitle_Tokens, "fifth symphony")

PostgreSQL 

SELECT albumid
FROM albums/*@force_index=albumsindex*/
WHERE spanner.search(albumtitle_tokens, 'fifth symphony')

Se o índice de pesquisa especificado não for qualificado, a consulta vai falhar, mesmo que haja outros índices de pesquisa qualificados.

Snippets nos resultados da pesquisa

Um snippet é um trecho de texto extraído de uma determinada string que dá aos usuários uma noção do que um resultado da pesquisa contém e por que ele é relevante para a consulta.

Por exemplo, o Gmail usa snippets para indicar a parte de um e-mail que corresponde à consulta de pesquisa:

Lista de snippets

Gerar um snippet no banco de dados tem várias vantagens:

  1. Conveniência: não é necessário implementar uma lógica para gerar snippets de uma consulta de pesquisa.
  2. Eficiência: os snippets reduzem o tamanho da saída do servidor.

A função SNIPPET cria o snippet. Ele retorna a parte relevante do valor da string original com as posições dos caracteres a serem destacados. O cliente pode escolher como mostrar o snippet para o usuário final (por exemplo, usando texto em negrito ou realçado).

Por exemplo, o código a seguir usa SNIPPET para extrair texto de AlbumTitle:

GoogleSQL 

SELECT AlbumId, SNIPPET(AlbumTitle, "Fast Car")
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, "Fast Car")

PostgreSQL

Este exemplo usa spanner.snippet.

SELECT albumid, spanner.snippet(albumtitle, 'Fast Car')
FROM albums
WHERE spanner.search(albumtitle_tokens, 'Fast Car')

A seguir