Consultas

Todos os endpoints de listagem da API suportam um conjunto comum de parâmetros de consulta para paginação, ordenação e filtragem.

Parâmetros comuns

Parâmetro	Tipo	Descrição
`page`	`number`	O número da página a obter (predefinição: 1).
`limit`	`number`	O número de itens a obter por página (predefinição: 10).
`sort`	`string`	O campo pelo qual ordenar. Usa o prefixo `-` para ordem descendente (ex.: `-createdAt`).
`where`	`object`	Objeto de consulta para filtrar resultados usando operadores.

Resposta paginada

Todos os endpoints de listagem devolvem uma resposta paginada com a seguinte estrutura:


{
  "docs": [...],           // Array of objects
  "totalDocs": number,     // Total number of documents
  "limit": number,         // Items per page
  "totalPages": number,    // Total number of pages
  "page": number,          // Current page number
  "pagingCounter": number, // Index of first item on current page
  "hasPrevPage": boolean,  // Whether a previous page exists
  "hasNextPage": boolean,  // Whether a next page exists
  "prevPage": number | null,
  "nextPage": number | null
}

Ordenação

Usa o parâmetro sort para ordenar os resultados por um campo específico.

Direção da ordenação

Ascendente (predefinição): ?sort=createdAt
Descendente: Prefixo com - → ?sort=-createdAt

Campos ordenáveis

Podes ordenar por qualquer campo de nível superior do objeto. Exemplos comuns:

Campo	Descrição
`createdAt`	Ordenar por data de criação
`updatedAt`	Ordenar por data da última modificação
`title`	Ordenar alfabeticamente por título

Exemplos

Mais recentes primeiro:


?sort=-createdAt

Mais antigos primeiro:


?sort=createdAt

Alfabeticamente por título:


?sort=title

Operadores where

O parâmetro where aceita um objeto de consulta que te permite filtrar resultados usando vários operadores:

Operador	Descrição
`equals`	O valor tem de ser exatamente igual.
`not_equals`	Devolve todos os documentos em que o valor não é igual.
`greater_than`	Para campos numéricos ou baseados em data.
`greater_than_equal`	Para campos numéricos ou baseados em data.
`less_than`	Para campos numéricos ou baseados em data.
`less_than_equal`	Para campos numéricos ou baseados em data.
`like`	A string tem de estar presente (sem distinção entre maiúsculas e minúsculas). Se for uma sequência de palavras, todas têm de estar presentes, em qualquer ordem.
`contains`	Tem de conter o valor introduzido, sem distinção entre maiúsculas e minúsculas.
`in`	O valor tem de estar na lista de valores delimitada por vírgulas.
`not_in`	O valor NÃO pode estar na lista de valores delimitada por vírgulas.
`exists`	Devolve apenas documentos onde o valor existe (`true`) ou não existe (`false`).

Lógica And / Or

Podes combinar várias consultas usando lógica and / or. Estas podem ser aninhadas tão profundamente quanto necessário para criar consultas complexas.

Exemplos de consultas

Filtrar por valor exato:


?where[status][equals]=COMPLETE

Filtrar por valor que contenha uma string:


?where[title][contains]=tutorial

Filtrar por data (maior que):


?where[createdAt][greater_than]=2024-01-01

Filtrar onde um campo existe:


?where[description][exists]=true

Usando lógica OR:


?where[or][0][status][equals]=COMPLETE&where[or][1][status][equals]=PROCESSING

Usando lógica AND:


?where[and][0][status][equals]=COMPLETE&where[and][1][visibility][equals]=private

Usar o pacote qs

Consultas complexas podem tornar-se difíceis de escrever como query strings. Recomendamos usar o pacote qs-esm para converter objetos JSON em query strings:


import { stringify } from 'qs-esm';
 
const query = stringify({
  where: {
    status: {
      equals: 'COMPLETE'
    },
    and: [
      { visibility: { equals: 'private' } },
      { createdAt: { greater_than: '2024-01-01' } }
    ]
  },
  limit: 20,
  page: 1
}, { addQueryPrefix: true });
 
// Result: ?where[status][equals]=COMPLETE&where[and][0][visibility][equals]=private&where[and][1][createdAt][greater_than]=2024-01-01&limit=20&page=1

Esta abordagem torna muito mais fácil construir e manter consultas complexas de forma programática.