Zapytania

Wszystkie endpointy list w API obsługują wspólny zestaw parametrów zapytania pod paginację, sortowanie i filtrowanie.

Wspólne parametry

Parametr	Typ	Opis
`page`	`number`	Numer strony do pobrania (domyślnie: 1).
`limit`	`number`	Liczba elementów na stronę (domyślnie: 10).
`sort`	`string`	Pole sortowania. Dodaj prefiks `-` dla kolejności malejącej (np. `-createdAt`).
`where`	`object`	Obiekt zapytania do filtrowania wyników za pomocą operatorów.

Odpowiedź paginacji

Wszystkie endpointy list zwracają odpowiedź z paginacją w następującej strukturze:


{
  "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
}

Sortowanie

Użyj parametru sort, żeby uporządkować wyniki według wybranego pola.

Kierunek sortowania

Rosnąco (domyślnie): ?sort=createdAt
Malejąco: prefiks - → ?sort=-createdAt

Pola do sortowania

Możesz sortować według dowolnego pola najwyższego poziomu obiektu. Typowe przykłady:

Pole	Opis
`createdAt`	Sortuj według daty utworzenia
`updatedAt`	Sortuj według daty ostatniej modyfikacji
`title`	Sortuj alfabetycznie według tytułu

Przykłady

Najpierw najnowsze:


?sort=-createdAt

Najpierw najstarsze:


?sort=createdAt

Alfabetycznie według tytułu:


?sort=title

Operatory Where

Parametr where przyjmuje obiekt zapytania, który pozwala filtrować wyniki różnymi operatorami:

Operator	Opis
`equals`	Wartość musi być dokładnie równa.
`not_equals`	Zwraca wszystkie dokumenty, w których wartość nie jest równa.
`greater_than`	Dla pól liczbowych lub dat.
`greater_than_equal`	Dla pól liczbowych lub dat.
`less_than`	Dla pól liczbowych lub dat.
`less_than_equal`	Dla pól liczbowych lub dat.
`like`	Ciąg bez rozróżniania wielkości liter musi wystąpić. Jeśli to kilka słów, wszystkie muszą wystąpić, w dowolnej kolejności.
`contains`	Musi zawierać podaną wartość, bez rozróżniania wielkości liter.
`in`	Wartość musi znajdować się na podanej liście wartości rozdzielonych przecinkami.
`not_in`	Wartość nie może znajdować się na podanej liście wartości rozdzielonych przecinkami.
`exists`	Zwracaj tylko dokumenty, w których pole istnieje (`true`) albo nie istnieje (`false`).

Logika And / Or

Możesz łączyć wiele warunków logiką and / or. Możesz je zagnieżdżać dowolnie głęboko, żeby budować złożone zapytania.

Przykłady zapytań

Filtr po dokładnej wartości:


?where[status][equals]=COMPLETE

Filtr po fragmencie w ciągu:


?where[title][contains]=tutorial

Filtr po dacie (większa niż):


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

Filtr: pole istnieje:


?where[description][exists]=true

Logika OR:


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

Logika AND:


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

Użycie pakietu qs

Złożone zapytania trudno zapisywać jako zwykłe ciągi query. Polecamy pakiet qs-esm, żeby zamieniać obiekty JSON na ciągi zapytań:


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

Dzięki temu znacznie łatwiej budować i utrzymywać złożone zapytania w kodzie.