Consultas de dados de paginação com N1QL

M. David Allen é um engenheiro de software full-stack e empresário que, há mais de uma década, trabalha com praticamente todas as linguagens de programação e tipos diferentes de sistemas de banco de dados que pode utilizar. David trabalhou anteriormente em vários setores, incluindo finanças, saúde e governo, concentrando-se normalmente em desafios de integração de dados em grande escala, transição de pesquisa aplicada e inovação tecnológica. Ele tem mestrado pela Virginia Commonwealth University, mas desde que deixou a educação formal continua sendo um estudante permanente de tecnologia.

Configuração

Para este tutorial, usaremos o conjunto de dados de amostras de cerveja que vem com o Couchbase, de modo que será fácil acompanhar o processo. Se você ainda não tiver o Couchbase instalado, poderá começar rapidamente com o docker e o seguindo as instruções simples na página da imagem do docker do couchbase para configurar uma instância rápida do Couchbase para testes. Basta executar o comando docker run -d -name db -p 8091-8094:8091-8094 -p 11210:11210 Couchbase com o Couchbase instalado para começarmos. Depois de seguir alguns prompts de configuração descritos nessa página, estamos prontos para trabalhar com alguns dados.

Casos de uso - O que é paginação e por que usá-la?

Vamos considerar uma necessidade muito comum: em nosso hipotético aplicativo front-end de cerveja, queremos mostrar aos nossos usuários uma tabela de cervejas e permitir que eles avaliem cada uma delas. O problema é que o banco de dados tem mais de 5.000 cervejas. Seria um desperdício enviar todo o conjunto de dados para o navegador todas as vezes, o que tornaria o carregamento da página do seu aplicativo Web muito lento.

Muito melhor seria mostrar ao usuário apenas as primeiras 10 cervejas. Então, ao clicar em um botão "Next" (Próximo) para ir para a próxima página ou, melhor ainda, ao usar um plug-in de rolagem infinita (como o ngInfiniteScroll para angular ou react-infinite para reagir), o usuário pode ver progressivamente mais registros do banco de dados.

Mostre-me o código!

Isso retorna os dados que você espera:

Para obter a segunda página de resultados, você só precisa adicionar o LIMIT ao OFFSET. Por exemplo, OFFSET 10 LIMIT 10 seria a segunda página. Para generalizar, quantos registros devem ser ignorados com o OFFSET para chegar à enésima página? Será sempre n * tamanho da página.

Usando essa matemática simples, podemos generalizar isso para qualquer cenário. E se quiséssemos mostrar 20 resultados por vez e o usuário quisesse ir direto para a 11ª página? Sem problemas, é só LIMIT 20 OFFSET 20 * 11. Assim, os pontos de extremidade do aplicativo, quer estejam pesquisando o banco de dados ou apenas listando as cervejas por nome, podem usar exatamente a mesma lógica de consulta todas as vezes. Não importa a complexidade da consulta, basta ajustar LIMIT e OFFSET e estaremos todos na mesma página.

Como isso funciona?

A mágica aqui é a combinação de três cláusulas N1QL:  LIMITE, DESLOCAMENTOe ORDER BY. Vamos dar uma olhada rápida em cada um deles, pois todos são necessários para realizar o trabalho.

• LIMITE faz exatamente o que diz. Ele limita quantos registros o Couchbase retornará e efetivamente impõe o tamanho da nossa página (queremos apenas 10 cervejas por vez, nunca 5.000)
• DESLOCAMENTO informa ao Couchbase quantos registros devem ser pulados antes de começar a retornar os documentos. Se você estiver familiarizado com SQL, ela se comporta exatamente como SKIP no SQL. A cláusula OFFSET é como avançamos por todo o conjunto de dados, um pedaço de cada vez.
• ORDER BY garante uma determinada ordem retornada pelo banco de dados. Isso é importante porque o Couchbase não garante nenhuma ordem específica dos resultados, a menos que você a solicite. Em nossa consulta anterior, a Cream Ale #17 apareceu como o primeiro resultado ao ordenar por nome. Se não usássemos ORDER BY, não poderíamos prever em que parte do conjunto o #17 Cream Ale apareceria, e é possível que ele aparecesse em mais de uma página, dependendo de como o Couchbase executou a consulta!

