Abfragen

Alle Listen-Endpoints der API unterstützen einen gemeinsamen Satz von Query-Parametern für Paginierung, Sortierung und Filterung.

Gemeinsame Parameter

Parameter	Typ	Beschreibung
`page`	`number`	Die abzurufende Seitennummer (Standard: 1).
`limit`	`number`	Die Anzahl der Einträge pro Seite (Standard: 10).
`sort`	`string`	Das Feld, nach dem sortiert wird. Präfix `-` für absteigende Reihenfolge (z. B. `-createdAt`).
`where`	`object`	Abfrageobjekt zum Filtern der Ergebnisse mit Operatoren.

Paginierungs-Antwort

Alle Listen-Endpoints liefern eine paginierte Antwort mit folgender Struktur:


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

Sortierung

Verwende den Parameter sort, um Ergebnisse nach einem bestimmten Feld zu sortieren.

Sortierrichtung

Aufsteigend (Standard): ?sort=createdAt
Absteigend: Präfix - → ?sort=-createdAt

Sortierbare Felder

Du kannst nach jedem Feld auf oberster Ebene des Objekts sortieren. Häufige Beispiele:

Feld	Beschreibung
`createdAt`	Nach Erstellungsdatum sortieren
`updatedAt`	Nach letzter Änderung sortieren
`title`	Alphabetisch nach Titel sortieren

Beispiele

Neueste zuerst:


?sort=-createdAt

Älteste zuerst:


?sort=createdAt

Alphabetisch nach Titel:


?sort=title

Where-Operatoren

Der Parameter where akzeptiert ein Abfrageobjekt, mit dem du Ergebnisse über verschiedene Operatoren filtern kannst:

Operator	Beschreibung
`equals`	Der Wert muss exakt übereinstimmen.
`not_equals`	Liefert alle Dokumente, bei denen der Wert nicht gleich ist.
`greater_than`	Für numerische oder datumsbasierte Felder.
`greater_than_equal`	Für numerische oder datumsbasierte Felder.
`less_than`	Für numerische oder datumsbasierte Felder.
`less_than_equal`	Für numerische oder datumsbasierte Felder.
`like`	Die Zeichenkette (Groß-/Kleinschreibung ignoriert) muss vorkommen. Bei mehreren Wörtern müssen alle vorkommen, in beliebiger Reihenfolge.
`contains`	Muss den eingegebenen Wert enthalten, Groß-/Kleinschreibung ignoriert.
`in`	Der Wert muss in der angegebenen, kommagetrennten Liste vorkommen.
`not_in`	Der Wert darf NICHT in der angegebenen, kommagetrennten Liste vorkommen.
`exists`	Liefert nur Dokumente, bei denen der Wert existiert (`true`) oder nicht existiert (`false`).

Und- / Oder-Logik

Du kannst mehrere Abfragen mit and- / or-Logik verbinden. Diese lassen sich beliebig tief verschachteln, um komplexe Abfragen zu bauen.

Abfragebeispiele

Nach exaktem Wert filtern:


?where[status][equals]=COMPLETE

Nach Wert filtern, der eine Zeichenkette enthält:


?where[title][contains]=tutorial

Nach Datum filtern (größer als):


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

Filtern, ob ein Feld existiert:


?where[description][exists]=true

Oder-Logik verwenden:


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

Und-Logik verwenden:


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

Paket qs verwenden

Komplexe Abfragen werden als Query-Strings schnell unübersichtlich. Wir empfehlen das Paket qs-esm, um JSON-Objekte in Query-Strings umzuwandeln:


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

So lassen sich komplexe Abfragen programmatisch deutlich einfacher aufbauen und pflegen.