Glossar

Begriffe der Regionaldatenbank Deutschland und das Vokabular, das diese CLI verwendet. Die Datenbank läuft auf der Software GENESIS: Statistiken bestehen aus Datenquadern, die in Tabellen aufbereitet und durch Merkmale und deren Ausprägungen beschrieben werden – und fast alles hat hier zusätzlich eine regionale Dimension, die bis auf Kreis- und Gemeindeebene reicht.

Objekte

Begriff GENESIS Bedeutung
Statistik statistic Ein vollständiges statistisches Produkt, identifiziert über einen fünfstelligen EVAS-Code (z. B. 12411, „Fortschreibung des Bevölkerungsstandes“). Enthält Datenquader.
Tabelle table Eine fertige zweidimensionale Ansicht mit einem Code wie 12411-01-01-4. Das, was Sie hauptsächlich abrufen.
Datenquader cube Die mehrdimensionalen Rohdaten hinter den Tabellen.
Zeitreihe timeseries Ein Datenquader, reduziert auf einen einzelnen Wert im Zeitverlauf.
Merkmal variable Eine Dimension bzw. ein Attribut (z. B. KREISE = Kreise und kreisfreie Städte, GES = Geschlecht).
Ausprägung value Ein konkreter Wert eines Merkmals (z. B. ein bestimmter Kreis).
Ergebnistabelle result Eine von einem asynchronen Job erzeugte Tabelle, gespeichert in Ihrem Nutzerbereich.

Codes und Auswahl

Regionalschlüssel und Ebenen

Die Antworthülle

Jede Antwort außer von helloworld steckt in einer Hülle:

Feld Bedeutung
Ident { Service, Method } – welcher Endpoint geantwortet hat.
Status { Code, Content, Type } – das logische Ergebnis (siehe unten).
Parameter Echo Ihrer Anfrage (Zugangsdaten maskiert als ********).
Copyright der anzugebende Quellenvermerk – siehe DATA_LICENSE.md.
List Katalogergebnisse (ein homogenes Array).
Object Nutzdaten für Daten und Metadaten (nicht näher typisiert; bei data/table ein CSV-String in Object.Content).

helloworld/whoami und helloworld/logincheck verwenden diese Hülle nicht – ebenso wenig Authentifizierungsfehler, die als bloßes { Code, Content, Type }-Objekt ankommen (siehe unten). logincheck antwortet mit HTTP 200, ob die Zugangsdaten stimmen oder nicht: Status ist ein Text – ein Fehlertext („Ein Fehler ist aufgetreten …“) heißt, sie wurden abgelehnt, und die CLI endet mit Exit 1 und dem Hinweis auf die Zugangsdaten – und Username nennt das Konto (ein falscher Token kommt dort als Echo zurück).

Werte von Status.Code

Die meisten logischen Ergebnisse kommen mit HTTP 200; Authentifizierungsfehler liefern dieselbe Struktur mit 401/404:

Code Typ Bedeutung Diese CLI
0 Information Erfolg liefert Daten
22 Warnung Erfolg, ein Parameter wurde automatisch korrigiert liefert Daten (Warnung in Status.Content sichtbar)
50 Information keine neueren Daten (bei --stand) liefert Daten
104 Information kein Objekt gefunden, das passt – ein Filter, der alles ausschließt, oder ein Code, den es nicht gibt (metadata/data) liefert ein leeres Ergebnis (Exit 0); ein Download mit data <kind>file schlägt stattdessen fehl (Exit 4, keine Datei geschrieben)
90 Fehler angefordertes Objekt nicht gefunden Fehler, Exit 4
98 Information Ergebnis zu groß für einen direkten Abruf Fehler mit Hinweisen zum Eingrenzen, Exit 1
15 ERROR nicht autorisiert (keine oder nicht erkannte Zugangsdaten; flacher Body bei HTTP 401) Fehler + Hinweis zu den Zugangsdaten, Exit 1
2 ERROR falscher Benutzername oder falsches Passwort (flacher Body bei HTTP 404 – kein fehlendes Objekt! – oder bei HTTP 200) Fehler + Hinweis zu den Zugangsdaten, Exit 1
beliebig Fehler / Error allgemeiner Fehler Fehler, Exit 1
jeder andere Information / Warnung kein dokumentierter Erfolgscode Fehler, Exit 1 (nie als Daten ausgegeben)

Die Zuordnung ist bewusst streng: Ein Code, den diese CLI nicht kennt, schlägt laut fehl (Exit 1), statt mit einer Warnung als Daten durchzugehen. Ein HTTP 404 ohne GENESIS-Code – etwa die HTML-Fehlerseite eines falschen Pfads – gilt als „nicht gefunden“, Exit 4.

Platzhalter für den Wertstatus

In einer CSV aus data/table kann eine Zelle statt einer Zahl ein Statuszeichen enthalten: - (nichts vorhanden / tatsächlich null), . (unbekannt oder geheim – auf Gemeindeebene wegen der statistischen Geheimhaltung häufig), ... (noch nicht verfügbar), / (keine Angabe, da Zahlenwert nicht sicher genug), x (keine sinnvolle Aussage möglich), () (eingeschränkter Aussagewert), p (vorläufig), r (berichtigt), s (geschätzt).

Begriffe zur Authentifizierung

Wie Zugangsdaten übertragen werden und warum Weiterleitungen nicht gefolgt wird, beschreibt DEVELOPING.md (englisch).

Log-Einträge

Log-Eintrag (log record). Jede Diagnosezeile, die die CLI nach stderr schreibt: ein Zeitstempel, eine Stufe (ERROR, WARN, INFO) und ein Thema regstat.<Bereich>, als Text (im Stil von log4j) oder mit --log-format jsonl als ein JSON-Objekt pro Zeile. Die Bereiche: cli (Bedienfehler, Meldungen von commander, unerwartete Fehler, die Warnung vor Zugangsdaten in einer Option), api (die Antworten von GENESIS: ein Fehlerstatus, der Hinweis zu den Zugangsdaten und eine fehlerhafte Antwort — ungültiges JSON, die falsche Form, ein leerer Body, eine HTML-Seite statt einer Datei, eine Anmeldeprüfung, die nichts bestätigt), http (die Verbindung, die Klartext-Warnung und je Wiederholung eine WARN-Zeile vor dem Warten), config (die Zugangsdaten-Datei) und output (die -o-Datei, Schreibfehler auf stdout). Ein Eintrag ist immer eine Zeile; Steuerzeichen darin werden maskiert.

Quelle auf GitHub ansehen →