Zum Hauptinhalt springen

Filtern und Sortieren

Jede Connection — ob Wurzelfeld oder To-many-Relation — nimmt ein where-Argument zum Filtern und ein order_by-Argument zum Sortieren. Beide werden aus Ihren Definitionen erzeugt; welche Operatoren auf einem Feld verfügbar sind, folgt also aus dem Typ dieses Feldes.

Die Beispiele verwenden die Objekte equipment und maintenance_request aus dem Überblick.

Fahrzeugsuche nach Anzeigenamen​

Fahrzeug-Wurzelfelder (vehicle und die Slugs konkreter Definitionen) akzeptieren zusätzlich search. Gesucht wird eine wörtliche Teilzeichenfolge im kanonischen display_name, ohne Unterscheidung von Groß- und Kleinschreibung; % und _ sind normale Zeichen. Die Eingabe darf höchstens 256 Zeichen enthalten. Äußere Leerzeichen werden entfernt, eine leere Eingabe schränkt die Ergebnisse nicht ein. Die Suche wird mit where kombiniert und vor totalCount, Sortierung und Paginierung angewendet, auch bei Rückwärtsseiten. Relative Datumsfilter verwenden weiterhin die Serverzeit und die Zeitzone des Arbeitsbereichs. Objekt-Wurzelfelder und verschachtelte Connections bieten dieses Argument nicht an. Siehe das Beispiel für Fahrzeugabfragen.

Operatoren nach Feldtyp​

Typisiertes Attribut / FeldOperatoren
Systemfeld id_eq, _ne, _in, _gt, _lt, _gte, _lte
text, email, phone_eq, _ne, _in, _contains, _starts_with, _ends_with, _is_null
number, capacity, measure, currency, rating_eq, _ne, _in, _gt, _lt, _gte, _lte, _is_null
boolean_eq, _ne, _is_null
einfacher select, state_eq, _ne, _in, _is_null
date, date_time_eq, _ne, _in, _gt, _lt, _gte, _lte, _is_null
Mehrfach-select_in, _contains, _is_null
raw_jsonNur _is_null; ein Pflichtdokument hat kein Filterfeld
rich_text_contains auf der Nur-Text-Projektion, _is_null
full_name_contains auf der kombinierten Anzeige, _is_null; order_by sortiert nach Nach-, dann Vorname
links_contains auf Bezeichnungen und URLs, _is_null
relationship, Tags, SkillsVerschachtelter Zielobjektfilter; siehe Nach einem verknüpften Datensatz filtern
locationNicht direkt filterbar

Zwei davon sind schmaler, als man erwarten könnte, und zwar mit Absicht:

  • ID hat kein _is_null. Ein Datensatz hat immer eine id. Die Ordnungsvergleiche gibt es hingegen: Sie existieren, damit id einen zusammengesetzten Cursor vervollständigen kann — siehe vollständige Durchläufe.
  • Enum-Filteroperanden sind Strings. Das Ausgabefeld ist ein erzeugtes GraphQL-Enum, Filter verwenden jedoch öffentliche Werte in Anführungszeichen: _eq: "hvac" oder _in: ["hvac", "ventilation"].
  • Erforderliche Felder haben kein _is_null. Ein Filter-Input bietet Null-Prüfungen nur an, wenn das Attribut laut Workspace-Schema ungesetzt bleiben darf.

Alle Operatoren auf einem Feld werden mit UND verknüpft. { name: { _starts_with: "Chiller" }, operational: { _eq: true } } bedeutet: beide Bedingungen.

urgent-open-requests.graphql
query UrgentOpenRequests {
maintenance_request(
where: {
resolved: { _eq: false }
priority: { _in: ["urgent"] }
reported_at: { _gte: "2026-03-01T00:00:00Z" }
}
order_by: [{ reported_at: desc }]
first: 20
) {
totalCount
edges {
node {
id
title
reported_at
}
}
}
}

Relative Zeiträume​

Operanden vom Typ DateTime und Date akzeptieren neben einem absoluten Zeitstempel auch einen relativen Zeitausdruck. Er wird bei der Ausführung der Abfrage aufgelöst, sodass now-6h immer die letzten sechs Stunden bezeichnet — ein gespeicherter Filter oder eine so geschriebene Dashboard-Abfrage veraltet damit nicht.

