Visão geral da consulta

Nesta página, descrevemos a função SEARCH e o modo de consulta avançada, que são usados para realizar consultas de pesquisa de texto completo em tabelas do Spanner.

Consultar um índice de pesquisa

O Spanner oferece 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 junções.

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 consulta de pesquisa bruta por padrão. Sintaxes alternativas podem ser especificadas usando o argumento SEARCH dialect.

Dialeto rquery

O dialeto padrão é 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 tokenizador 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

A linguagem de palavras é como 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ções, não como uma pesquisa de frase, e são ignoradas.

Com o dialeto de palavras, AND é aplicado implicitamente a todos os termos e é obrigatório durante a correspondência. Ele segue as mesmas regras do tokenizador 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.

Dialeto words_phrase

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

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

Para informações sobre como usar o dialeto words_phrase, consulte a 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 tokens e um modo mais avançado chamado enhance_query. Quando ativado, o enhance_query expande a consulta de pesquisa para incluir termos relacionados e sinônimos, 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 tempo 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 aprimorando os algoritmos de melhoria de consultas. Como resultado, uma consulta com enhance_query == true pode gerar resultados ligeiramente 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 procura, o que pode aumentar um pouco a latência.

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 usará um plano alternativo ou falhará se não houver um.

As consultas precisam atender às seguintes condições:

  • As funções SEARCH e SEARCH_SUBSTRING exigem um índice de pesquisa. O Spanner não é compatível com essas funções em consultas na tabela de base ou em índices secundários.

  • Í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 consultas 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 tabela e definição de í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 estã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 aceitar valores nulos, o esquema e a consulta precisarão excluir as linhas em que a coluna de ordem de classificação é NULL. Para mais detalhes, consulte Ordem de classificação do índice de pesquisa.

  • Se o índice de pesquisa for filtrado como NULL, a consulta precisará incluir a mesma expressão de filtragem 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.

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

Não é recomendável usar índices de pesquisa e funções de pesquisa 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/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 vai falhar por padrão. Ela também falha se a consulta contiver alguma das funções de pesquisa. Esse comportamento pode ser substituído com a dica @{ALLOW_SEARCH_INDEXES_IN_TRANSACTION=TRUE} no nível da instrução do GoogleSQL, mas as consultas ainda estão sujeitas a conflitos de bloqueio.

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

Parâmetros de consulta

Os argumentos de consulta 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 permitem o valor do parâmetro de consulta.

Seleção de índice

Normalmente, o Spanner seleciona o índice mais eficiente para uma consulta usando a modelagem baseada em custos. No entanto, a dica FORCE_INDEX instrui explicitamente o Spanner a usar um índice de pesquisa específico. Por exemplo, o código a seguir 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 ideia 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 com o banco de dados tem vários benefícios:

  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, além das posições dos caracteres a serem destacados. O cliente pode escolher como mostrar o snippet ao usuário final (por exemplo, usando texto destacado ou em negrito).

Por exemplo, o comando 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