HIVE Docs
Explore HIVE

Listen: Seitenwechsel, Filter, Sortierung, Felder und Erweiterung

Jede Liste der HIVE-API (Assets, Signale, Alarme, Arbeitsaufträge, Dokumente und alle weiteren) funktioniert gleich. Man lernt es einmal. Englische Fassung: Lists: pagination, filtering, sorting, fields and expansion. Die Parameter jeder Liste stehen in List parameters.

Die Antwort#

JSON
{
  "object": "list",
  "data": [ { "id": "alm_01m71xxn9ze26b4pq3dnxee9ms", "object": "alarm", "asset_id": "ast_01m71xxng7fzrvspnkgtw1t2kg", "expanded": {} } ],
  "has_more": true,
  "next_cursor": "c1.AQzIubxgQuAaae5Bh7r-gp9o...",
  "total_count": null,
  "total_count_is_lower_bound": null
}

Seitenwechsel: limit und cursor#

Das Konsistenzversprechen#

Ein Durchlauf über eine Menge, die sich nicht ändert, liefert jede Zeile genau einmal. Während Zeilen hinzukommen, sich ändern und gelöscht werden, gilt:

Wenn Sie eine vollständige Kopie sich ändernder Daten brauchen, verwenden Sie die Änderungsströme und Exporte statt eines langen Listendurchlaufs.

Filter#

feld=wert ist Gleichheit. feld[operator]=wert verwendet einen Operator. Mehrere Parameter werden mit UND verknüpft; ein ODER gibt es nicht (verwenden Sie in oder zwei Anfragen). Jede Liste legt fest, welche Felder mit welchen Operatoren filterbar sind (List parameters).

OperatorBedeutungGilt für
eq (die bloße Form)gleichalle Typen
neungleichalle Typen
gt, gte, lt, ltegrößer, größer oder gleich, kleiner, kleiner oder gleichZahlen, Zeitstempel, Datumswerte
in, ninin / nicht in einer kommagetrennten Liste mit höchstens 100 WertenStrings, Aufzählungen, Zahlen, Referenzen
contains, prefixenthält / beginnt mit, ohne Unterscheidung von Groß- und KleinschreibungFelder, die als textsuchbar deklariert sind
is_nulltrue findet leere Werte, false nicht leere Wertealle Typen

Werte sind typisiert:

Höchstens 5 Filter, 100 Werte in einer in-Liste, 3 Sortierfelder und 3 Erweiterungen je Anfrage. Ein Filter auf ein Feld, das nicht als filterbar deklariert ist, ein für das Feld nicht erlaubter Operator, ein Wert des falschen Typs und ein Parameter, den die Liste nicht kennt, werden mit 400 invalid_request abgelehnt; sie werden nie ignoriert. Die Fehlereinträge nennen den Parameter und einen der Codes invalid_filter_field, invalid_filter_operator, invalid_type, invalid_enum, too_many_items, unknown_field.

Beispiele (Musterwerk):

Code
GET /v1/alarms?state=open&asset_id[in]=ast_01m71xxng7fzrvspnkgtw1t2kg,ast_01m71xxpcwfz1snpsm3pqdqrjc&sort=-raised_at&expand=asset&limit=20
GET /v1/work-orders?created_at[gte]=2026-11-09T00:00:00Z&title[contains]=bearing&fields=id,key,title,state
GET /v1/assets?asset_type_id[is_null]=true

Filterwerte werden nie in unsere Protokolle geschrieben; nur die Feldnamen und Operatoren.

Sortierung#

sort=raised_at,-key: eine kommagetrennte Liste mit bis zu 3 sortierbaren Feldern, - für absteigend. Der Server hängt id als letzten Schlüssel an, damit die Reihenfolge eindeutig ist; er übernimmt die Richtung des letzten Feldes, das Sie angegeben haben. Standard ist -id (neueste zuerst), sofern die Liste keinen anderen Standard dokumentiert. Ein nicht sortierbares Feld, ein wiederholtes Feld, id an anderer Stelle als am Ende oder mehr als 3 Felder ergeben 400 invalid_sort_field. Leere Werte stehen bei aufsteigender Sortierung zuletzt und bei absteigender zuerst.

Felder: fields#

fields=key,name liefert nur diese Felder der obersten Ebene sowie id und object. Eine Punktebene wählt einen Teil eines Objekts oder jedes Objekts eines Arrays: fields=key,external_refs.system. Ein unbekannter Name ergibt 400 invalid_field_selection. Eine Liste mit Erweiterungen behält immer das Feld expanded.

Erweiterung: expand#

expand=asset fügt die referenzierten Objekte unter expanded.asset hinzu und behält das Feld asset_id. Erlaubt sind nur Namen, die die Liste deklariert, höchstens 3 und nur eine Ebene tief (asset.parent wird abgelehnt). Ohne expand lautet das Feld "expanded": {}.

Eine Erweiterung ist ein Lesezugriff mit Ihren Berechtigungen: Ein Objekt, das Sie nicht lesen dürfen oder das nicht existiert, ist in expanded null, nie ein Fehler und nie Daten. Felder eines erweiterten Objekts wählen Sie mit fields[asset]=key,name.

Zählen: count=true#

count=true fügt total_count hinzu: genau bis 10.000. Darüber ist total_count gleich 10000 und total_count_is_lower_bound gleich true. Ohne count=true wird nichts gezählt. Dauert das Zählen zu lange, wird die Seite trotzdem geliefert und total_count ist null.

Fehler#

SituationAntwort
Ungültiger Parameter400 invalid_request, je Problem ein Eintrag in errors[] mit parameter
Cursor ungültig, abgelaufen oder mit anderer Abfrage, anderem Mandanten, Endpunkt oder anderer Version verwendet400 invalid_cursor (immer derselbe Inhalt)
Die Datenbank braucht für eine Seite mehr als 2 Sekunden504 timeout, keine Teildaten; Filter einengen und erneut versuchen