recently-reported.graphql
query RecentlyReported {
maintenance_request(where: { reported_at: { _gte: "now-6h" } }) {
edges { node { id title reported_at } }
}
}

Die Syntax besteht aus now, einem optionalen Versatz und einem optionalen Ausrichten auf eine Einheitengrenze:

AusdruckBedeutung
nowdieser Zeitpunkt
now-6hvor sechs Stunden
now+30min dreißig Minuten
now/dBeginn des heutigen Tages
now-1d/dBeginn des gestrigen Tages
now/wBeginn dieser Woche (Montag)
now-12Mvor zwölf Monaten

Einheiten sind s, m (Minuten), h, d, w, M (Monate), y — Groß- und Kleinschreibung ist bedeutsam: m sind Minuten, M sind Monate. Versätze sind auf 10000 Einheiten begrenzt.

Der Versatz wird zuerst angewendet, danach die Ausrichtung. Genau deshalb bezeichnet now-1d/d den Beginn des gestrigen Tages und nicht diese Uhrzeit am Vortag. Für einen abgeschlossenen Zeitraum werden zwei Grenzen kombiniert:

where: { reported_at: { _gte: "now-1d/d", _lt: "now/d" } }

Drei Punkte sind dabei wichtig:

  • Zeitzone. Ausrichtungen und Versätze ab einem Tag werden in der Zeitzone des Workspace ausgewertet; „Beginn des heutigen Tages“ ist also Ihre Mitternacht, nicht die UTC-Mitternacht. Versätze unterhalb eines Tages sind exakte Zeitspannen.
  • Kalenderarithmetik oberhalb der Stunde. now-1M ergibt vom 31. März aus den 28. Februar und nicht „vor 30 Tagen“, und now-1d behält seine Uhrzeit über eine Zeitumstellung hinweg. Verwenden Sie now-24h, wenn Sie stattdessen eine exakte Zeitspanne benötigen.
  • Geltungsbereich. Vergleichsoperatoren (_eq, _gt, _lt, _gte, _lte) auf Feldern vom Typ DateTime und Date. Time akzeptiert ausschließlich absolute Werte — ein Ausdruck bezeichnet einen Zeitpunkt, keine Tageszeit.

Ein fehlerhafter Ausdruck wird mit einem Fehler abgelehnt, der diese Syntax benennt, zum Beispiel 'nowish' is not a valid relative time expression: ….

Textvergleich​

Textvergleiche sind semantisch und unterscheiden nicht zwischen Groß- und Kleinschreibung. Clients senden Text und niemals SQL-Muster:

OperatorBedeutung
_containsDas Feld enthält den Operanden an einer beliebigen Stelle.
_starts_withDas Feld beginnt mit dem Operanden.
_ends_withDas Feld endet mit dem Operanden.

Die Zeichen % und _ werden wörtlich verglichen. Dadurch bleibt die Mustersyntax der Datenbank aus dem öffentlichen Vertrag heraus, und REST sowie GraphQL verhalten sich identisch.

filter-contains.graphql
{ equipment(where: { name: { _contains: "chiller" } }, first: 10) { edges { node { name } } } }

Prüfung auf Null​

_is_null: true findet Datensätze, in denen das Feld nicht gesetzt ist; _is_null: false findet die, in denen es gesetzt ist. Das ist etwas anderes als _eq: null, was nicht unterstützt wird. Eine Mehrfachauswahl ohne Werte gilt als nicht gesetzt.

Nicht gesetzte Werte in verneinten Bedingungen​

Ein Vergleich trifft nie auf einen Datensatz zu, dessen Feld nicht gesetzt ist: _eq, _in, _gt, _contains und die übrigen Operatoren überspringen ihn. _ne und _not finden jeden Datensatz, auf den die positive Bedingung nicht zutrifft, und schließen damit Datensätze ohne gesetztes Feld ein. { status: { _ne: "retired" } } liefert Datensätze mit einem anderen Status und Datensätze ohne Status. Ergänzen Sie _is_null: false, wenn nicht gesetzte Werte herausfallen sollen: { status: { _ne: "retired", _is_null: false } }.

Das gilt für Objekt-, Fahrzeug- und Aufgaben-Connections. Bei system_tour lassen _ne und _not Touren ohne gesetztes Feld weiterhin weg.

Mehrfachauswahl-Felder​

