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 / Feld | Operatoren |
|---|---|
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_json | Nur _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, Skills | Verschachtelter Zielobjektfilter; siehe Nach einem verknüpften Datensatz filtern |
location | Nicht direkt filterbar |
Zwei davon sind schmaler, als man erwarten könnte, und zwar mit Absicht:
IDhat kein_is_null. Ein Datensatz hat immer eineid. Die Ordnungsvergleiche gibt es hingegen: Sie existieren, damitideinen 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.
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.
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:
| Ausdruck | Bedeutung |
|---|---|
now | dieser Zeitpunkt |
now-6h | vor sechs Stunden |
now+30m | in dreißig Minuten |
now/d | Beginn des heutigen Tages |
now-1d/d | Beginn des gestrigen Tages |
now/w | Beginn dieser Woche (Montag) |
now-12M | vor 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-1Mergibt vom 31. März aus den 28. Februar und nicht „vor 30 Tagen“, undnow-1dbehält seine Uhrzeit über eine Zeitumstellung hinweg. Verwenden Sienow-24h, wenn Sie stattdessen eine exakte Zeitspanne benötigen. - Geltungsbereich. Vergleichsoperatoren (
_eq,_gt,_lt,_gte,_lte) auf Feldern vom TypDateTimeundDate.Timeakzeptiert 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:
| Operator | Bedeutung |
|---|---|
_contains | Das Feld enthält den Operanden an einer beliebigen Stelle. |
_starts_with | Das Feld beginnt mit dem Operanden. |
_ends_with | Das 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.
{ 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:
| Operator | Bedeutung |
|---|---|
_in | Das Array enthält mindestens einen der angegebenen öffentlichen Auswahlwerte. |
_contains | Das 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:
{ 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: Filter | Der angegebene Filter darf nicht zutreffen. Ein Datensatz ohne gesetztes Feld gilt als nicht zutreffend. |
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:
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:
{
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:
{
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:
{
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_atabsteigend, falls Sie überhaupt keine Sortierung angegeben haben — eine unsortierte Liste ist damit neueste-zuerst und nicht willkürlich; - dann immer
idaufsteigend, 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.