Overzicht van zoekfunctie voor FHIR
De FHIR-specificatie® (Fast Healthcare Interoperability Resources) definieert een API voor het opvragen van resources in een FHIR-serverdatabase. In dit artikel wordt u begeleid bij enkele belangrijke aspecten van het opvragen van gegevens in FHIR. Raadpleeg de HL7 FHIR Search-documentatie voor volledige informatie over de FHIR-zoek-API.
In dit artikel laten we de FHIR-zoeksyntaxis zien in voorbeeld-API-aanroepen met de tijdelijke aanduiding voor de {{FHIR_URL}} FHIR-server-URL. In het geval van de FHIR-service in Azure Health Data Services zou deze URL zijn https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
FHIR-zoekopdrachten kunnen betrekking hebben op een specifiek resourcetype, een opgegeven compartiment of alle resources in de FHIR-serverdatabase. De eenvoudigste manier om een zoekopdracht uit te voeren in FHIR is door een GET aanvraag te gebruiken. Als u bijvoorbeeld alle Patient resources in de database wilt ophalen, kunt u de volgende aanvraag gebruiken:
GET {{FHIR_URL}}/Patient
U kunt ook zoeken met behulp van POST. Als u wilt zoeken met behulp POSTvan, worden de zoekparameters geleverd in de hoofdtekst van de aanvraag. Dit maakt het eenvoudiger om query's met langere, complexere reeks parameters te verzenden.
POST GETAls de zoekaanvraag is geslaagd, ontvangt u een FHIR-bundel searchset met de resource-instanties die zijn geretourneerd door de zoekopdracht. Als de zoekopdracht mislukt, vindt u de foutdetails in een OperationOutcome antwoord.
In de volgende secties behandelen we de verschillende aspecten van het opvragen van resources in FHIR. Zodra u deze onderwerpen hebt bekeken, raadpleegt u de pagina met FHIR-zoekvoorbeelden, die voorbeelden van verschillende FHIR-zoekmethoden bevat.
Zoekparameters
Wanneer u een zoekopdracht uitvoert in FHIR, zoekt u in de database naar resources die voldoen aan bepaalde zoekcriteria. De FHIR-API geeft een uitgebreide set zoekparameters op voor het verfijnen van zoekcriteria. Elke resource in FHIR draagt informatie als een set elementen en zoekparameters werken om een query uit te voeren op de informatie in deze elementen. Als in een FHIR-zoek-API-aanroep een positieve overeenkomst wordt gevonden tussen de zoekparameters van de aanvraag en de bijbehorende elementwaarden die zijn opgeslagen in een resource-exemplaar, retourneert de FHIR-server een bundel met de resource-instanties waarvan de elementen voldoen aan de zoekcriteria.
Voor elke zoekparameter definieert de FHIR-specificatie de gegevenstypen die kunnen worden gebruikt. Ondersteuning in de FHIR-service voor de verschillende gegevenstypen wordt hieronder beschreven.
| Type zoekparameter | FHIR-service in Azure Health Data Services | Azure API for FHIR | Opmerking |
|---|---|---|---|
| Nummer | Ja | Ja | |
| datum | Ja | Ja | |
| tekenreeks | Ja | Ja | |
| token | Ja | Ja | |
| referentie | Ja | Ja | |
| composiet | Gedeeltelijk | Gedeeltelijk | De lijst met ondersteunde samengestelde typen wordt verderop in dit artikel gegeven. |
| quantity | Ja | Ja | |
| uri | Ja | Ja | |
| bijzonder | Nee | Nr. |
Algemene zoekparameters
Er zijn algemene zoekparameters die van toepassing zijn op alle resources in FHIR. Deze worden hieronder vermeld, samen met hun ondersteuning in de FHIR-service:
| Algemene zoekparameter | FHIR-service in Azure Health Data Services | Azure API for FHIR | Opmerking |
|---|---|---|---|
_id |
Ja | Ja | |
_lastUpdated |
Ja | Ja | |
_tag |
Ja | Ja | |
_type |
Ja | Ja | |
_security |
Ja | Ja | |
_profile |
Ja | Ja | |
_has |
Ja | Ja | |
_query |
No | Nee | |
_filter |
Nee | Nee | |
_list |
Nee | Nee | |
_text |
Nee | Nee | |
_content |
Nee | Nr. |
Resourcespecifieke parameters
De FHIR-service in Azure Health Data Services ondersteunt bijna alle resourcespecifieke zoekparameters die zijn gedefinieerd in de FHIR-specificatie. Zoekparameters die niet worden ondersteund, worden weergegeven in de onderstaande koppelingen:
U kunt ook de huidige ondersteuning voor zoekparameters zien in de FHIR-mogelijkheidsinstructie met de volgende aanvraag:
GET {{FHIR_URL}}/metadata
Als u de ondersteunde zoekparameters in de mogelijkheidsinstructie wilt weergeven, gaat u naar CapabilityStatement.rest.resource.searchParam de resourcespecifieke zoekparameters en CapabilityStatement.rest.searchParam naar zoekparameters die van toepassing zijn op alle resources.
Notitie
De FHIR-service in Azure Health Data Services indexeert niet automatisch zoekparameters die niet zijn gedefinieerd in de basis-FHIR-specificatie. De FHIR-service biedt echter wel ondersteuning voor aangepaste zoekparameters.
Samengestelde zoekparameters
Met samengestelde zoekopdrachten in FHIR kunt u zoeken op elementparen als logisch verbonden eenheden. Als u bijvoorbeeld zoekt naar waarnemingen waarbij de lengte van de patiënt meer dan 60 inch was, moet u ervoor zorgen dat één eigenschap van de observatie de hoogtecode bevat en een waarde groter dan 60 inch (de waarde mag alleen betrekking hebben op de hoogte). U wilt geen positieve overeenkomst retourneren voor een observatie met de hoogtecode en een arm tot arm lengte van meer dan 60 inch, bijvoorbeeld. Samengestelde zoekparameters voorkomen dit probleem door te zoeken naar vooraf opgegeven paren elementen waarvan de waarden beide moeten voldoen aan de zoekcriteria voor een positieve overeenkomst.
De FHIR-service in Azure Health Data Services ondersteunt de volgende combinaties van zoekparameters voor samengestelde zoekopdrachten:
- Verwijzing, token
- Token, datum
- Token, getal, getal
- Token, Hoeveelheid
- Token, tekenreeks
- Token, Token
Zie de documentatie van hl7 Composite Search Parameters voor meer informatie.
Notitie
Samengestelde zoekparameters bieden geen ondersteuning voor modifiers, volgens de FHIR-specificatie.
Modifiers en voorvoegsels
Met modifiers kunt u zoekparameters kwalificeren met aanvullende voorwaarden. Hieronder vindt u een lijst met FHIR-modifiers en hun ondersteuning in de FHIR-service:
| Modifiers | FHIR-service in Azure Health Data Services | Azure API for FHIR | Opmerking |
|---|---|---|---|
:missing |
Ja | Ja | |
:exact |
Ja | Ja | |
:contains |
Ja | Ja | |
:text |
Ja | Ja | |
:type (verwijzing) |
Ja | Ja | |
:not |
Ja | Ja | |
:below (URI) |
Ja | Ja | |
:above (URI) |
Ja | Ja | |
:in (token) |
Nee | Nr. | |
:below (token) |
Nee | Nr. | |
:above (token) |
Nee | Nr. | |
:not-in (token) |
Nee | Nee | |
:identifier |
Nee | Nr. |
Voor zoekparameters met een specifieke volgorde (getallen, datums en hoeveelheden) kunt u een voorvoegsel voor de parameterwaarde gebruiken om de zoekcriteria te verfijnen (bijvoorbeeld Patient?_lastUpdated=gt2022-08-01 wanneer het voorvoegsel gt 'groter dan' betekent). De FHIR-service in Azure Health Data Services ondersteunt alle voorvoegsels die zijn gedefinieerd in de FHIR-standaard.
Parameters voor zoekresultaat
FHIR geeft een set zoekresultaatparameters op om de informatie te beheren die wordt geretourneerd door een zoekopdracht. Raadpleeg de HL7-website voor gedetailleerde informatie over het gebruik van zoekresultaatparameters in FHIR. Hieronder ziet u een lijst met FHIR-zoekresultaatparameters en hun ondersteuning in de FHIR-service.
| Parameters voor zoekresultaat | FHIR-service in Azure Health Data Services | Azure API for FHIR | Opmerking |
|---|---|---|---|
_elements |
Ja | Ja | |
_count |
Ja | Ja | _count is beperkt tot 1000 resources. Als deze hoger is dan 1000, worden er slechts 1000 geretourneerd en wordt er een waarschuwing opgenomen in de bundel. |
_include |
Ja | Ja | Items die worden opgehaald met _include zijn beperkt tot 100. _includeop PaaS en OSS in Azure Cosmos DB wordt niet ondersteund :iterate (#2137). |
_revinclude |
Ja | Ja | Items die worden opgehaald met _revinclude zijn beperkt tot 100. _revincludeop PaaS en OSS in Azure Cosmos DB wordt niet ondersteund :iterate (#2137). Er is ook een onjuiste statuscode voor een ongeldige aanvraag #1319. |
_summary |
Ja | Ja | |
_total |
Gedeeltelijk | Gedeeltelijk | _total=none en _total=accurate |
_sort |
Gedeeltelijk | Gedeeltelijk | sort=_lastUpdated wordt ondersteund in de FHIR-service. Voor de FHIR-service en de OSS SQL DB FHIR-servers worden sorteren op tekenreeksen en datum/tijd-velden ondersteund. Voor Azure API for FHIR- en OSS Azure Cosmos DB-databases die na 20 april 2021 zijn gemaakt, wordt sortering ondersteund op voornaam, achternaam, geboortedatum en klinische datum. |
_contained |
Nee | Nee | |
_containedType |
Nee | Nee | |
_score |
Nee | Nr. |
Opmerking:
_sortRangschikt standaard records in oplopende volgorde. U kunt ook het voorvoegsel-gebruiken om in aflopende volgorde te sorteren. Met de FHIR-service kunt u slechts op één veld tegelijk sorteren.- De FHIR-service ondersteunt zoekopdrachten met jokertekens met revinclude. Door de queryparameter '.' toe te voegen in revinclude-query, wordt de FHIR-service om te verwijzen naar alle resources die zijn toegewezen aan de bronresource.
De FHIR-service in Azure Health Data Services is standaard ingesteld op een soepele verwerking. Dit betekent dat de server onbekende of niet-ondersteunde parameters negeert. Als u strikte verwerking wilt gebruiken, kunt u de Prefer koptekst en set handling=strictopnemen.
Gekoppelde en omgekeerde zoekopdrachten
Met een gekoppelde zoekopdracht kunt u nauwkeurig gerichte query's uitvoeren voor resources die een verwijzing naar een andere resource hebben. Als u bijvoorbeeld wilt zien waar de naam van de patiënt Jane is, gebruikt u:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
De . bovenstaande aanvraag stuurt het pad van de gekoppelde zoekopdracht naar de doelparameter (name in dit geval).
Op dezelfde manier kunt u een omgekeerde ketenzoekopdracht uitvoeren met de _has parameter. Hiermee kunt u resource-exemplaren ophalen door criteria op te geven voor andere resources die verwijzen naar de interessante resources. Raadpleeg de pagina met FHIR-zoekvoorbeelden voor voorbeelden van gekoppelde en omgekeerde ketenzoekopdrachten.
Paginering
Zoals hierboven vermeld, zijn de resultaten van een FHIR-zoekopdracht beschikbaar in gepagineerd formulier via een koppeling in de searchset bundel. De FHIR-service geeft standaard 10 zoekresultaten per pagina weer, maar dit kan worden verhoogd (of verlaagd) door de parameter in te _count stellen. Als er meer overeenkomsten zijn dan op één pagina past, bevat de bundel een next koppeling. Herhaaldelijk ophalen van de next koppeling levert de volgende pagina's met resultaten op. Houd er rekening mee dat de _count parameterwaarde niet groter mag zijn dan 1000.
De FHIR-service in Azure Health Data Services ondersteunt momenteel alleen de next koppeling en biedt geen ondersteuning firstvoor , lastof previous koppelingen in bundels die worden geretourneerd door een zoekopdracht.
Volgende stappen
Nu u de basisbeginselen van FHIR-zoekopdrachten hebt geleerd, raadpleegt u de pagina met zoekvoorbeelden voor meer informatie over het zoeken met behulp van zoekparameters, modifiers en andere FHIR-zoekmethoden.
FHIR® is een geregistreerd handelsmerk van HL7 en wordt gebruikt met de machtiging HL7.
Feedback
Binnenkort beschikbaar: In de loop van 2024 zullen we GitHub-problemen geleidelijk uitfaseren als het feedbackmechanisme voor inhoud en deze vervangen door een nieuw feedbacksysteem. Zie voor meer informatie: https://aka.ms/ContentUserFeedback.
Feedback verzenden en weergeven voor