Erweiterte FHIR-Suchfunktionen

Auf dieser Seite wird erläutert, wie Sie mit FHIR-Ressourcen, die über die Methode projects.locations.datasets.fhirStores.fhir.search verfügbar sind, nach FHIR-Ressourcen suchen. In diesem Leitfaden wird davon ausgegangen, dass Sie mit dem Inhalt von Nach FHIR-Ressourcen suchen vertraut sind.

String-Modifikatoren für die Suche

Bei einer Stringsuche wird standardmäßig ein Präfixabgleich verwendet, bei dem die Groß-/Kleinschreibung ignoriert wird. Die Akzente werden dabei nicht berücksichtigt. Satzzeichen und zusätzlicher Leerzeichen werden ignoriert.

Folgende Modifikatoren sind verfügbar:

  • :contains gleicht Ressourcen mit dem angegebenen Wert an einer beliebigen Stelle im String ab, beispielsweise stimmt name:contains=eve mit Evelyn und Severine überein.
  • :exact entspricht dem gesamten String einschließlich Groß- und Kleinschreibung, z. B. name:exact=Eve stimmt nicht mit eve oder Evelyn überein.

Komparatoren und Genauigkeit für Zahlen, Daten und Mengen

Die in einer numerischen oder Datumssuche verwendeten Werte hängen von der Genauigkeit des Parameterwerts ab. Beispiel: Die Zahl 7.00 hat einen impliziten Bereich von 6.995 (einschließlich) bis 7.005 (ausschließlich). Das Datum 2015-08-12 umfasst einen Bereich von 2015-08-12T00:00:00 (einschließlich) bis 2015-08-13T00:00:00 (ausschließlich).

Die Genauigkeit beeinflusst, welche Ergebnisse für Gleichheitsvergleiche zurückgegeben werden. Beispielsweise würde ein Wert von 7.03 in einer Ressource mit einer Suche nach value=7.0 übereinstimmen, aber nicht mit einer Suche nach value=7.00.

Alle klinisch signifikanten Gleitkommawerte in FHIR werden durch Typen wie Dezimalzahl und Menge dargestellt, die die Genauigkeit des gespeicherten Wertes aufzeichnen. Ausgenommen hiervon sind einige Felder, die einfache Ganzzahlen verwenden, z. B. zur Darstellung einer Position in einer Sequenz. Suchvorgänge in diesen Feldern sind exakte numerische Übereinstimmungen.

Die folgenden Präfixe gelten für numerische Vergleiche gegenüber einem Singleton-Wert. Wenn keine Präfixe angegeben sind, wird der Standardwert eq verwendet.

  • eq: Gleich, der exakte gespeicherte Wert liegt innerhalb des Bereichs, der durch die Genauigkeit des Parameterwerts definiert wird
  • ne: nicht gleich, das Gegenteil von eq
  • gt: Der genaue gespeicherte Wert ist größer als der genaue Parameterwert.
  • lt: Der genaue gespeicherte Wert ist kleiner als der genaue
  • ge: Der genaue gespeicherte Wert ist größer oder gleich dem genauen Parameterwert
  • le: Der genaue gespeicherte Wert ist kleiner oder gleich dem exakten Parameterwert.

Datumswerte haben einen impliziten Bereich, der auf der Spezifität des Werts basiert (ein Jahr, ein Monat, ein Tag). Andere Datentypen wie Bereich und Zeitraum enthalten explizite Ober- und Untergrenzen. Die folgenden Präfixe gelten für Bereichsvergleiche. Wenn keine Präfixe angegeben sind, wird der Standardwert eq verwendet.

  • eq: gleich, der Bereich des Parameterwerts enthält den Bereich des Ziels vollständig
  • ne: nicht gleich, das Gegenteil von eq
  • gt: größer als, der Bereich über dem Parameterwert überschneidet sich mit dem Bereich des Ziels
  • lt: kleiner als, der Bereich unter dem Parameterwert überschneidet sich mit dem Bereich des Ziels
  • ge: Größer als oder gleich
  • le: Kleiner als oder gleich
  • sa: Der Bereich des Parameterwerts beginnt nach dem Zielbereich.
  • eb: Der Bereich des Parameterwerts endet vor dem Zielbereich.

Tokensuchparameter gelten für Fälle, in denen ein Wert kein beliebiger String, sondern eine Entität in einem Benennungssystem ist. Die Zeichenfolge, die mit einem Tokenparameter übereinstimmt, ist genau.

