Einführung von $materialize: SQL-Schnittstelle für FHIR-Daten

FHIR-Datenstrukturen sind komplex und verschachtelt, was die Arbeit mit Standard-SQL-Tools und Analyseplattformen erschwert.

Um diesem Problem zu begegnen, führt Aidbox eine neue SQL on FHIR-Operation namens $materialize ein. Sie erstellt eine SQL-Repräsentation einer ViewDefinition-Ressource und wandelt komplexe FHIR-Strukturen in vertraute Tabellenformate um, die nahtlos mit Tools wie DBeaver, Metabase und anderen SQL-basierten Analyseplattformen funktionieren.

Stand September 2025 ist dies noch nicht in der SQL on FHIR-Spezifikation enthalten, aber wir hoffen, dass sie in Zukunft standardisiert wird.

Was $materialize leistet

Im Kern verbindet $materialize zwei Welten: die Flexibilität von FHIR und die Vertrautheit von SQL. Es:

• Erstellt eine SQL-Tabelle oder -View aus einer ViewDefinition-Ressource.
• Wandelt verschachtelte FHIR-Daten in flache, abfragbare Strukturen um, die SQL-Tools verarbeiten können.
• Bietet eine vertraute Schnittstelle für Analysten und Entwickler, die mit FHIR-Daten arbeiten.

Warum das wichtig ist

FHIR-Ressourcen weisen komplexe, verschachtelte JSON-Strukturen auf, die sich nur schwer direkt mit SQL abfragen lassen.

Bisher war dafür Folgendes erforderlich:

• Schreiben komplexer JSON-Path-Abfragen
• Detailliertes Verständnis von FHIR-Ressourcenstrukturen
• Eigener Code zum Abflachen und Transformieren von Daten

$materialize löst dieses Problem, indem Sie die Datentransformation einmalig als ViewDefinition definieren und anschließend eine einfache SQL-Schnittstelle erstellt wird, die jeder Analyst mit vertrauten Tools nutzen kann.

Vorteile auf einen Blick:

• Einfache SQL-Abfragen statt komplexer JSON-Operationen
• Kompatibel mit jedem SQL-Tool (DBeaver, Metabase, Tableau usw.)
• Wiederverwendbare Definitionen — einmal definieren, überall abfragen
• Standardisierter FHIR-Ansatz mit ViewDefinition-Ressourcen
• Leistungsvorteile — komplexe JSON-Abfragen bei jeder Anfrage vermeiden

Materialisierungstypen

$materialize unterstützt drei Typen der Materialisierung und bietet Ihnen je nach Anwendungsfall die passende Flexibilität:

• view (Standard) — erstellt eine Datenbankview, die Daten dynamisch transformiert

  • Immer aktuell mit den neuesten FHIR-Daten

  • Kein zusätzlicher Speicher erforderlich

  • Ideal für die meisten Anwendungsfälle, die eine SQL-Schnittstelle benötigen

• table — erstellt eine persistente Tabelle mit einer Momentaufnahme der Daten

  • Schnellste Lesezugriffe für große Datensätze und komplexe Abfragen

  • Erfordert manuelle Aktualisierung, um Daten auf dem neuesten Stand zu halten

  • Belegt Speicher, eliminiert aber die Verarbeitungszeit bei Abfragen

• materialized-view — erstellt eine materialisierte View, die aktualisiert werden kann

  • Ausgewogener Ansatz zwischen Leistung und Aktualität

  • Kann bei Bedarf oder zeitgesteuert aktualisiert werden

  • Unterstützt Indizes für optimierte Abfrageleistung

Funktionsweise

• Erstellen Sie eine ViewDefinition-Ressource, die FHIR-Daten auf einfache Spalten abbildet.
• Senden Sie einen POST an /fhir/ViewDefinition/$materialize.
• Der Server erstellt eine SQL-View/-Tabelle mit den abgeflachten Daten.
• Die resultierende Repräsentation ist in der Datenbank verfügbar.
• Alternativ können Sie sie mit einem beliebigen SQL-Tool oder dem /$sql-Endpunkt von Aidbox abfragen.