Eine Mehrfachauswahl wird als JSON-Array stabiler Auswahl-IDs gespeichert und als aktuelle Auswahlwerte ausgegeben. Gefiltert wird über Enthaltensein statt über skalare Vergleiche:

OperatorBedeutung
_inDas Array enthält mindestens einen der angegebenen öffentlichen Auswahlwerte.
_containsDas Array enthält alle angegebenen öffentlichen Auswahlwerte.

Setzen Sie _in in ein _not, um Datensätze zu finden, die keinen der Werte haben, einschließlich Datensätzen ohne Wert: _not: { certifications: { _in: ["TUV"] } }.

Der Operand ist eine nicht leere GraphQL-Liste öffentlicher Auswahlwerte und kein codierter JSON-String:

certifications-contains.graphql
{ equipment(where: { certifications: { _contains: ["TUV"] } }, first: 10) { edges { node { name } } } }

Die typisierte API unterstützt keine beliebigen Array- oder verschachtelten Objektattribute. Der einzige zusammengesetzte Wert, location, hat eine feste Ausgabeform und keine direkten Filteroperatoren.

Bedingungen verknüpfen​

_and: [Filter!]Alle angegebenen Filter müssen zutreffen.
_or: [Filter!]Mindestens einer muss zutreffen.
_not: FilterDer angegebene Filter darf nicht zutreffen. Ein Datensatz ohne gesetztes Feld gilt als nicht zutreffend.
neglected-or-critical.graphql
query NeglectedOrCritical {
equipment(
where: {
_or: [
{ operational: { _eq: false } }
{ _and: [{ category: { _in: ["hvac"] } }, { replacement_cost: { _gte: 20000 } }] }
]
_not: { asset_tag: { _starts_with: "TEMP-" } }
}
first: 25
) {
totalCount
edges { node { name asset_tag } }
}
}

Zwei Randfälle sollten Sie kennen, weil sie einander entgegengesetzt sind:

  • _and: [] — eine leere Liste — findet alles.
  • _or: [] findet nichts.

Das folgt aus der Logik (eine leere Konjunktion ist wahr, eine leere Disjunktion falsch), fällt aber unangenehm auf, wenn ein Client die Liste dynamisch aufbaut: Ein _or, dessen Bedingungen alle herausgefiltert wurden, liefert null Treffer statt ignoriert zu werden. Lassen Sie den Schlüssel weg, wenn Sie keine Bedingungen haben.

Verschachtelungsgrenze​

Ein where-Argument darf höchstens 4 Ebenen tief verschachtelt sein. Jedes _and, _or, _not und jeder Relations-Unterfilter zählt als eine Ebene. Bei Überschreitung kommt graphql/filter-too-deep zurück, mit der übermittelten Tiefe und dem Grenzwert.

Dieses Limit ist unabhängig vom Tiefenlimit für Abfragen, das die Relationsnavigation begrenzt — es sind zwei getrennte Regler mit getrennten Werten. Siehe Fehler und Limits.

Nach einem verknüpften Datensatz filtern​

Eine Relation steuert dem Filter-Input ein Feld bei, benannt nach dem Relations-Slug und typisiert als Filter der anderen Seite. Es trifft auf einen Elterndatensatz zu, wenn mindestens ein verknüpfter Datensatz zutrifft:

equipment-with-urgent-requests.graphql
query EquipmentWithUrgentRequests {
equipment(
where: { maintenance_requests: { priority: { _in: ["urgent"] }, resolved: { _eq: false } } }
first: 20
) {
totalCount
edges { node { name } }
}
}

Ein leerer Relationsfilter trifft auf einen Elterndatensatz mit mindestens einem verknüpften Datensatz zu: { manufacturer: {} }. Setzen Sie einen Relationsfilter in ein _not, um Elterndatensätze zu finden, auf die kein verknüpfter Datensatz zutrifft: _not: { manufacturer: {} } liefert Geräte ohne Hersteller, und _not: { manufacturer: { id: { _in: ["…"] } } } liefert Geräte, die mit keinem der angegebenen Datensätze verknüpft sind, einschließlich Geräten ganz ohne Hersteller. Innerhalb eines Relationsfilters gilt eine Bedingung für einen vorhandenen verknüpften Datensatz: { manufacturer: { id: { _ne: "…" } } } liefert Geräte mit einem anderen Hersteller, nicht Geräte ohne Hersteller.

