Implementation Guide
Telematikinfrastruktur (TI) Common
Version 1.1.0 - ballot

Query API: Allgemeine Anforderungen Suche und Sortierung

Seiteninhalt:

Diese Seite beschreibt Standard-API-Zugriffe für eine clientseitige Suche und Bereitstellung von Daten des FHIR Data Service. Im Detail bedeutet dies das Navigieren in Suchergebnisseiten, die kompakte Suche mit verknüpften FHIR-Ressourcen als auch die Suche unter Nutzung von Vergleichsoperatoren.

Suche

Die FHIR-Schnittstellen des FHIR Data Service unterstützen standardmäßige [FHIR-Suchoperationen] gemäß den Vorgaben der FHIR-Spezifikation. Bei einer Suche wird ein Search Set Bundle zurückgegeben.

Der FHIR Data Service MUSS sicherstellen, dass für jede Ressource, die direkt den in der Suchanfrage angegebenen Kriterien entspricht, das Attribut entry.search.mode auf match gesetzt wird.

fullUrl in FHIR Bundles

Der FHIR Data Service MUSS sicherstellen, dass das fullUrl-Feld in jedem Entry (Bundle.entry.fullUrl) wie in der Standard HL7 FHIR Spezifikation als absolute URL oder als UUID-basierte URI (urn:uuid) angegeben wird. Relative Pfade sind im fullUrl-Feld nicht zulässig. Für absolute URLs gilt zusätzlich, dass sie das Format [base]/[Ressourcentyp]/[ResourceId] aufweisen müssen. Der FHIR Data Service MUSS sicherstellen, dass, wenn im Bundle.entry.fullUrl eine UUID-basierte URI (urn:uuid) verwendet wird, alle Referenzen innerhalb desselben Bundles ebenfalls in der Form urn:uuid:[UUID] angegeben werden. Eine Mischung aus absoluten URLs, UUID-basierten URIs und relativen Referenzen innerhalb eines Bundles DARF NICHT verwendet werden. Der FHIR Data Service MUSS sicherstellen, dass relative Referenzen wie "literal" Referenzen in der Form [Resourcetyp]/[ResourceId] NICHT im Feld Bundle.entry.fullUrl verwendet werden. Alle Verweise auf Ressourcen innerhalb des Aktensystems MÜSSEN entweder als absolute URLs oder als UUID-basierte URIs (urn:uuid) angegeben werden.

Beispiel:

Eine UUID-basierte URI MUSS das Format urn:uuid:[UUID] haben, zum Beispiel

urn:uuid:ea01ccbc-aa5d-4c34-8292-d95678d52c98

Beispiele Standard-Suchparameter

_id: Bezieht sich auf die logische ID der Ressource

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_id=ea01ccbc-aa5d-4c34-8292-d95678d52c98

_lastUpdated: Kann verwendet werden, um Ressourcen basierend auf dem letzten Änderungszeitpunkt auszuwählen

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=2025-15-01

Einbeziehung verknüpfter Ressourcen in das Ergebnis

_include:

In FHIR wird der Suchparameter _include verwendet, um zu fordern, dass der Server nicht nur die angeforderten Ressourcen, sondern auch andere Ressourcen, die über eine angegebene Referenz mit ihnen verbunden sind, zurückgibt. Dieser Parameter ist besonders nützlich, um verknüpfte Ressourcen in einer einzigen Abfrage abzurufen, wodurch die Notwendigkeit nachfolgender Anfragen verringert wird. Beispielsweise, wenn eine Abfrage an MedicationRequest-Instanzen mit einem _include-Parameter wie MedicationRequest:medication durchgeführt wird, gibt der Medication Service die angeforderten MedicationRequest-Instanzen zusammen mit verknüpften Medication-Instanzen zurück. Das bedeutet, dass eine Liste von Medication-Instanzen ebenso erhalten ist.

Beispiel

GET [base]/epa/medication/api/v1/fhir/MedicationRequest?_include=MedicationRequest:medication

