Zielgruppe: Data Stewards, Datenautoren und Portal-Manager

In einem CKAN-Portal können beliebige Dateiformate veröffentlicht werden. Um jedoch den vollen Funktionsumfang der Plattform zu nutzen und die Nachnutzbarkeit der Daten signifikant zu erhöhen, ist die Bereitstellung von strukturierten Daten im CKAN Datastore hilfreich. Dieser Beitrag soll eine praktische Anleitung sein, wie Sie tabellarische Daten korrekt vorbereiten und mithilfe der XLoader-Erweiterung effizient in den Datastore importieren.

Die Vorteile der Datastore-Nutzung

Wenn eine tabellarische Ressource (z.B. eine CSV-Datei) in den Datastore importiert wird, ist sie nicht länger nur eine Datei zum Herunterladen. Sie wird zu einer abfragbaren Datenquelle mit den folgenden Vorteilen:

• Verbesserte Such- und Filterfunktionen: Nutzer können die Daten direkt in der CKAN-Oberfläche durchsuchen und filtern, anstatt die gesamte Datei herunterladen zu müssen.
• Automatische Bereitstellung einer API: Für jeden Datensatz im Datastore wird automatisch eine API-Schnittstelle generiert. Dies ermöglicht Entwicklern den direkten, maschinellen Zugriff auf die Daten für die Integration in andere Anwendungen.
• Integrierte Visualisierungsmöglichkeiten: Daten aus dem Datastore können direkt in CKAN als Diagramme oder auf Karten visualisiert werden, ohne dass zusätzliche Werkzeuge erforderlich sind. Die CKAN Extension datatables_view leistet hierzu gute Dienste.
• Effizientere Datenaktualisierung: Anstatt eine gesamte Datei bei Änderungen neu hochladen zu müssen, können Datensätze im Datastore programmatisch und gezielt aktualisiert, hinzugefügt oder gelöscht werden. Die Funktion datastore_upsert() kann hierzu benutzt werden.

Anleitung: Daten mit dem XLoader in den Datastore importieren

Die XLoader-Erweiterung automatisiert den Import von unterstützten Dateiformaten (üblicherweise CSV und XLSX) in den Datastore. Der Prozess läuft im Hintergrund ab, erfordert jedoch eine korrekte Vorbereitung der Quelldatei.

Schritt 1: Datenvorbereitung (Der wichtigste Schritt)

Die meisten Importfehler lassen sich durch eine saubere Quelldatei vermeiden. Überprüfen Sie Ihre Tabelle vor dem Upload auf folgende Punkte:

• Header-Zeile: Die allererste Zeile der Datei muss die Spaltenüberschriften enthalten. Diese sollten eindeutig, kurz und frei von Sonderzeichen oder Zeilenumbrüchen sein.
• Keine Leerzeilen oder Kommentare: Entfernen Sie Leerzeilen vor der Header-Zeile sowie eventuelle Kommentarzeilen oder Metadaten am Anfang oder Ende der Datei.
• Datenformatierung:
  • Vermeiden Sie verbundene Zellen, wie sie in Excel häufig vorkommen.
  • Stellen Sie sicher, dass jede Spalte einen konsistenten Datentyp aufweist (z.B. eine Spalte enthält nur Zahlen, eine andere nur Datumswerte im Format JJJJ-MM-TT).
• Zeichenkodierung: Speichern Sie CSV-Dateien immer in der Kodierung UTF-8, um Probleme mit Umlauten und Sonderzeichen zu vermeiden.

Schritt 2: Der Upload-Prozess

Der Upload selbst unterscheidet sich nicht vom normalen Vorgehen:

1. Navigieren Sie zum gewünschten Datensatz.
2. Klicken Sie auf „Ressource hinzufügen“.
3. Laden Sie Ihre vorbereitete CSV- oder XLSX-Datei hoch.
4. Geben Sie die notwendigen Metadaten (Titel, Beschreibung, Format) an und speichern Sie die Ressource.