Bei einer Relation zum System-Objekt user akzeptiert der id-Filter zusätzlich me, den aufrufenden Benutzer: where: { team: { id: { _eq: "me" } } } liefert die Projekte des Aufrufers, und _in: ["me", "…"] kombiniert ihn mit weiteren Benutzer-IDs. Mitglieder ohne users:read können über eine Benutzerrelation nach id, firstname, lastname, active und deleted_at filtern und sortieren sowie diese Felder und display_name auswählen.

Achten Sie genau auf die Semantik: Das liefert Geräte, die irgendeine unerledigte dringende Anfrage haben. Es filtert nicht die maintenance_requests-Connection selbst. Um beides zu erreichen — die Geräte auswählen und die zurückgegebenen Anfragen einschränken — filtern Sie an beiden Stellen:

filter-both-levels.graphql
{
equipment(where: { maintenance_requests: { resolved: { _eq: false } } }, first: 20) {
edges {
node {
name
maintenance_requests(where: { resolved: { _eq: false } }, first: 5) {
edges { node { title } }
}
}
}
}
}

Dieselbe verschachtelte Form gilt für tags, required_skills und provided_skills; ihr Ziel ist das Plattformobjekt tag beziehungsweise skill. Das gilt für Objekt-Wurzelfelder sowie für Wurzelfelder konkreter Fahrzeug- und Aufgabendefinitionen, die das Attribut deklarieren. Bereitgestellte und benötigte Skills filtern jeweils ihre eigene Zuordnungsrolle. Die übergreifenden Wurzelfelder für Fahrzeuge und Aufgaben behalten ihre Filter auf den gemeinsamen Feldern. Leseberechtigungen für das Ziel gelten vor dem Filtern und Zählen. Auch verwaltete Rückseiten einer Beziehung sind filterbar, obwohl REST-Schreibvorgänge über die deklarierende Eigentümerseite erfolgen müssen. Plattforminterne verborgene Connector-Seiten steuern kein Filterfeld bei.

Sortieren​

order_by nimmt eine Liste, und die Reihenfolge der Liste ist die Sortierpriorität:

order-by-category-name.graphql
{
equipment(order_by: [{ category: asc }, { name: asc }], first: 50) {
edges { node { category name } }
}
}

Die Richtungen sind asc und desc.

lock_version, display_name, Tags, Skills und Standorte können nicht direkt sortiert werden. Gespeicherte skalare Attribute und Select-/Statusattribute können sortiert werden, ebenso die Systemfelder id, created_at und updated_at.

Eine To-one-Beziehung unterstützt genau einen Sortierungsschritt. So wird Equipment nach dem Namen des Herstellers sortiert, ohne dass der Client diesen Namen in jeden Equipment-Datensatz kopieren muss:

order-by-related-manufacturer.graphql
{
equipment(order_by: [{ manufacturer: { name: asc } }], first: 50) {
edges { node { display_name manufacturer { display_name } } }
}
}

Verkettete Beziehungssortierungen und die Sortierung eines übergeordneten Datensatzes nach einer To-many-Sammlung werden nicht angeboten. Um Datensätze einer To-many-Beziehung zu sortieren, verwenden Sie order_by direkt an ihrer Relationship-Connection. Bei aufsteigender Sortierung stehen fehlende Beziehungen oder Nullwerte des Zielattributs zuletzt, bei absteigender Sortierung zuerst.

Ergebnisse stehen immer in einer totalen Ordnung​

Das ist wichtiger, als es klingt, denn es macht Paginierung verlässlich. PostgreSQL garantiert ohne ausdrückliche Sortierung keine Zeilenreihenfolge; eine unsortierte Abfrage in Kombination mit einem Seitenfenster könnte also denselben Datensatz auf zwei Seiten liefern und einen anderen nie.

Deshalb erhält jede Abfrage eine totale Ordnung:

  • zuerst Ihre order_by-Felder, in der von Ihnen angegebenen Reihenfolge;
  • dann created_at absteigend, falls Sie überhaupt keine Sortierung angegeben haben — eine unsortierte Liste ist damit neueste-zuerst und nicht willkürlich;
  • dann immer id aufsteigend, was jeden verbleibenden Gleichstand auflöst.

Sie müssen also nie selbst ein Tiebreaker-Feld ergänzen, und zwei identische Abfragen liefern Seiten, die zusammenpassen.