Die meisten Token-Suchanfragen werden auf komplexe Datentypen angewendet, die einen system enthalten, bei dem es sich um einen URI handelt, der das Benennungssystem angibt, aus dem der Wert code stammt. Diese Suchvorgänge unterstützen die folgenden Wertsyntaxen:

  • [parameter]=[code] stimmt mit dem code-Wert überein, unabhängig von system
  • [parameter]=[system]|[code] muss sowohl mit dem angegebenen system als auch mit code übereinstimmen.
  • [parameter]=|[code] stimmt mit code überein, wenn der Wert system leer ist
  • [parameter]=[system]| entspricht einem beliebigen code mit dem angegebenen system-Wert

Es gibt mehrere Modifikatoren, die alternative Tokensuchfunktionen auslösen:

  • :not negiert die übereinstimmenden Bedingungen einer Tokensuche
  • :text führt eine String-Suche (keine exakte Übereinstimmung) im Feld text oder display durch, das mit dem Code verknüpft ist, und sucht nicht nach dem Codewert selbst
  • :above verwendet nur einen Parameter im Format [system]|[code] und gleicht Ressourcen ab, bei denen der Code in der Ressource den Abfrageparameter subsumiert. Zur Verwendung dieses Modifizierers muss das angegebene system im FHIR-Speicher als CodeSystem-Ressource vorhanden sein.
  • :below entspricht :above, stimmt aber überein, wenn der Code in der Ressource vom Abfrageparameter subsumiert wird.
  • :in verwendet einen einzelnen Parameter mithilfe der Referenzparametersyntax, z. B. code:in=ValueSet/1234. Der Verweis muss auf eine ValueSet-Ressource im selben FHIR-Speicher verweisen. Der Modifikator entspricht jedem Code im referenzierten ValueSet.
  • :not-in negiert die Bedingungen von :in

Tokensuchen gelten auch für boolesche Felder und URI-Felder sowie bestimmte Stringfelder, in denen nur genaue Übereinstimmungen zulässig sind. In diesen Fällen lautet das einzige Parameterformat [parameter]=[value].

Nach fehlenden Werten suchen

Der Suchmodifikator :missing kann für jeden Suchparameter verwendet werden, der auf dem Vorhandensein oder Fehlen eines beliebigen Werts im angegebenen Feld basiert. Beispielsweise gleich Patient?gender=unknown Ressourcen ab, die explizit den Enum-Wert unknown für das Geschlecht enthalten. Da dieses Feld jedoch nicht erforderlich ist, gibt es möglicherweise andere Ressourcen, die dieses Feld überhaupt nicht befüllen. Solche Ressourcen können mit Patient?gender:missing=true abgeglichen werden. Umgekehrt stimmt Patient?gender:missing=false mit jeder Ressource überein, die dieses Feld explizit füllt.

Der spezielle Suchparameter _content führt eine Textübereinstimmung für alle Felder durch, die das Ziel eines Suchparameters in einer Ressource sind. Standardmäßig werden Ressourcen abgeglichen, die alle Wörter in der Abfrage enthalten. Außerdem werden zusätzliche Operatoren unterstützt:

  • | ist der OR-Operator. abc | def | ghi xyz entspricht beispielsweise einer Ressource, die xyz und einen oder mehrere von abc def ghi enthält.
  • - ist der NOT-Operator, z. B. entspricht abc -def einer Ressource, die abc enthält, aber nicht def enthält.

Der Parameter _text führt die gleiche Art von Abgleich nur für das Feld Narrative aus, das eine für den Menschen lesbare Zusammenfassung der Ressourceninhalte enthalten soll. Die Cloud Healthcare API generiert diese Zusammenfassung nicht automatisch, unterstützt aber den Suchparameter _text, wenn diese Daten vom Client beim Erstellen oder Aktualisieren der Ressource ausgefüllt wurden.

Zusammengesetzte Suchparameter

Bei der Suche mit mehreren Suchparametern gibt es Fälle, in denen einzelne Suchparameter mit AND kombiniert unbeabsichtigte Ergebnisse liefern würden. Zusammengesetzte Suchparameter sind eine spezielle Art von Suchparameter, mit denen dieses Problem behoben wird.

Die Ressource Observation kann beispielsweise mehrere Werte im Feld component enthalten, die jeweils ein Paar aus code und value enthalten. Eine Suche nach Observation?component-code=8867-4&component-value-quantity=lt50 würde mit einer Ressource übereinstimmen, die eine Komponente mit einem code von 8867-4 und einer anderen Komponente mit einem value kleiner als 50 hätte. Diese Suche kann nicht zur Beschränkung auf eine Übereinstimmung dieser beiden Werte innerhalb derselben Komponente verwendet werden.