Details zum Upload-Prozess und Hinweise zur Aufbereitung strukturierter Daten gibt es in diesem Artikel

Schritt 3: Überprüfung des Imports

Nach dem Speichern startet der XLoader im Hintergrund automatisch den Importvorgang. Dies kann je nach Dateigröße einige Augenblicke dauern. Sie erkennen einen erfolgreichen Import an folgenden Merkmalen auf der Ressourcenseite:

• Es erscheint ein Button „Daten-Vorschau“ oder „Data Explorer“.
• Ein Klick darauf öffnet eine tabellarische Ansicht Ihrer Daten, die sortiert und gefiltert werden kann.
• Ein weiterer Button mit der Aufschrift „Daten-API“ wird sichtbar. Dieser führt zur technischen Dokumentation der automatisch erstellten Schnittstelle.

Was tun, wenn der Import fehlschlägt?

Wenn nach einigen Minuten keine Daten-Vorschau erscheint, ist der Import wahrscheinlich fehlgeschlagen. Die häufigsten Ursachen sind:

1. Formatierungsfehler in der Quelldatei: Überprüfen Sie erneut alle Punkte aus Schritt 1. Insbesondere versteckte Leerzeilen oder inkonsistente Daten in Spalten sind eine häufige Fehlerquelle.
2. Falsche Zeichenkodierung: Öffnen Sie Ihre CSV-Datei in einem Texteditor (z.B. Notepad++) und speichern Sie sie explizit als „UTF-8“.
3. Dateigröße: Sehr große Dateien können das Zeitlimit des Importers überschreiten. Erwägen Sie in diesem Fall, die Datei in mehrere kleinere Dateien aufzuteilen.

Nutzung der Datastore API für Lese- und Schreibzugriffe

Sobald Daten im Datastore sind, werden sie über eine maschinenlesbare Schnittstelle (Datastore API) zugänglich. Damit werden „lebendige“ Anwendungen möglich, die immer auf die aktuellsten Daten zugreifen, ohne dass Dateien manuell heruntergeladen werden müssen. Die Interaktion erfolgt über HTTP-Anfragen, die von jeder Programmiersprache (z.B. Python, JavaScript) oder Tools wie curl aus gesendet werden können.

Der API-Endpunkt datastore_search  ermöglicht das Suchen, Filtern und Sortieren von Daten. Anstatt die gesamte Tabelle abzurufen, können Sie gezielt nur die benötigten Informationen anfordern.

Anwendungsbeispiel: Abrufen der ersten 5 Einträge aus einer Ressource, bei denen die Spalte stadtteil den Wert Mitte hat.

# Beispiel mit dem Kommandozeilen-Tool curl
curl -X POST https://IHRE_CKAN_URL/api/3/action/datastore_search \
     -H "Content-Type: application/json" \
     -d '{
           "resource_id": "IHRE_RESOURCE_ID",
           "filters": {"stadtteil": "Mitte"},
           "limit": 5
         }'

• resource_id: Die ID der Ressource, die Sie abfragen möchten.
• filters: Ein Objekt, das Spaltennamen und die gewünschten Werte enthält, um das Ergebnis zu filtern
• q: Kann für eine Volltextsuche über alle Spalten verwendet werden (z.B. "q": "Blumenstraße").
• limit: Begrenzt die Anzahl der zurückgegebenen Datensätze.

Zusammenfassung: Die Nutzung des Datastores ist ein zentraler Baustein für ein hochwertiges und funktionales Datenportal. Durch eine sorgfältige Vorbereitung Ihrer tabellarischen Daten stellen Sie sicher, dass der automatisierte Import über den XLoader reibungslos funktioniert. Dies steigert nicht nur den Nutzwert für Endanwender, sondern erleichtert auch die technische Weiterverarbeitung bzw. den Zugriff auf Ihre Daten erheblich.