In dieser Abfrage bedeutet:

  1. MedicationRequest der FHIR-Ressourcentyp, der abgefragt wird

  2. _include=MedicationRequest:medication die Anweisung an den Medication Service, die Medication-Instanzen einzubeziehen, auf die in den MedicationRequest-Instanzen referenziert wird

Diese Abfrage gibt ein Search Set Bundle zurück, welches alle im Medication Service verfügbaren MedicationRequest-Instanzen enthält - also auch zugehörige Medication-Instanzen. Hinweis: Dies kann potenziell eine große Ergebnismenge bedeuten und ist davon abhängig, wie viele MedicationRequest-Datensätze gespeichert sind.

Der FHIR Data Service MUSS die _include-Suche gemäß der [FHIR Search Include] unterstützen, sodass referenzierte Ressourcen innerhalb der Suchergebnisse automatisch mit einbezogen werden können.
_revinclude:

In FHIR ist _revinclude ein Suchparameter, der es ermöglicht, Ressourceninstanzen in die Ergebnismenge einzubeziehen, die jeweils auf die primäre Ressourceninstanz referenziert.

Der FHIR Data Servic MUSS die _revinclude-Suche gemäß der [FHIR Search Revinclude] unterstützen, sodass Ressourcen, die auf die gesuchten Ressourcen verweisen, innerhalb der Suchergebnisse automatisch mit einbezogen werden können.

Beispiel

GET [base]/epa/medication/api/v1/fhir/MedicationRequest?_revinclude=MedicationDispense:prescription

In dieser Abfrage bedeutet:

  1. MedicationRequest der FHIR-Ressourcentyp, der abgefragt wird

  2. _revinclude=MedicationDispense:prescription die Anweisung an den Medication Service, die MedicationDispense-Instanzen einzuschließen, die eine authorizingPrescription-Referenz haben, welche wiederum auf die MedicationRequest-Instanzen verweist

Diese Abfrage gibt ein Search Set Bundle zurück, welche MedicationRequest-Instanzen zusammen mit den MedicationDispense-Instanzen enthält.

Der FHIR Data Service MUSS für jede zurückgegebene Ressource die zugehörigen Ressourcen gemäß den Verknüpfungskriterien ermitteln und mit entry.search.mode = "include" in die Antwort aufnehmen. Falls eine referenzierte Ressource nicht existiert, nicht gefunden wird oder nicht abrufbar ist, DARF KEIN Fehler zurückgegeben werden. Der FHIR Data Service MUSS sicherstellen, dass Ressourcen, die durch _include oder _revinclude in das Suchergebnis aufgenommen werden, stets auf derselben Ergebnisseite wie die zugehörigen Suchtreffer (entry.search.mode = "match") enthalten sind.

Unterstützung des :iterate-Modifikators

Der :iterate-Modifikator ermöglicht es, bei der Verwendung von _include und _revinclude die Einschlusslogik rekursiv anzuwenden. Dadurch werden nicht nur direkt referenzierte Ressourcen in das Suchergebnis aufgenommen, sondern auch alle Ressourcen, die durch die eingeschlossenen Ressourcen weiter referenziert werden. Dies ist besonders nützlich für mehrstufige Abhängigkeiten und zirkuläre Beziehungen.

Der FHIR Data Service MUSS den :iterate-Modifikator für _include und _revinclude unterstützen, um rekursive Einschlussabfragen gemäß der FHIR-Spezifikation zu ermöglichen. Der FHIR Data Service MUSS alle weiter referenzierten Ressourcen gemäß der angegebenen Referenzpfade iterativ in die Antwort aufnehmen, wenn _include:iterate verwendet wird. Der FHIR Data Service MUSS alle iterativ verknüpften rückreferenzierenden Ressourcen zurückgeben, wenn _revinclude:iterate verwendet wird.
Beispiel: Einbeziehung von MedicationDispense und der zugehörigen abgebenden Leistungserbringerinstitution (LEI) in die Medikamentensuche

