Información general de búsqueda FHIR
La especificación Fast Healthcare Interoperability Resources (FHIR®) define una API para consultar recursos en una base de datos del servidor FHIR. Este artículo le guía por los aspectos clave de la consulta de datos en FHIR. Para obtener detalles completos sobre la API de búsqueda de FHIR, consulte la documentación de Búsqueda de FHIR de HL7.
En este artículo, se muestra la sintaxis de búsqueda de FHIR en llamadas API de ejemplo con el {{FHIR_URL}} marcador de posición para representar la dirección URL del servidor FHIR. Si el servicio FHIR está en Azure Health Data Services, esta dirección URL sería https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
Las búsquedas de FHIR se pueden realizar sobre un tipo de recurso concreto, un compartimiento especificado o todos los recursos en la base de datos del servidor FHIR. La manera más sencilla de ejecutar una búsqueda en FHIR consiste en usar una solicitud GET. Por ejemplo, si desea extraer todos los Patient recursos de la base de datos, puede usar la siguiente solicitud.
GET {{FHIR_URL}}/Patient
También puede realizar búsquedas con POST. Para buscar mediante POST, los parámetros de búsqueda se entregan en el cuerpo de la solicitud. Esto facilita el envío de consultas con una serie más larga y compleja de parámetros.
Con o POST GET, si la solicitud de búsqueda se realiza correctamente, recibirá un lote de FHIR searchset que contiene las instancias de recursos devueltas de la búsqueda. Si se produce un error en la búsqueda, encontrará los detalles del error en una respuesta OperationOutcome.
En las secciones siguientes, tratamos los distintos aspectos de la consulta de recursos en FHIR. Una vez que haya revisado estos temas, consulte la Página de ejemplos de búsqueda de FHIR, que incluye ejemplos de diferentes métodos de búsqueda de FHIR.
Parámetros de búsqueda
Al realizar una búsqueda en FHIR, está buscando en la base de datos recursos que coincidan con determinados criterios. La API de FHIR especifica un amplio conjunto de parámetros de búsqueda para ajustar los criterios de búsqueda. Cada recurso de FHIR incluye información como un conjunto de elementos y los parámetros de búsqueda funcionan para consultar la información de estos elementos. En una llamada a la API de búsqueda de FHIR, si se encuentra una coincidencia positiva entre los parámetros de búsqueda de la solicitud y los valores de elemento correspondientes almacenados en una instancia de recurso, el servidor FHIR devuelve una agrupación que contiene las instancias de recursos cuyos elementos cumplen los criterios de búsqueda.
Para cada parámetro de búsqueda, la especificación FHIR define el tipo de datos que se puede usar. A continuación se describe la compatibilidad con el servicio FHIR para los distintos tipos de datos.
| Tipo de parámetro de búsqueda | Servicio FHIR en Azure Health Data Services | Azure API for FHIR | Comentario |
|---|---|---|---|
| number | Sí | Sí | |
| date | Sí | Sí | |
| string | Sí | Sí | |
| token | Sí | Sí | |
| reference | Sí | Sí | |
| composite | Parcial | Parcial | La lista de tipos compuestos admitidos sigue en este artículo. |
| quantity | Sí | Sí | |
| uri | Sí | Sí | |
| especial | No | No |
Parámetros de búsqueda comunes
Hay parámetros de búsqueda comunes que se aplican a todos los recursos en FHIR. Estos se enumeran de la siguiente manera, junto con su soporte técnico en el servicio FHIR.
| Parámetro de búsqueda común | Servicio FHIR en Azure Health Data Services | Azure API for FHIR | Comentario |
|---|---|---|---|
_id |
Sí | Sí | |
_lastUpdated |
Sí | Sí | |
_tag |
Sí | Sí | |
_type |
Sí | Sí | |
_security |
Sí | Sí | |
_profile |
Sí | Sí | |
_has |
Sí | Sí | |
_query |
No | N.º | |
_filter |
N.º | N.º | |
_list |
N.º | N.º | |
_text |
N.º | N.º | |
_content |
N.º | No |
Parámetros específicos del recurso
El servicio FHIR de Azure Health Data Services admite casi todos los parámetros de búsqueda específicos de recursos definidos en la especificación de FHIR. Los parámetros de búsqueda que no se admiten se enumeran en los vínculos siguientes:
También puede ver la compatibilidad actual con los parámetros de búsqueda en FHIR Capability Statement con la siguiente solicitud:
GET {{FHIR_URL}}/metadata
Para ver los parámetros de búsqueda admitidos en la instrucción de funcionalidad, vaya a CapabilityStatement.rest.resource.searchParam para ver los parámetros de búsqueda específicos del recurso y CapabilityStatement.rest.searchParam para los parámetros de búsqueda que se aplican a todos los recursos.
Nota:
El servicio FHIR de Azure Health Data Services no indexa automáticamente los parámetros de búsqueda que no están definidos en la especificación de FHIR base. El servicio FHIR admite parámetros de búsqueda personalizados.
Parámetros de búsqueda compuestos
Las búsquedas compuestas en FHIR permiten buscar en pares de elementos como unidades conectadas lógicamente. Por ejemplo, si estuviera buscando observaciones en las que el alto del paciente era superior a 60 pulgadas, querrá asegurarse de que una sola propiedad de la observación contenga el código de altura y un valor superior a 60 pulgadas (el valor solo debe pertenecer a la altura). Por ejemplo, no desearía una coincidencia positiva en una observación con el código de altura y un código de longitud de brazo de más de 60 pulgadas. Los parámetros de búsqueda compuestos impiden que se produzca este problema mediante la búsqueda en pares de elementos especificados previamente cuyos valores deben cumplir los criterios de búsqueda para que se produzca una coincidencia positiva.
El servicio FHIR de Azure Health Data Services admite los siguientes emparejamientos de tipos de parámetros de búsqueda para búsquedas compuestas.
- Referencia, Token
- Token, Fecha
- Token, Número, Número
- Token, Cantidad
- Token, Cadena
- Token, Token
Para obtener más información, vea la documentación Parámetros de búsqueda compuestos de HL7.
Nota:
Los parámetros de búsqueda compuestos no admiten modificadores según la especificación de FHIR.
Modificadores y prefijos
Los modificadores permiten calificar los parámetros de búsqueda con condiciones adicionales. A continuación se muestra una tabla de modificadores de FHIR y su compatibilidad con el servicio FHIR.
| Modificadores | Servicio FHIR en Azure Health Data Services | Azure API for FHIR | Comentario |
|---|---|---|---|
:missing |
Sí | Sí | |
:exact |
Sí | Sí | |
:contains |
Sí | Sí | |
:text |
Sí | Sí | |
:type (referencia) |
Sí | Sí | |
:not |
Sí | Sí | |
:below (uri) |
Sí | Sí | |
:above (uri) |
Sí | Sí | |
:in (token) |
No | No | |
:below (token) |
No | No | |
:above (token) |
No | No | |
:not-in (token) |
No | N.º | |
:identifier |
N.º | No |
Para los parámetros de búsqueda que tienen un orden específico (números, fechas y cantidades), puede usar un prefijo antes del valor del parámetro para refinar los criterios de búsqueda (por ejemplo, Patient?_lastUpdated=gt2022-08-01 donde el prefijo gt significa "mayor que"). El servicio FHIR de Azure Health Data Services admite todos los prefijos definidos en el estándar FHIR.
Parámetros de resultados de la búsqueda
FHIR especifica un conjunto de parámetros de resultados de búsqueda para ayudar a administrar la información devuelta desde una búsqueda. Para obtener más información sobre cómo usar parámetros de resultados de búsqueda en FHIR, consulte el sitio web de HL7 . A continuación se muestra una tabla de parámetros de resultados de búsqueda de FHIR y su compatibilidad con el servicio FHIR.
| Parámetros de resultados de búsqueda | Servicio FHIR en Azure Health Data Services | Azure API for FHIR | Comentario |
|---|---|---|---|
_elements |
Sí | Sí | |
_count |
Sí | Sí | _count se limita a 1000 recursos. Si se establece más de 1000, solo se devuelven 1000 y se incluirá una advertencia en la agrupación. |
_include |
Sí | Sí | Los elementos recuperados con _include están limitados a 100. _include en PaaS y soS en Azure Cosmos DB no admite :iterate (2137). |
_revinclude |
Sí | Sí | Los elementos recuperados con _revinclude están limitados a 100. _revinclude en PaaS y soS en Azure Cosmos DB no admite :iterate (2137). También hay un código de estado incorrecto para una solicitud incorrecta: #1319. |
_summary |
Sí | Sí | |
_total |
Parcial | Parcial | _total=none y _total=accurate |
_sort |
Parcial | Parcial | sort=_lastUpdated se admite en el servicio FHIR. Para el servicio FHIR y los servidores FHIR de OSS SQL DB, se admite la ordenación por cadenas y campos dateTime. Para Azure API for FHIR y las bases de datos de OSS Azure Cosmos DB creadas después del 20 de abril de 2021, también se admite la ordenación por nombre, apellido, fecha de nacimiento y fecha clínica. |
_contained |
No | N.º | |
_containedType |
N.º | N.º | |
_score |
N.º | No |
Nota:
- De forma predeterminada,
_sortorganiza los registros en orden ascendente. Puede usar el prefijo-para ordenar en orden descendente. El servicio FHIR solo permite ordenar un solo campo a la vez. - El servicio FHIR admite búsquedas de caracteres comodín con revinclude. Al agregar un parámetro de consulta "." en una consulta revinclude, el servicio FHIR hace referencia a todos los recursos asignados al recurso de origen.
De forma predeterminada, el servicio FHIR de Azure Health Data Services se establece en control flexible. Esto significa que el servidor omite los parámetros desconocidos o no admitidos. Si quiere usar un control estricto, puede incluir el encabezado Prefer y establecer handling=strict.
Búsqueda encadenada y búsqueda encadenada inversa
Una búsqueda encadenada permite realizar consultas específicas para los recursos que tienen una referencia a otro recurso. Por ejemplo, si quiere encontrar instancias donde el nombre del paciente sea Jane, use lo siguiente:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
En . la solicitud anterior se dirige la ruta de acceso de la búsqueda encadenada al parámetro de destino (name en este caso).
De forma similar, puede realizar una búsqueda encadenada inversa con el parámetro _has. Esto le permite recuperar instancias de recursos especificando criterios en otros recursos que hacen referencia a los recursos de interés. Para obtener ejemplos de búsqueda encadenada e inversa, consulte la página de ejemplos de búsqueda de FHIR.
Paginación
Como se mencionó anteriormente, los resultados de una búsqueda de FHIR están disponibles en formulario paginado en un vínculo proporcionado en la searchset agrupación. De forma predeterminada, el servicio FHIR muestra 10 resultados de búsqueda por página, pero esto se puede aumentar (o disminuir) estableciendo el _count parámetro . Si hay más coincidencias de las que caben en una página, la agrupación incluye un next vínculo. La captura repetida del next vínculo produce las páginas de resultados posteriores. Tenga en cuenta que el _count valor del parámetro no puede superar los 1000.
Actualmente, el servicio FHIR de Azure Health Data Services solo admite el vínculo next y no admite vínculos first, last o previous en agrupaciones devueltas de una búsqueda.
Preguntas más frecuentes
¿Qué significa "compatibilidad parcial" en parámetros de búsqueda no admitidos de R4?
Algunos de los parámetros de búsqueda específicos del recurso cubren más de un tipo de datos y el servicio FHIR en Azure Health Data Services solo puede admitir ese parámetro de búsqueda en uno de esos tipos de datos. Por ejemplo, Condition-abatement-age y Condition-onset-age cubren dos tipos de datos diferentes, Age y Range; Sin embargo, el servicio FHIR en Azure Health Data Services admite esos dos parámetros de búsqueda en Range, pero no en Age.
¿Se admite la operación de $lastn para observaciones?
Esto no se admite. El enfoque alternativo sería usar _count para restringir los recursos devueltos por página y _sort para proporcionar resultados en orden descendente.
Pasos siguientes
Ahora que ha aprendido los conceptos básicos de la búsqueda FHIR, vea la página de ejemplos de búsqueda para obtener más información sobre cómo realizar búsquedas con diferentes parámetros de búsqueda, modificadores y otros métodos de búsqueda de FHIR.
Nota:
FHIR® es una marca registrada de HL7 y se usa con su permiso.