Fonctionnalités de recherche FHIR avancées

Cette page explique comment rechercher des ressources FHIR à l'aide d'une fonctionnalité de requête plus avancée disponible via la méthode projects.locations.datasets.fhirStores.fhir.search. Dans ce guide, nous partons du principe que vous connaissez déjà le contenu de la section Rechercher des ressources FHIR.

Modificateurs de recherche de chaîne

Une recherche de chaîne utilise par défaut une correspondance de préfixe qui n'est pas sensible à la casse et à l'accent en se repliant au format NFC Unicode standard. La ponctuation et les espaces supplémentaires sont ignorés.

Les modificateurs suivants sont disponibles :

  • :contains établit une correspondance avec les ressources ayant la valeur spécifiée n'importe où dans la chaîne ; par exemple, name:contains=eve correspond à Evelyn et Severine.
  • :exact établit une correspondance avec la chaîne complète, y compris la casse et les accents ; par exemple name:exact=Eve ne correspond pas à eve ou Evelyn.

Comparateurs et précision pour les nombres, les dates et les quantités

Les valeurs utilisées dans une recherche numérique ou par date dépendent de la précision de la valeur du paramètre. Par exemple, le nombre 7.00 a une plage implicite de 6.995 inclus à 7.005 exclu. La date 2015-08-12 est comprise entre 2015-08-12T00:00:00 inclus et 2015-08-13T00:00:00 exclu.

La précision a une incidence sur les résultats renvoyés pour les comparaisons d'égalité. Par exemple, une valeur 7.03 d'une ressource correspond à une recherche de value=7.0, mais pas à une recherche de value=7.00.

Toutes les valeurs à virgule flottante cliniquement significatives dans FHIR sont représentées par des types tels que Décimal et Quantité qui enregistrent la précision de la valeur stockée. À titre exceptionnel, certains champs utilisent des entiers simples, par exemple pour représenter une position dans une séquence, et les recherches sur ces champs sont des correspondances numériques exactes.

Les préfixes suivants s'appliquent aux comparaisons numériques avec une valeur unique. Si aucun préfixe n'est spécifié, la valeur par défaut est eq.

  • eq : est égal à, la valeur stockée exacte est comprise dans la plage définie par la précision de la valeur de paramètre.
  • ne : n'est pas égal à, l'opposé de eq
  • gt : la valeur stockée exacte est supérieure à la valeur de paramètre exacte.
  • lt : la valeur stockée exacte est inférieure à la valeur de paramètre exacte.
  • ge : la valeur stockée exacte est supérieure ou égale à la valeur de paramètre exacte.
  • le : la valeur stockée exacte est inférieure ou égale à la valeur de paramètre exacte.

Les valeurs de date ont une plage implicite basée sur le niveau de spécificité de la valeur (un an, un mois, un jour). D'autres types de données, tels que Plage et Période, contiennent des limites supérieures et inférieures explicites. Les préfixes suivants s'appliquent aux comparaisons de plage. Si aucun préfixe n'est spécifié, la valeur par défaut est eq.

  • eq : est égal à, la plage de la valeur de paramètre contient entièrement la plage de la cible
  • ne : n'est pas égal à, l'opposé de eq
  • gt : supérieur à, la plage au-dessus de la valeur de paramètre chevauche la plage de la cible
  • lt : inférieur à, la plage située sous la valeur de paramètre chevauche celle de la cible.
  • ge : supérieur ou égal à
  • le : inférieur ou égal à
  • sa : la plage de la valeur de paramètre commence après la plage cible.
  • eb : la plage de la valeur de paramètre se termine avant la plage cible.

Les paramètres de recherche de jetons s'appliquent aux cas où une valeur n'est pas une chaîne arbitraire, mais plutôt une entité dans un système d'appellation. La correspondance de chaîne sur un paramètre de jeton est exacte.

La plupart des recherches de jetons s'appliquent à des types de données complexes contenant un system qui est un URI indiquant le système d'appellation duquel la valeur code est extraite. Ces recherches prennent en charge les syntaxes de valeur suivantes :

  • [parameter]=[code] correspond à la valeur code, quelle que soit la valeur system.
  • [parameter]=[system]|[code] doit correspondre à la fois à system et à code.
  • [parameter]=|[code] correspond à code lorsque la valeur system est vide.
  • [parameter]=[system]| correspond à tout code avec la valeur system donnée.

Plusieurs modificateurs déclenchent une autre fonctionnalité de recherche de jetons :

  • :not annule les conditions de correspondance d'une recherche de jetons.
  • :text effectue une recherche de chaîne (correspondance non exacte) sur le champ text ou display associé au code, au lieu de la valeur de code elle-même.
  • :above prend un paramètre uniquement de la forme [system]|[code] et établit une correspondance avec les ressources dans lesquelles le code de la ressource inclut le paramètre de requête. Pour utiliser ce modificateur, l'élément system spécifié doit exister dans le magasin FHIR en tant que ressource CodeSystem.
  • :below est semblable à :above, mais correspond si le code de la ressource est inclus dans le paramètre de requête.
  • :in prend un seul paramètre à l'aide de la syntaxe de paramètre de référence, par exemple code:in=ValueSet/1234. La référence doit se rapporter à une ressource ValueSet dans le même magasin FHIR. Le modificateur correspond à n'importe quel code figurant dans le ValueSet référencé.
  • :not-in annule les conditions de :in

