Os aplicativos da Web geralmente paginam os dados conforme eles são apresentados aos usuários. O usuário final recebe uma página de resultados e, quando navega para a próxima página, o próximo lote de resultados é recuperado e apresentado. Nesta página, descrevemos como adicionar paginação aos resultados da pesquisa ao realizar uma pesquisa de texto completo no Spanner.
Opções de paginação
Cada página de um conjunto de resultados paginados é buscada por uma consulta independente, e o Spanner não mantém nenhum estado entre as páginas. Qualquer alteração entre consultas consecutivas, como os dados ou a ordem de classificação, pode tornar os resultados inconsistentes: quando o aplicativo passa para a próxima página, as linhas podem ser ignoradas ou as linhas da página anterior podem ser repetidas. Esse comportamento se aplica a todas as consultas paginadas no Spanner, mas o método de paginação escolhido determina o quanto essas mudanças afetam os resultados.
Há duas maneiras de implementar consultas paginadas no Spanner: paginação baseada em chave (recomendada) e paginação baseada em deslocamento.
A paginação baseada em chaves é um método para recuperar resultados da pesquisa em partes menores e mais gerenciáveis, garantindo resultados consistentes em todas as solicitações. Um identificador exclusivo (a "chave") do último resultado de uma página é usado como ponto de referência para buscar o próximo conjunto de resultados.
O Spanner geralmente recomenda o uso da paginação baseada em chaves, exceto ao paginar resultados de pesquisa classificados. Embora a paginação baseada em deslocamento seja mais fácil de implementar, ela tem duas desvantagens significativas:
- Custo de consulta mais alto: a paginação baseada em deslocamento precisa recuperar e descartar os resultados de todas as páginas anteriores, o que aumenta os custos e diminui o desempenho.
- Resultados inconsistentes: em consultas paginadas, cada página normalmente é recuperada em um carimbo de data/hora de leitura diferente. Por exemplo, a primeira página pode vir de uma consulta às 13h, e a próxima de uma consulta às 13h10. Entre as consultas, qualquer linha inserida ou excluída antes do deslocamento atual muda as linhas que a seguem, de modo que as linhas são ignoradas ou repetidas nas páginas.
Já a paginação baseada em chave usa um identificador exclusivo (chave) do último resultado de uma página para buscar o próximo conjunto de resultados. Essa abordagem garante uma recuperação eficiente e resultados mais consistentes: a próxima página é retomada da última chave da página anterior, de modo que apenas as gravações simultâneas que movem linhas além desse limite afetam os resultados. Por exemplo, uma linha recém-inserida que é classificada antes dessa chave é ignorada, enquanto uma linha retornada anteriormente que é atualizada para ser classificada depois dessa chave é repetida.
Para garantir a estabilidade nos resultados da página, o aplicativo pode emitir todas as consultas
para páginas diferentes no mesmo carimbo de data/hora. No entanto, isso pode falhar se a
consulta exceder o período de retenção
da versão
(o padrão é 1 hora). Por exemplo, essa falha acontece se version_gc for
de uma hora, e o usuário final buscar os primeiros resultados às 13h e clicar em Próxima
às 15h.
Usar paginação baseada em chave
A paginação baseada em chave lembra o último item da página anterior e o usa como
ponto de partida para a consulta da próxima página. Para isso, a consulta precisa retornar as colunas especificadas na cláusula ORDER BY e limitar o número de linhas usando LIMIT.
Para que a paginação baseada em chave funcione, a consulta precisa ordenar os resultados por uma ordem total estrita. A maneira mais fácil de conseguir um é escolher qualquer ordem total e adicionar colunas de desempate, se necessário. Na maioria dos casos, a ordem total é a ordem de classificação do índice da Pesquisa, e a combinação exclusiva de colunas é a chave primária da tabela base.
Usando nosso esquema de amostra Albums, para a primeira página, a consulta é semelhante a esta:
GoogleSQL
SELECT AlbumId, ReleaseTimestamp
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, "fifth symphony")
ORDER BY ReleaseTimestamp DESC, AlbumId
LIMIT 10;
PostgreSQL
SELECT albumid, releasetimestamp
FROM albums
WHERE spanner.search(albumtitle_tokens, 'fifth symphony')
ORDER BY releasetimestamp DESC, albumid
LIMIT 10;
O AlbumId é o critério de desempate, já que ReleaseTimestamp não é uma chave. Pode
haver dois álbuns diferentes com o mesmo valor para ReleaseTimestamp.
Para retomar, o aplicativo executa a mesma consulta novamente, mas com uma cláusula WHERE
que restringe os resultados da página anterior. A condição adicional
precisa considerar a direção da chave (ascendente ou descendente), os critérios de desempate
e a ordem dos valores NULL para colunas anuláveis.
No nosso exemplo, AlbumId é a única coluna de chave (em ordem crescente) e não pode ser NULL. Portanto, a condição é a seguinte:
GoogleSQL
SELECT AlbumId, ReleaseTimestamp
FROM Albums
WHERE (ReleaseTimestamp < @last_page_release_timestamp
OR (ReleaseTimestamp = @last_page_release_timestamp
AND AlbumId > @last_page_album_id))
AND SEARCH(AlbumTitle_Tokens, @p)
ORDER BY ReleaseTimestamp DESC, AlbumId ASC
LIMIT @page_size;
PostgreSQL
Este exemplo usa os parâmetros de consulta $1, $2, $3 e $4, que estão vinculados aos valores especificados para last_page_release_timestamp, last_page_album_id, query e page_size, respectivamente.
SELECT albumid, releasetimestamp
FROM albums
WHERE (releasetimestamp < $1
OR (releasetimestamp = $1
AND albumid > $2))
AND spanner.search(albumtitle_tokens, $3)
ORDER BY releasetimestamp DESC, albumid ASC
LIMIT $4;
O Spanner interpreta esse tipo de condição como pesquisável. Isso significa que o Spanner não lê o índice dos documentos que você está filtrando. Essa otimização é o que torna a paginação baseada em chaves muito mais eficiente do que a paginação baseada em deslocamento.
Usar paginação baseada em deslocamento
A paginação baseada em deslocamento usa as cláusulas LIMIT e OFFSET da consulta SQL
para simular páginas. O valor LIMIT indica o número de resultados por página.
O valor OFFSET é definido como zero para a primeira página, o tamanho da página para a segunda
página e o dobro do tamanho da página para a terceira página.
Por exemplo, a consulta a seguir busca a terceira página, com um tamanho de página de 50:
GoogleSQL
SELECT AlbumId
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, "fifth symphony")
ORDER BY ReleaseTimestamp DESC, AlbumId
LIMIT 50 OFFSET 100;
PostgreSQL
SELECT albumid
FROM albums
WHERE spanner.search(albumtitle_tokens, 'fifth symphony')
ORDER BY releasetimestamp DESC, albumid
LIMIT 50 OFFSET 100;
Observações sobre o uso:
- A cláusula
ORDER BYé altamente recomendada para garantir uma ordenação consistente entre as páginas. - Em consultas de produção, use parâmetros de consulta em vez de constantes para especificar
LIMITeOFFSETpara tornar o armazenamento em cache de consultas mais eficiente. Para mais informações, consulte Parâmetros de consulta.
Paginar resultados da pesquisa classificados
O Spanner recomenda a paginação baseada em deslocamento para
consultas classificadas, que ordenam
os resultados pelo valor da função SCORE, em vez de pelas colunas de chave da
tabela. Embora seja possível incluir a última pontuação da página anterior na cláusula WHERE
da próxima página, essa condição não é pesquisável e, portanto, não
oferece os benefícios de custo e desempenho da paginação baseada em chaves. Além disso,
os valores de SCORE não são comparáveis entre as versões do pontuador. Portanto, a paginação baseada em deslocamento
produz menos linhas ignoradas ou repetidas quando a versão do pontuador
muda.
Para paginar os resultados classificados, ordene pela pontuação com a chave primária como critério de desempate e use LIMIT e OFFSET para paginar. Por exemplo, a consulta a seguir
busca a primeira página com um tamanho de página de dois:
GoogleSQL
SELECT
AlbumId,
SCORE(AlbumTitle_Tokens, @p) AS Score
FROM Albums
WHERE SEARCH(AlbumTitle_Tokens, @p)
ORDER BY Score DESC, AlbumId
LIMIT 2 OFFSET 0;
PostgreSQL
Este exemplo usa o parâmetro de consulta $1, que está vinculado à string de consulta.
SELECT
albumid,
spanner.score(albumtitle_tokens, $1) AS score
FROM albums
WHERE spanner.search(albumtitle_tokens, $1)
ORDER BY score DESC, albumid
LIMIT 2 OFFSET 0;
O valor de SCORE depende da
versão do avaliador.
O Spanner usa a versão padrão do pontuador do banco de dados, a menos que a
consulta defina uma. Uma nova versão do pontuador pode mudar a ordem dos resultados. Portanto, se
a versão do pontuador mudar entre duas páginas da mesma consulta paginada, as
páginas podem ficar inconsistentes. Por exemplo, suponha que os álbuns correspondentes tenham as
seguintes pontuações em duas versões de pontuação:
| AlbumId | Pontuação com a versão 1 | Pontuação com a versão 2 |
|---|---|---|
| 1 | 0,9 | 0,7 |
| 2 | 0,8 | 0,95 |
| 3 | 0,7 | 0,6 |
| 4 | 0,6 | 0,85 |
Com a versão 1 e um tamanho de página de dois, a primeira página retorna os álbuns 1 e 2. Se
a versão do pontuador mudar para a versão 2 antes que a segunda página seja buscada, ela
será calculada com OFFSET 2 na ordem da versão 2, em que os
álbuns são classificados como 2, 4, 1, 3. Como resultado, a segunda página retorna os álbuns 1 e
3, então o álbum 1 é repetido e o álbum 4 é ignorado.
As mudanças na versão do pontuador são raras: a versão padrão do pontuador do banco de dados só muda quando você a atualiza ou quando o Spanner migra o banco de dados para uma versão padrão mais recente, e apenas as consultas paginadas que estão em andamento naquele momento são afetadas. Para a maioria dos aplicativos, essa breve inconsistência é aceitável, e o Spanner recomenda usar a versão padrão do avaliador para que você sempre se beneficie das melhorias mais recentes do avaliador.
Se você precisar de mais controle sobre a mudança, há duas opções:
- Nível do banco de dados: defina você mesmo a versão padrão do avaliador do banco de dados, conforme descrito em Definir a versão padrão do avaliador do banco de dados. Definir essa opção não evita a inconsistência, mas permite que você escolha quando a troca vai acontecer (por exemplo, durante um período de pouco tráfego) ou permaneça na versão atual até que esteja tudo pronto.
- Nível de consulta: fixe a versão do avaliador na consulta e a carregue no estado de paginação, conforme descrito nas etapas a seguir. Essa abordagem mantém as consultas paginadas em andamento na versão do avaliador em que começaram, para que a mudança não as afete. No entanto, essas consultas continuam sujeitas a mudanças de linhas devido a gravações simultâneas, como em qualquer paginação baseada em deslocamento. Essa abordagem é mais complexa de implementar e não é necessária para a maioria dos aplicativos.
Para fixar a versão do avaliador no nível da consulta, siga estas etapas:
Defina a versão do avaliador explicitamente no argumento
optionsda funçãoSCORE. Use a mesma consulta para cada página, com o deslocamento definido como0para a primeira página:GoogleSQL
SELECT AlbumId, SCORE(AlbumTitle_Tokens, @p, options=>JSON_OBJECT('version', @score_version)) AS Score FROM Albums WHERE SEARCH(AlbumTitle_Tokens, @p) ORDER BY Score DESC, AlbumId LIMIT @page_size OFFSET @offset;PostgreSQL
Este exemplo usa os parâmetros de consulta
$1,$2,$3e$4, que estão vinculados à string de consulta, as opções de pontuação como um valorJSONB, como{"version": 2}, o tamanho da página e o deslocamento, respectivamente.SELECT albumid, spanner.score(albumtitle_tokens, $1, options => $2) AS score FROM albums WHERE spanner.search(albumtitle_tokens, $1) ORDER BY score DESC, albumid LIMIT $3 OFFSET $4;Para a primeira página, use a versão do pontuador da configuração do aplicativo. Normalmente, é o mesmo valor da versão padrão do pontuador do banco de dados, para que as consultas paginadas e outras sejam classificadas da mesma forma.
Armazene a versão do avaliador que você vinculou, junto com o deslocamento da próxima página, no estado de paginação, por exemplo, em um cookie de sessão ou no token de página opaco retornado pela API.
Para cada página subsequente, transmita a versão do avaliador armazenada na consulta, em vez de ler a versão da configuração atual do aplicativo. Essa abordagem mantém os resultados paginados consistentes em todas as mudanças de versão do pontuador, seja o padrão do banco de dados ou a atualização da configuração do aplicativo.
A versão do marcador fixada na consulta tem precedência sobre a versão padrão do marcador do banco de dados. Para mover consultas fixadas para uma versão mais recente do pontuador, mude o valor na configuração do aplicativo.
A seguir
- Saiba como classificar os resultados da pesquisa.
- Saiba como fazer uma pesquisa de substring.
- Saiba como misturar consultas de texto completo e não textuais.
- Saiba como pesquisar várias colunas.