Beispielanfrage

So sieht es in der Praxis aus.

POST /fhir/ViewDefinition/$materialize
Content-Type: application/json

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "type",
    "valueCode": "view"
  }, {
    "name": "viewResource",
    "resource": {
      "name": "patient_view",
      "status": "draft",
      "resource": "Patient",
      "description": "Patient flat view",
      "id": "a099e84c-b3c2-4b6e-8115-a580d25f6495",
      "resourceType": "ViewDefinition",
      "select": [{
        "column": [{
          "name": "id",
          "path": "id",
          "type": "id"
        }, {
          "name": "birth_date",
          "path": "birthDate",
          "type": "date"
        }, {
          "name": "family_name",
          "path": "name.family",
          "type": "string"
        }]
      }]
    }
  }]
}

Die Antwort enthält Informationen über die erstellte View:

{
  "resourceType": "Parameters",
  "parameter": [{
    "name": "viewName",
    "valueString": "sof.patient_view"
  }, {
    "name": "viewType",
    "valueString": "view"
  }, {
    "name": "viewSchema",
    "valueString": "sof"
  }]
}

Jetzt können Sie die abgeflachten Daten mit einfachem SQL abfragen:

SELECT * FROM sof.patient_view WHERE birth_date > '1990-01-01';

Beispiel: Patienten-IDs und demografische Daten

Praktische Einsatzmöglichkeiten

Da $materialize Standard-SQL ausgibt, eröffnet es ein breites Spektrum an Möglichkeiten:

• Analysen und Berichte — FHIR-Daten mit BI-Tools wie Metabase oder Tableau verbinden
• Datenerkundung — FHIR-Daten mit SQL-Tools wie DBeaver erkunden
• ETL-Pipelines — abgeflachte Daten für nachgelagerte Systeme extrahieren
• Eigene Anwendungen — Apps entwickeln, die tabellarische Views von FHIR-Daten benötigen
• Forschung und Analyse — Forschenden ermöglichen, FHIR-Daten mit Standard-SQL abzufragen

Leistungsüberlegungen

Obwohl der primäre Nutzen von $materialize in der Vereinfachung des Datenzugriffs liegt, spielt die Leistung bei bestimmten Anwendungsfällen eine wichtige Rolle:

• Häufig wiederholte Abfragen: Wenn Sie dieselben komplexen Abfragen wiederholt ausführen (Dashboards, Berichte), können die Typen materialized-view oder table die Antwortzeiten erheblich reduzieren.
• Große Datensätze: Bei der Arbeit mit Millionen von FHIR-Ressourcen vermeidet materialisierter Speicher die erneute Verarbeitung von JSON-Strukturen bei jeder Abfrage.
• Komplexe Transformationen: [ViewDefinitions](/blog/what-is-a-viewdefinition) mit mehreren Joins und Aggregationen profitieren von einer Vorberechnung.
• Analytische Workloads: BI-Tools, die umfangreiche Scans über große Datensätze durchführen, erzielen mit materialisiertem Speicher deutliche Leistungsverbesserungen.

Für die meisten explorativen Arbeiten und moderate Abfragevolumina bietet der Standard-Typ view die beste Balance aus Einfachheit und Leistung.

Abschließende Hinweise

Der Standard-Typ view eignet sich hervorragend für die meisten Szenarien, in denen Sie eine SQL-Schnittstelle zu FHIR-Daten benötigen — stets aktuell und ohne zusätzlichen Wartungsaufwand.

Ziehen Sie die Typen table oder materialized-view in Betracht, wenn Sie häufig wiederholte Abfragen oder große Datensätze verarbeiten, die von vorberechneten Ergebnissen profitieren würden.

$materialize wandelt komplexe FHIR-Strukturen in einfache SQL-Schnittstellen um, macht FHIR-Daten für alle zugänglich, die SQL beherrschen, und ermöglicht den Einsatz standardisierter Analyse-Tools im gesamten Ökosystem der Gesundheitsdaten.

Weitere Informationen zur Funktionsweise von $materialize und seinen Parametern finden Sie in der Aidbox-Dokumentation.