Les recherches de jetons s'appliquent également aux champs booléens et URI, ainsi qu'à certains champs de chaîne où seule une correspondance exacte est autorisée. Dans ce cas, le seul format de paramètre est [parameter]=[value].

Rechercher des valeurs manquantes

Le modificateur de recherche :missing peut être utilisé sur n'importe quel paramètre de recherche pour établir une correspondance en fonction de la présence ou de l'absence d'une valeur dans le champ spécifié. Par exemple, Patient?gender=unknown établit une correspondance avec les ressources qui contiennent explicitement la valeur d'énumération unknown pour le sexe, mais comme ce champ n'est pas obligatoire, il se peut que d'autres ressources ne renseignent pas le champ du tout. Ces ressources peuvent être mises en correspondance par Patient?gender:missing=true. L'inverse, Patient?gender:missing=false, correspond à toute ressource qui remplit explicitement ce champ.

Le paramètre de recherche spécial _content effectue une correspondance textuelle sur tous les champs cibles d'un paramètre de recherche dans une ressource. Par défaut, il établit une correspondance avec les ressources contenant tous les mots de la requête, avec la prise en charge d'opérateurs supplémentaires :

  • | est l'opérateur OR. Par exemple, abc | def | ghi xyz correspond à une ressource contenant xyz et un ou plusieurs éléments abc def ghi.
  • - est l'opérateur NOT. Par exemple, abc -def correspond à une ressource contenant abc, mais pas def.

Le paramètre _text effectue le même type de correspondance uniquement dans le champ Narratif, qui doit contenir un résumé lisible du contenu de la ressource. L'API Cloud Healthcare ne génère pas automatiquement ce résumé, mais accepte le paramètre de recherche _text si ces données ont été renseignées par le client lors de la création ou de la mise à jour de la ressource.

Paramètres de recherche composites

Lorsque vous effectuez une recherche à l'aide de plusieurs paramètres de requête, il arrive que des paramètres de recherche individuels associés à AND correspondent à des résultats inattendus. Les paramètres de recherche composites sont un type spécial de paramètre de recherche qui permet de résoudre ce problème.

Par exemple, la ressource Observation peut contenir plusieurs valeurs dans le champ component, chacune contenant une paire de code et de value. Une recherche de Observation?component-code=8867-4&component-value-quantity=lt50 correspond à une ressource dont un composant contient un élément code de 8867-4 et un composant différent contenant un élément value inférieur à 50. Cette recherche ne peut pas être utilisée pour limiter à une correspondance de ces deux valeurs dans le même composant.

Les paramètres de recherche composites définissent un nouveau paramètre qui combine deux autres paramètres de recherche et définit un niveau d'imbrication dans lequel ils doivent tous les deux correspondre. Dans la requête, les deux valeurs sont jointes par $. Par exemple, Observation dispose d'un paramètre composite component-code-value-quantity qui peut limiter l'exemple précédent à un seul composant en recherchant Observation?component-code-value-quantity=8867-4$lt50. Ces paramètres sont définis par la spécification FHIR et n'existent pas pour toutes les combinaisons de paramètres de recherche.

Les paramètres de recherche composites n'autorisent pas les modificateurs.

Comme pour tous les paramètres de recherche, des informations sur les paramètres composites compatibles avec l'API Cloud Healthcare sont disponibles dans la déclaration de capacité ou la déclaration de conformité FHIR.

Une recherche en chaîne permet à une recherche de traverser des références dans le contexte d'une requête. La syntaxe de base d'une recherche en chaîne est la suivante :

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

Si le paramètre de référence ne fait référence qu'à un seul type de ressource, :[resource type] peut être omis, ce qui entraîne :

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

Par exemple, Observation dispose d'un paramètre de recherche de référence subject qui peut pointer vers Group, Device, Patient ou Location. Pour trouver Observations dont un subject est un Patient dont le nom commence par "Joe", vous pouvez effectuer une recherche sur Observation?subject:Patient.name=Joe.

Les recherches en chaîne peuvent comporter plusieurs niveaux, par exemple Observation?subject:Patient.organization:Organization.name=Acme. Dans cet exemple, :Organization a pu être omis, car le paramètre de recherche de l'organisation ne peut pointer que vers des ressources Organization, ce qui donne Observation?subject:Patient.organization.name=Acme.