Die folgende FHIR-Suchanfrage kombiniert _revinclude und _include:iterate, um sowohl rückverknüpfte als auch iterativ eingeschlossene Ressourcen in die Antwort aufzunehmen:

GET [base]/Medication?_revinclude=MedicationDispense:medication&_include:iterate=MedicationDispense:performer

In dieser Abfrage bedeutet:

  1. _revinclude=MedicationDispense:medication
    • Sucht alle Medication-Instanzen und schließt zusätzlich alle MedicationDispense-Instanzen ein, die diese Medikamente referenzieren.
  2. _include:iterate=MedicationDispense:performer
    • Nachdem die MedicationDispense-Instanzen über revinclude</i> einbezogen wurden, bewirkt der _:iterate-Modifikator, dass die in MedicationDispense.performer referenzierten Organisationen ebenfalls in die Antwort aufgenommen werden.
Beispiel: Abruf aller Verschreibungen mit zugehörigem verschreibenden Leistungserbringer (LE) und verschreibender Leistungserbringerinstitution (LEI)

Die folgende FHIR-Suchanfrage kombiniert include</i> und _include:iterate, um eine vollständige Abfrage aller _MedicationRequest-Instanzen mit den relevanten Informationen zum verschreibenden LE und zur verschreibenden LEI durchzuführen. Diese Abfrage ermöglicht es, alle Verschreibungen (MedicationRequest) mit dem zugehörigen verschreibenden LE (Practitioner) und der verschreibenden LEI (Organization) abzurufen.

GET [base]/MedicationRequest?_include=MedicationRequest:medication
    &_include=MedicationRequest:requester
    &_include:iterate=PractitionerRole:organization
    &_include:iterate=PractitionerRole:practitioner

In dieser Abfrage bedeutet:

  1. _include=MedicationRequest:medication
    • Bezieht die in MedicationRequest.medication referenzierte Medication-Instanz in die Antwort ein.
  2. _include=MedicationRequest:requester
    • Bezieht die in MedicationRequest.requester referenzierte PractitionerRole-Instanz mit ein.
  3. _include:iterate=PractitionerRole:organization
    • Falls die PractitionerRole-Instanz eine Referenz zu einer Organization enthält, wird diese in die Antwort aufgenommen.
    • So kann die verschreibende LEI (z. B. eine Praxis oder Klinik) ermittelt werden.
  4. _include:iterate=PractitionerRole:practitioner
    • Falls die PractitionerRole-Instanz eine Referenz zu einer Practitioner-Instanz enthält, wird diese in die Antwort aufgenommen.
    • So kann der verschreibenden LE ermittelt werden.

Vergleiche und Präzision für Zahlen, Daten und Mengen

Bei einer Suche, die numerische oder Datumsparameter umfasst, hängen die verwendeten Werte von der Präzision des bereitgestellten Parameters ab. Zum Beispiel erstreckt sich für das Datum 2025-02-11 der Bereich von 2025-02-11, um 00:00:00 Uhr (inklusive) bis 2025-02-12, um 00:00:00 Uhr (exklusive).

Präfix

In FHIR werden Gleitkommazahlen durch Datentypen wie [FHIR decimal) und [FHIR Quantity] dargestellt, die die Präzision des gespeicherten Werts erfassen. Dies schließt jedoch einige Felder aus, die einfache Ganzzahlen verwenden. Suchoperationen in diesen Feldern führen zu exakten numerischen Übereinstimmungen. Bei numerischen Vergleichen ([FHIR Search number], [FHIR Search quantity]) mit einem einzelnen Wert sind nachfolgende spezifische Präfixe anwendbar. Wenn kein Präfix angegeben wird, wird standardmäßig eq verwendet. Weitere Details finden sich hier: [FHIR Search Prefixes]