Zusammengesetzte Suchparameter definieren einen neuen Parameter, der zwei andere Suchparameter kombiniert und eine Verschachtelungsebene definiert, innerhalb der beide Parameter übereinstimmen müssen. In der Abfrage werden die beiden Werte mit $ verbunden. Beispiel: Observation hat einen zusammengesetzten Parameter component-code-value-quantity, der das vorherige Beispiel auf eine einzelne Komponente beschränken kann. Dazu suchen Sie nach Observation?component-code-value-quantity=8867-4$lt50. Diese Parameter werden durch die FHIR-Spezifikation definiert und existieren nicht für alle Kombinationen von Suchparametern.

Zusammengesetzte Suchparameter lassen keine Modifikatoren zu.

Wie bei allen Suchparametern finden Sie in der Capability-Anweisung oder der FHIR-Konformitätserklärung Informationen dazu, welche zusammengesetzten Parameter von der Cloud Healthcare API unterstützt werden.

Bei einer verketteten Suche kann eine Suche in Verweisen im Kontext einer Abfrage suchen. Die grundlegende Syntax für eine verkettete Suche sieht so aus:

[reference parameter]:[resource type].[inner search parameter]=[inner value]

Wenn sich der Verweisparameter nur auf einen einzigen Ressourcentyp bezieht, kann :[resource type] weggelassen werden. Dies führt zu Folgendem:

[reference parameter].[inner search parameter]=[inner value]

Beispiel: Observation hat einen Referenzsuchparameter subject, der auf Group, Device, Patient oder Location verweisen kann. Um Observations zu finden, deren subject ein Patient ist, dessen Name mit "Joe" beginnt, können Sie nach Observation?subject:Patient.name=Joe suchen.

Wenn die Abfrage mehrere verkettete Parameter enthält, wird jede Kette separat ausgewertet. Zum Beispiel könnte Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada einem Patient entsprechen, der zwei general-practitioner-Referenzen hat, eine mit dem Namen "Joe" und die andere mit einer Adresse in Kanada. Es gibt keine Syntax, um diese Klauseln so zu gruppieren, dass sie nur mit Joe aus Kanada übereinstimmen.

Bei einer umgekehrten verketteten Suche werden Ressourcen basierend auf Kriterien anderer Ressourcen, die auf sie verweisen, abgeglichen. Die Syntax für eine umgekehrte verkettete Suche lautet:

_has:[resource type]:[reference parameter]:[search parameter]=[value]

Die Ressource Appointment hat beispielsweise einen Suchparameter patient, der auf eine Patient-Ressource verweist. Verwenden Sie Patient?_has:Appointment:patient:date=eq2020-04-01, um alle Patient-Ressourcen zu finden, auf die eine Appointment-Ressource mit dem Datum 2020-04-01 verweist.

Umkehrketten können wiederkehrend sein. Practitioner?_has:Encounter:practitioner:_has:Claim:encounter:created=eq2020-04-01 würde beispielsweise mit einem Practitioner P übereinstimmen, wenn es ein Encounter E und ein Claim C gibt, sodass C ein Erstellungsdatum von 2020-04-01 hat, C sich auf E über die Referenz encounter und E auf P über die Referenz practitioner bezieht.

Aufnahme zusätzlicher Ressourcen in die Suchergebnisse

Die Parameter _include und _revinclude verlangen, dass die Suchergebnisse zusätzliche Ressourcen ("einschließlich enthaltener Ressourcen") enthalten, die sich auf die Ressourcen beziehen, die direkt mit der Abfrage übereinstimmen ("primäre Ergebnisse"). Die Verwendung dieser Parameter ist effizienter als eine Reihe von Anfragen zum separaten Abrufen dieser zusätzlichen Ressourcen. Im Paket searchset, das von der Suche zurückgegeben wird, werden Ressourcen, die von diesen Parametern hinzugefügt werden, mit entry.search.mode = include gekennzeichnet, um sie von den primären Ergebnissen mit entry.search.mode = match zu unterscheiden.

Durch das Weiterleiten mit _include werden Ressourcen hinzugefügt, auf die die in primären Ergebnissen verwiesen wird. Die umgekehrte Integration mit _revinclude fügt Ressourcen hinzu, die auf die primären Ergebnisse verweisen. Die zu verfolgende Referenz wird durch den Namen eines Suchparameters angegeben. Auf diese Weise können nur Referenzfelder verwendet werden, die als Suchparameter verfügbar sind.