Si la requête comporte plusieurs paramètres en chaîne, chaque chaîne est évaluée séparément. Par exemple, Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada correspond à un Patient comportant deux références general-practitioner, l'une nommée "Joe" et l'autre ayant une adresse au Canada. Il n'existe pas de syntaxe permettant de regrouper ces clauses pour ne faire correspondre que Joe du Canada.

Une recherche en chaîne inversée correspond aux ressources en fonction des critères d'autres ressources qui s'y rapportent. La syntaxe d'une recherche en chaîne inverse est la suivante :

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

Par exemple, la ressource Appointment possède un paramètre de recherche patient faisant référence à une ressource Patient. Pour trouver toutes les ressources Patient référencées par une ressource Appointment dont la date est 2020-04-01, utilisez Patient?_has:Appointment:patient:date=eq2020-04-01.

Les chaînes inversées peuvent être récursives. Par exemple, Practitioner?_has:Encounter:practitioner:_has:Claim:encounter:created=eq2020-04-01 correspond à un Practitioner P s'il existe un Encounter E et un Claim C de sorte que C ait une date de création de 2020-04-01, que C fasse référence à E via sa référence encounter et que E fasse référence à P via sa référence practitioner.

Inclure des ressources supplémentaires dans les résultats de recherche

Les paramètres _include et _revinclude nécessitent que les résultats de recherche incluent des ressources supplémentaires ("ressources incluses") associées aux ressources correspondant directement à la requête ("résultats principaux"). L'utilisation de ces paramètres est plus efficace qu'une série de requêtes effectuées pour récupérer ces ressources supplémentaires séparément. Dans le groupe searchset renvoyé par la recherche, les ressources ajoutées par ces paramètres sont signalées par entry.search.mode = include afin de se distinguer des résultats principaux contenant entry.search.mode = match.

L'inclusion directe avec _include ajoute des ressources référencées par les résultats principaux, et l'inclusion inverse avec _revinclude ajoute des ressources qui référencent les résultats principaux. La référence à suivre est spécifiée par le nom d'un paramètre de recherche. Seuls les champs de référence disponibles en tant que paramètres de recherche peuvent être utilisés de cette manière.

Les formats de paramètre _include et _revinclude sont identiques, en prenant deux ou trois valeurs délimitées par :. La première valeur est le type de ressource dont provient la référence, la deuxième le nom du paramètre de recherche et la troisième valeur facultative limite le type de ressource à un seul type dans le cas où la référence peut pointer vers plusieurs types.

Exemple :

  • MedicationRequest?_include=MedicationRequest:subject recherche sur les ressources MedicationRequest, et pour chaque ressource renvoyée, renvoie également la cible de la référence subject, qui peut être un Group ou un Patient tel que défini dans la spécification FHIR.
  • MedicationRequest?_include=MedicationRequest:subject:Patient est similaire, mais ne renvoie que des références subject aux ressources Patient.
  • MedicationRequest?_revinclude=Provenance:target recherche sur les ressources MedicationRequest, et pour chaque ressource renvoyée renvoie également toutes les ressources Provenance où la référence target sur Provenance fait référence à la ressource correspondante.

Le modificateur :iterate entraîne l'évaluation itérative d'un élément _include ou _revinclude. Ce modificateur peut suivre une couche supplémentaire de références à partir des résultats inclus ou suivre des structures récursives telles que Observation:derived-from faisant référence à un autre Observation. La profondeur de la récursion est limitée.

Exemple :

  • Observation?_include:iterate=Observation:derived-from:Observation recherches sur les ressources Observation et suit de manière récursive la référence dérivée des ressources Observation correspondantes, puis des ressources incluses, etc.
  • MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agent effectue une recherche sur MedicationRequest, inclut les ressources Provenance avec un target dans cet ensemble de résultats, puis inclut également les ressources référencées via le paramètre agent de ces ressources Provenance.

Les ressources incluses sont dédupliquées, de sorte qu'une seule copie d'une ressource est renvoyée dans une page de résultats, même si elle est trouvée via plusieurs références. La même ressource incluse est renvoyée sur chaque page de résultats lorsqu'un résultat principal s'y rapporte.

Limiter les champs affichés dans les résultats de recherche

Le paramètre _elements permet au client de demander que seul un sous-ensemble de champs soit renvoyé pour chaque résultat de recherche afin de réduire la taille de la réponse en omettant les données inutiles. Le paramètre accepte une liste de noms d'éléments de base séparés par une virgule dans la ressource, par exemple Patient?_elements=identifier,contact,link. Seuls ces champs et leurs enfants seront inclus dans les ressources renvoyées. Les ressources de la réponse qui ont été modifiées par ce paramètre contiennent une valeur meta.tag de SUBSETTED pour indiquer qu'elles sont incomplètes.

L'API Cloud Healthcare est limitée pour le paramètre _summary, qui fournit des sous-ensembles prédéfinis de champs de ressources similaires à _elements :

  • _summary=text ne renvoie que les champs de niveau supérieur text, id et meta.
  • _summary=data supprime le champ text et renvoie tous les autres champs.