Präfix Beschreibung
eq Der Wert des Parameters in der Ressource ist gleich dem bereitgestellten Wert.
ne Der Wert des Parameters in der Ressource ist nicht gleich dem bereitgestellten Wert.
gt Der Wert des Parameters in der Ressource ist größer als der bereitgestellte Wert.
lt Der Wert des Parameters in der Ressource ist kleiner als der bereitgestellte Wert.
ge Der Wert des Parameters in der Ressource ist größer oder gleich dem bereitgestellten Wert.
le Der Wert des Parameters in der Ressource ist kleiner oder gleich dem bereitgestellten Wert.

Datumsangaben haben einen Bereich, der auf ihrer Präzision (Jahr, Monat, Tag) basiert. Für Typen wie [FHIR Range] oder [FHIR Period] sind eindeutige obere und untere Grenzen definiert. Es gibt spezifische Präfixe für derartige Vergleiche. Wird kein Präfix angegeben, ist eq die Standardwahl.

Präfix Beschreibung
eq Der Bereich des Suchwerts enthält den Bereich des Zielwerts vollständig.
ne Der Bereich des Suchwerts enthält den Bereich des Zielwerts nicht vollständig.
gt Der Bereich oberhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
lt Der Bereich unterhalb des Suchwerts überlappt mit dem Bereich des Zielwerts.
ge Der Bereich oberhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
le Der Bereich unterhalb des Suchwerts überlappt mit oder schließt den Bereich des Zielwerts vollständig ein.
sa Der Bereich des Parameterwerts beginnt nach dem Zielbereich.
eb Der Bereich des Parameterwerts endet vor dem Zielbereich.
Der FHIR Data Service MUSS numerische und Datums-Suchparameter so verarbeiten, dass die Suchwerte entsprechend ihrer Präzision interpretiert werden. Beispielsweise MUSS eine Suche nach 2025-02-11 den Bereich von 2025-02-11T00:00:00 (inklusive) bis 2025-02-12T00:00:00 (exklusive) abdecken. Der FHIR Data Service MUSS die in der [FHIR Search Prefixes] definierten Vergleichspräfixe für numerische (number, quantity) und Datumsparameter (date, Range, Period) unterstützen. Falls kein Vergleichspräfix angegeben wird, MUSS der FHIR Data Service standardmäßig das Präfix eq verwenden. Der FHIR Data Service MUSS die folgenden Vergleichspräfixe für numerische Werte (number, quantity) unterstützen: eq, ne, gt, lt, ge, le Der FHIR Data Service MUSS die folgenden Vergleichspräfixe für Datumswerte (date, Range, Period) unterstützen: eq, ne, gt, lt, ge, le, sa, eb Der FHIR Data Service MUSS sicherstellen, dass Suchoperationen für Felder mit Ganzzahlen (integer) nur exakte numerische Übereinstimmungen liefern und keine Präzisionsanpassungen wie bei Gleitkommazahlen (decimal, quantity) vornehmen. Der FHIR Data Service MUSS für Suchanfragen, die Range- oder Period-Werte betreffen, sicherstellen, dass obere und untere Grenzen des Bereichs korrekt berücksichtigt werden und mit den definierten Vergleichspräfixen korrekt verarbeitet werden.

Beispiele:

Alle AuditEvents, die vor dem 15. Januar 2025 aktualisiert oder erstellt wurden:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_lastUpdated=lt2025-15-01T00:00:00Z


Alle AuditEvents nach dem 15. Januar 2025:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=gt2025-15-01T00:00:00Z


Alle AuditEvents seit dem 15. Januar 2025 und von der Allgemeinarztpraxis “Praxis Dr. John Doe”:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=ge2025-15-01T11:00:00Z&altid=1-883110000092404


Alle AuditEvents ab dem 15. Januar 2025 und alle AuditEvents, die eine Erstellung protokollieren:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=2025-15-01T11:00:00Z&action=C


Alle AuditEvents für das XDS-Dokument Arztbrief4711:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?entity-name=Arztbrief4711