Em termos simples, imagine o Couchbase criando uma lista de todas as cervejas ordenadas por nome (ORDER BY). A paginação está apenas pegando lotes de 10 delas (LIMIT 10). Cada página começa pulando toda a lista ordenada até o ponto de partida da próxima página (OFFSET).

EXPLIQUE-SE, Couchbase.

Um exemplo final: como em qualquer consulta N1QL, você pode obter muitas informações sobre como ela funciona simplesmente colocando "EXPLAIN" na frente dela. Isso diz ao Couchbase para informar o que ele está planejando fazer.

(Experimente você mesmo essa consulta!) O resultado é bastante longo, portanto não vamos colá-lo aqui, mas vamos resumir o que o Couchbase está fazendo com essa consulta.

1. Primeiro, ele faz uma varredura primária do balde de amostras de cerveja e busca documentos.
2. Em paralelo, ele filtra para:
   1. Registros que têm um brewery_id (isso nos diz que o registro é uma cerveja, não um documento da cervejaria)
   2. Ele projeta o nome, a categoria e as propriedades de teor alcoólico (o que pedimos)
3. Em seguida, ele ordena os resultados por nome
4. O deslocamento é aplicado em seguida, pulando efetivamente os primeiros X registros e não os retornando de forma alguma.
5. Por fim, ele aplica o LIMIT lendo os próximos n registros e ignorando todos os posteriores.

Quando terminamos?

Se estivermos percorrendo nossos dados uma página de cada vez, também precisaremos saber quando parar. Há duas maneiras de abordar isso: por um lado, se continuarmos avançando indefinidamente pelas páginas, acabaremos ficando sem dados. Por outro lado, você poderia simplesmente pré-computar quantas páginas estão presentes e, em seguida, iterar por elas até atingir esse número.

O que acontece se solicitarmos a sétima página de 1.000 resultados, sabendo muito bem que não há nenhum conjunto de documentos desse tipo?

Bem, não se preocupe - se você passar do final, obterá apenas uma matriz vazia.

Para fins de registro, a matriz vazia também é o que você obterá se pedir algo sem sentido, como:

Wait....what?!?! Essa consulta está pedindo para iniciar 5 registros antes do início do conjunto de saída e retornar não mais do que -10 registros. 5 registros antes do início não é nada. E não mais do que -10 registros não é nada. Portanto, você obtém....nothing!

Esse comportamento é muito conveniente; fica claro quando não há mais registros e também funciona bem com várias outras suposições em diferentes camadas de software. Se você já usou APIs REST compatíveis com paginação, geralmente é assim que elas funcionam. Por exemplo, você pode facilmente imaginar um ponto de extremidade da API REST com a seguinte aparência: http://cool-app.com/beers?limit=10&page=6000. Se você escreveu esse endpoint no seu back-end, pode ver facilmente como ele geraria uma consulta N1QL correspondente e, mesmo que o usuário fornecesse um número de página diferente, seu endpoint faria a coisa certa.

Mas e se eu quiser saber com antecedência quantas páginas haverá?

Isso também é simples. Se soubermos que cada página tem n registros e soubermos o número total de registros, poderemos dividir o total por n, pegar o teto desse número e isso nos dirá quantas páginas em potencial existem no Couchbase.

Isso resulta no meu banco de dados local 590. Como há exatamente 5.891 documentos sobre cerveja, isso significa que haverá 589 conjuntos de 10, e a página final terá apenas 1 documento. Como 5.891 / 10 = 589,1, usamos o N1QL Função CEIL para obter um número inteiro de páginas, pois qualquer aplicativo front-end não exibirá 0,1 de uma página.

Lembre-se de que ainda precisamos da cláusula WHERE aqui, para reduzir os documentos a apenas documentos sobre cerveja, excluindo cervejarias e outros documentos. Se a cláusula WHERE estivesse faltando, você obteria o número errado, com certeza.

Esta postagem faz parte do Programa de Redação da Comunidade Couchbase