Die Parameterformate für _include und _revinclude sind identisch und nehmen zwei oder drei durch : getrennte Werte an. Der erste Wert ist der Ressourcentyp, aus dem die Referenz stammt, der zweite Wert ist der Name des Suchparameters. Der optionale dritte Wert beschränkt den Ressourcentyp auf einen einzigen Typ in Fällen, in denen die Referenz auf mehrere Typen verweisen kann.

Beispiel:

  • MedicationRequest?_include=MedicationRequest:subject durchsucht MedicationRequest-Ressourcen und gibt für jede zurückgegebene Ressource auch das Ziel der subject-Referenz zurück, das ein Group oder Patient sein kann, wie in der FHIR-Spezifikation definiert.
  • MedicationRequest?_include=MedicationRequest:subject:Patient ist ähnlich, gibt jedoch nur subject-Verweise auf Patient-Ressourcen zurück.
  • MedicationRequest?_revinclude=Provenance:target durchsucht MedicationRequest-Ressourcen und gibt für jede zurückgegebene Ressource auch alle Provenance-Ressourcen zurück, wobei der target-Verweis auf Provenance auf die übereinstimmende Ressource verweist.

Der Modifikator :iterate bewirkt, dass ein _include iterativ ausgewertet wird. Dieser Modifikator kann einer zusätzlichen Ebene von Referenzen aus eingeschlossenen Ergebnissen folgen oder rekursiven Strukturen folgen, beispielsweise Observation:derived-from, die auf eine andere Observation verweisen. Die Rekursionstiefe ist begrenzt.

Beispiel:

  • Observation?_include:iterate=Observation:derived-from:Observation durchsucht Observation-Ressourcen und folgt rekursiv der abgeleiteten Referenz aus übereinstimmenden Observation-Ressourcen und dann aus eingeschlossenen Ressourcen usw.
  • MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agent durchsucht MedicationRequest, schließt Provenance-Ressourcen mit einem target ein, das in dieser Ergebnismenge enthalten ist, und schließt dann Ressourcen ein, auf die über den Parameter agent dieser Provenance-Ressourcen verwiesen wird.

Der Platzhalter * gibt an, dass alle in Form von Suchparametern verfügbaren Verweise enthalten sein sollen. Sie können den Platzhalter * als erstes und einziges Argument in _include oder anstelle des Suchparameternamens aus dem Standard-_include verwenden, in dem der optionale dritte Wert angegeben wird. Dieser beschränkt den Ressourcentyp auf einen einzelnen Typ wie im ursprünglichen Verhalten.

Beispiel:

  • Observation?_include=* durchsucht Observation-Ressourcen und gibt für jede Ressource auch alle referenzierten Ressourcen zurück.
  • Observation?_include=Observation:* entspricht dem obigen Vorgehen.
  • MedicationRequest?_include=MedicationRequest:*:Patient gibt alle Verweise auf Patient-Ressourcen für jede MedicationRequest-Ressource zurück.

Enthaltene Ressourcen werden dedupliziert. So wird nur eine Kopie einer Ressource auf einer Ergebnisseite zurückgegeben, auch wenn sie über mehrere Referenzen gefunden wird. Auf jeder Ergebnisseite, auf die sich ein primäres Ergebnis bezieht, wird dieselbe eingeschlossene Ressource zurückgegeben.

Die in den Suchergebnissen zurückgegebenen Felder einschränken

Mit dem Parameter _elements kann der Client anfordern, dass für jedes Suchergebnis nur eine Teilmenge von Feldern zurückgegeben wird. Auf diese Weise wird durch Weglassen von unnötigen Daten die Größe der Antwort reduziert. Der Parameter akzeptiert eine durch Kommas getrennte Liste von Basiselementnamen in der Ressource, z. B. Patient?_elements=identifier,contact,link. Nur diese Felder und deren untergeordneten Elemente werden in den zurückgegebenen Ressourcen berücksichtigt. Ressourcen in der Antwort, die von diesem Parameter geändert wurden, enthalten einen meta.tag-Wert von SUBSETTED, um anzugeben, dass sie unvollständig sind.

Die Cloud Healthcare API unterstützt den Parameter _summary, der vordefinierte Teilmengen von Ressourcenfeldern wie _elements bereitstellt, eingeschränkt:

  • _summary=text gibt nur die Felder der obersten Ebene text, id und meta zurück.
  • _summary=data entfernt das Feld text und gibt alle anderen Felder zurück.