Verkettete Parameter (Chained parameters)

Das Client-System KANN in dem FHIR Data Service einen Referenzparameter mithilfe sogenannter “Chained parameters” verwenden. Dabei wird ein Referenzparameter durch einen Punkt (.) mit dem Namen eines Suchparameters der Zielressource verknüpft. Diese Verkettung kann mehrstufig durchgeführt werden, indem ein logischer Pfad über mehrere verknüpfte Ressourcen definiert wird.

Die Syntax für eine verkettete Parameter-Suche sieht folgendermaßen aus:

[Referenzparameter]:[Ressourcentyp].[innerer Suchparameter]=[innerer Wert]

Wenn der Referenzparameter nur auf einen einzelnen Ressourcentyp verweist, kann :[Ressourcentyp] weggelassen werden. Die Syntax lautet dann:

[Referenzparameter].[innerer Suchparameter]=[innerer Wert]


Der FHIR Data Service MUSS die Suche von verketteten Parametern gemäß der Spezifikation unter [FHIR Chained parameters] implementieren und unterstützen.

Beispiel

In diesem Beispiel gibt der ePA Medication Service nur MedicationRequest-Instanzen zurück, die sich auf das Medikament Ibuprofen beziehen:

GET [base]/MedicationRequest?medication.code=http://fhir.de/CodeSystem/bfarm/atc|M01AE01

Reverse Chaining (_has)

Das Client-System KANN in dem FHIR Data Service den _has-Parameter verwenden, um eine umgekehrte verkettete Parametersuche durchzuführen. Bei einer umgekehrten verketteten Parametersuche werden Ressourceninstanzen basierend auf den Kriterien von anderen Ressourceninstanzen abgeglichen, die auf sie verweisen. Dies ist das Gegenteil der verketteten Parametersuche, bei der Instanzen basierend auf den Eigenschaften von Ressourcen ausgewählt werden, auf die sie verweisen.

Die Syntax für eine umgekehrte verkettete Parametersuche sieht folgendermaßen aus:

_has:[Ressourcentyp]:[Referenzparameter]:[Suchparameter]=[Wert]


Der FHIR Data Service MUSS die umgekehrte verkettete Parametersuche gemäß der Spezifikation unter [FHIR Reverse Chaining] implementieren und unterstützen.

Beispiele

In diesem Beispiel wird nach Medication-Ressourceninstanzen gesucht, die von MedicationStatement-Instanzen referenziert werden und der Status der MedicationStatement-Instanzen auf “active” steht.

GET [base]/Medication?_has:MedicationStatement:medication:status=active

In diesem Beispiel wird nach Medication-Ressourceninstanzen gesucht, die von MedicationStatement-Instanzen referenziert werden und das effective-Datum zwischen dem 22. Juli 2025 und dem 23. Juli 2025 liegt.

GET [base]/Medication?_has:MedicationStatement:medication:effective=ge2025-07-22&_has:MedicationStatement:medication:effective=le2025-07-23

In diesem Beispiel wird nach Medication-Ressourceninstanzen gesucht, die von MedicationStatement-Instanzen referenziert werden und der Status der MedicationStatement-Instanzen auf “stopped” steht. Mit dem _revinclude-Parameter werden zusätzlich alle zugehörigen MedicationStatement-Instanzen, die auf die jeweilige Medication-Ressource verweisen, in den Ergebnissen zurückgegeben.

GET [base]/Medication?_has:MedicationStatement:medication:status=stopped&_revinclude=MedicationStatement:medication

Sortierung

Das Client-System KANN die Reihenfolge der zurückgegebenen Ergebnisse durch den Parameter _sort angeben, der eine durch Kommas getrennte Liste von Sortierregeln in Prioritätsreihenfolge enthalten kann. Der FHIR Data Service MUSS die Sortierfunktion nach [FHIR Sorting] implementieren.

Beispiel:

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_sort=action,-date