Implementation Guide
TI Common
Version 1.5.0-ballot.1 - ballot

Query API: Allgemeine Anforderungen Suche und Sortierung

Seiteninhalt:

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

Suche

Die FHIR-Schnittstellen eines 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.

funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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.

"Direkt den in der Suchanfrage angegebenen Kriterien entsprechen" heißt in diesem Fall, dass das entsprechende Ergebnis nicht über einen _include- oder _revinclude-Parameter der Ergebnismenge hinzugefügt wurde.

fullUrl in FHIR Bundles

funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS sicherstellen, dass das fullUrl-Feld in jedem Entry (Bundle.entry.fullUrl) wie in der 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS sicherstellen, dass relative Referenzen - wie literal-Referenzen in der Form [Ressourcentyp]/[ResourceId] - nicht im Feld Bundle.entry.fullUrl verwendet werden. Alle Verweise auf Ressourcen innerhalb des FHIR Data Service 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 für Standardsuchparameter

_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-01-15

Einbeziehung verknüpfter Ressourcen in das Ergebnis

_include

In der FHIR-Spezifikation 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. Wird beispielsweise eine Abfrage an MedicationRequest-Instanzen mit einem _include-Parameter wie MedicationRequest:medication durchgeführt, gibt der FHIR Data Service die angeforderten MedicationRequest-Instanzen zusammen mit verknüpften Medication-Instanzen zurück. Das bedeutet, dass eine Liste von Medication-Instanzen zusätzlich enthalten 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 FHIR Data Service, die Medication-Instanzen einzubeziehen, die in den MedicationRequest-Instanzen referenziert werden

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

funkt. Eignung: Test Produkt/FA 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 der FHIR-Spezifikation ist _revinclude ein Suchparameter, der es ermöglicht, Ressourceninstanzen in die Ergebnismenge einzubeziehen, die jeweils auf die primäre Ressourceninstanz verweisen.

funkt. Eignung: Test Produkt/FA Der FHIR Data Service 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 FHIR Data 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, welches die MedicationRequest-Instanzen zusammen mit den zugehörigen MedicationDispense-Instanzen enthält.

funkt. Eignung: Test Produkt/FA 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. funkt. Eignung: Test Produkt/FA 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.

funkt. Eignung: Test Produkt/FA 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. funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS alle weiter referenzierten Ressourcen gemäß der angegebenen Referenzpfade iterativ in die Antwort aufnehmen, wenn _include:iterate verwendet wird. funkt. Eignung: Test Produkt/FA 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 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 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 verschreibende 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 gelten die nachfolgenden Präfixe. 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.
Tabelle: Präfixe für numerische Vergleiche


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 Zielwerts liegt vollständig nach dem Bereich des Suchwerts.
eb Der Bereich des Zielwerts liegt vollständig vor dem Bereich des Suchwerts.
Tabelle: Präfixe für datumsbasierte Vergleiche


funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS numerische und datumsbasierte 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS standardmäßig das Präfix eq verwenden, falls kein Vergleichspräfix angegeben wird. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS die folgenden Vergleichspräfixe für numerische Werte (number, quantity) unterstützen: eq, ne, gt, lt, ge, le funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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 funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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-01-15T00:00:00Z


Alle AuditEvents nach dem 15. Januar 2025:

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


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-01-15&altid=1-883110000092404


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

GET [base]/epa/audit/api/v1/fhir/AuditEvent?date=ge2025-01-15&action=C


Alle AuditEvents für das IHE XDS-Dokument mit dem Titel 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 Parametersuche 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]


funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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 FHIR Data 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]


funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA 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, deren Status 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, deren effective-Datum am oder nach dem 22. Juli 2025 liegt.

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

In diesem Beispiel wird nach Medication-Ressourceninstanzen gesucht, die von MedicationStatement-Instanzen referenziert werden, deren Status 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

funkt. Eignung: Konformitätsbestätigung funkt. Eignung: Test Produkt/FA funkt. Eignung: Konformitätsbestätigung 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. funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS die Sortierfunktion nach [FHIR Sorting] implementieren.

Beispiel

GET [base]/epa/audit/api/v1/fhir/AuditEvent?_sort=action,-date
funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA funkt. Eignung: Test Produkt/FA Der FHIR Data Service MUSS bei der Sortierung von Instanzen anhand des Datentyps Period nach dem Element Period.start sortieren. Sofern zwei Instanzen den gleichen start-Wert besitzen, muss, sofern vorhanden, weitergehend nach Period.end sortiert werden. Ein nicht angegebener Period.start-Wert oder Period.end-Wert ist hierbei als noch nicht gestartet, also negativ unendlich, bzw. offen, also unendlich anzusehen.