Query

Tutti gli endpoint elenco nell’API supportano un insieme comune di parametri di query per paginazione, ordinamento e filtraggio.

Parametri comuni

Parametro	Tipo	Descrizione
`page`	`number`	Il numero di pagina da recuperare (predefinito: 1).
`limit`	`number`	Il numero di elementi da recuperare per pagina (predefinito: 10).
`sort`	`string`	Il campo per cui ordinare. Prefissa con `-` per ordine decrescente (es. `-createdAt`).
`where`	`object`	Oggetto query per filtrare i risultati usando gli operatori.

Risposta di paginazione

Tutti gli endpoint elenco restituiscono una risposta paginata con la seguente struttura:


{
  "docs": [...],
  "totalDocs": number,
  "limit": number,
  "totalPages": number,
  "page": number,
  "pagingCounter": number,
  "hasPrevPage": boolean,
  "hasNextPage": boolean,
  "prevPage": number | null,
  "nextPage": number | null
}

Ordinamento

Usa il parametro sort per ordinare i risultati in base a un campo specifico.

Direzione di ordinamento

Crescente (predefinito): ?sort=createdAt
Decrescente: prefissa con - → ?sort=-createdAt

Campi ordinabili

Puoi ordinare per qualsiasi campo di primo livello sull’oggetto. Esempi comuni:

Campo	Descrizione
`createdAt`	Ordina per data di creazione
`updatedAt`	Ordina per data dell’ultima modifica
`title`	Ordina alfabeticamente per titolo

Esempi

Prima i più recenti:


?sort=-createdAt

Prima i meno recenti:


?sort=createdAt

Alfabeticamente per titolo:


?sort=title

Operatori Where

Il parametro where accetta un oggetto query che ti permette di filtrare i risultati con vari operatori:

Operatore	Descrizione
`equals`	Il valore deve essere esattamente uguale.
`not_equals`	Restituisce tutti i documenti in cui il valore non è uguale.
`greater_than`	Per campi numerici o basati su data.
`greater_than_equal`	Per campi numerici o basati su data.
`less_than`	Per campi numerici o basati su data.
`less_than_equal`	Per campi numerici o basati su data.
`like`	La stringa (senza distinzione tra maiuscole e minuscole) deve essere presente. Se è una stringa di parole, tutte le parole devono essere presenti, in qualsiasi ordine.
`contains`	Deve contenere il valore inserito, senza distinzione tra maiuscole e minuscole.
`in`	Il valore deve comparire nell’elenco di valori separati da virgola fornito.
`not_in`	Il valore NON deve comparire nell’elenco di valori separati da virgola fornito.
`exists`	Restituisce solo documenti in cui il valore esiste (`true`) o non esiste (`false`).

Logica And / Or

Puoi combinare più query usando la logica and / or. Possono essere annidate a qualsiasi profondità per creare query complesse.

Esempi di query

Filtra per valore esatto:


?where[status][equals]=COMPLETE

Filtra per valore che contiene una stringa:


?where[title][contains]=tutorial

Filtra per data (maggiore di):


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

Filtra dove un campo esiste:


?where[description][exists]=true

Usando la logica OR:


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

Usando la logica AND:


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

Uso del pacchetto qs

Le query complesse possono diventare difficili da scrivere come stringhe di query. Ti consigliamo di usare il pacchetto qs-esm per convertire oggetti JSON in stringhe di query:


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

Questo approccio rende molto più semplice costruire e mantenere query complesse in modo programmatico.