Información general de la búsqueda en Azure API for FHIR
Importante
Azure API for FHIR se retirará el 30 de septiembre de 2026. Siga las estrategias de migración para realizar la transición a servicio FHIR® de Azure Health Data Services en esa fecha. Debido a la retirada de Azure API for FHIR, no se permitirán nuevas implementaciones a partir del 1 de abril de 2025. El servicio FHIR de Azure Health Data Services es la versión evolucionada de la API de Azure para FHIR que permite a los clientes administrar FHIR, DICOM y los servicios de tecnologías médicas con integraciones en otros servicios de Azure.
La especificación de Recursos Rápidos de Interoperabilidad en Salud (FHIR®) define los aspectos básicos de la búsqueda de recursos de FHIR. Este artículo le guía por algunos aspectos clave de la búsqueda de recursos en FHIR. Para obtener detalles completos sobre cómo buscar recursos de FHIR, vea Búsqueda en la especificación de HL7 FHIR. En este artículo, se proporcionan ejemplos de sintaxis de búsqueda. Cada búsqueda está en el servidor FHIR, que normalmente tiene una dirección URL de https://<FHIRSERVERNAME>.azurewebsites.net. En los ejemplos, usamos el marcador de posición {{FHIR_URL}} para esta dirección URL.
Las búsquedas de FHIR se pueden realizar sobre un tipo de recurso concreto, un compartimiento especificado o todos los recursos. 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 pacientes de la base de datos, puede usar la siguiente solicitud.
GET {{FHIR_URL}}/Patient
También puede buscar mediante POST, que es útil si la cadena de consulta es larga. Para realizar búsquedas con POST, los parámetros de búsqueda se pueden enviar como el cuerpo de un formulario. Esto permite series más largas y complejas de parámetros de consulta que pueden ser difíciles de ver y comprender en una cadena de consulta.
Si la solicitud de búsqueda se realiza correctamente, recibirá una respuesta de agrupación de FHIR con el tipo searchset. Si se produce un error en la búsqueda, puede encontrar los detalles del error en OperationOutcome para ayudarle a comprender por qué se produjo un error en la búsqueda.
En las secciones siguientes, tratamos los distintos aspectos implicados en la búsqueda. Una vez que haya revisado estos detalles, consulte nuestra página de ejemplos que contiene ejemplos de búsquedas que puede realizar en Azure API for FHIR.
Parámetros de búsqueda
Las búsquedas se basan en varios atributos del recurso. Estos atributos se denominan parámetros de búsqueda. Cada recurso tiene un conjunto de parámetros de búsqueda definidos. El parámetro de búsqueda se debe definir e indexar en la base de datos para que pueda buscarlo correctamente.
Cada parámetro de búsqueda tiene un tipo de datos definido. En la tabla siguiente se describe la compatibilidad con los distintos tipos de datos.
Advertencia
Actualmente hay un problema al usar _sort en Azure API for FHIR con la búsqueda encadenada. Para obtener más información, vea el problema de código abierto n.º 2344. Esto se resolverá con una versión de diciembre de 2021.
| Tipo de parámetro de búsqueda | Azure API for FHIR | Servicio FHIR en Azure Health Data Services | 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 se describe más adelante en este artículo. |
| cantidad | 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. Estas se encuentran en la lista siguiente, junto con su soporte técnico en Azure API for FHIR.
| Parámetro de búsqueda común | Azure API for FHIR | Servicio FHIR en Azure Health Data Services | Comentario |
|---|---|---|---|
| _id | Sí | Sí | |
| _lastUpdated | Sí | Sí | |
| _tag | Sí | Sí | |
| _type | Sí | Sí | |
| _security | Sí | Sí | |
| _profile | Sí | Sí | |
| _has | Parcial | Sí | La compatibilidad con _has se encuentra en MVP en Azure API for FHIR y en la versión del sistema operativo respaldada por Azure Cosmos DB. En la siguiente sección de encadenamiento se incluyen más detalles. |
| _query | No | No | |
| _filter | No | No | |
| _list | No | No | |
| _text | No | No | |
| _content | No | No |
Parámetros específicos del recurso
Con Azure API for FHIR, se admiten prácticamente todos los parámetros de búsqueda específicos del recurso definidos por la especificación FHIR. Los únicos parámetros de búsqueda que no se admiten están disponibles en los vínculos siguientes.
También puede ver la compatibilidad actual con los parámetros de búsqueda en la instrucción de funcionalidad de FHIR con la siguiente solicitud.
GET {{FHIR_URL}}/metadata
Para ver los parámetros de búsqueda en la instrucción de funcionalidad, vaya a para CapabilityStatement.rest.resource.searchParam ver los parámetros de búsqueda de cada recurso y CapabilityStatement.rest.searchParam para buscar los parámetros de búsqueda de todos los recursos.
Nota:
En Azure API for FHIR no se crean ni indexan automáticamente los parámetros de búsqueda que no estén definidos por la especificación de FHIR. Sin embargo, proporcionamos compatibilidad para definir sus propios parámetros de búsqueda.
Parámetros de búsqueda compuestos
La búsqueda compuesta permite buscar en pares de valores. Por ejemplo, si tuviera que buscar una observación de altura en la que la persona medía 152,4 cm, querría asegurarse de que un solo componente de la observación contiene el código de altura y el valor de 152,4. No le gustaría obtener una observación en la que se almacenase un peso de 152,4 y una altura de 121,92, aunque la observación tuviera entradas que se calificaran para el valor 152,4 y el código de altura, pero en secciones de componentes diferentes.
Con Azure API for FHIR, se admiten los siguientes emparejamientos de tipos de parámetros de búsqueda.
- Referencia, Token
- Token, Fecha
- Token, Número, Número
- Token, Cantidad
- Token, Cadena
- Token, Token
Para obtener más información, vea los parámetros de búsqueda compuesta 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 alterar el parámetro de búsqueda. La tabla siguiente es una introducción a todos los modificadores de FHIR y su compatibilidad con Azure API for FHIR.
| Modificadores | Azure API for FHIR | Servicio FHIR en Azure Health Data Services | Comentario |
|---|---|---|---|
| :missing | Sí | Sí | |
| :exact | Sí | Sí | |
| :contains | Sí | Sí | |
| texto: | Sí | Sí | |
| :type (reference) | 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 | No |
Para los parámetros de búsqueda que tienen un orden concreto (números, fechas y cantidades), puede usar un prefijo en el parámetro a fin de facilitar la búsqueda de coincidencias. Azure API for FHIR admite todos los prefijos.
Parámetros de resultados de la búsqueda
Para ayudar a administrar los recursos devueltos, hay parámetros de resultado de búsqueda que puede usar. Para obtener más información sobre cómo usar cada uno de los parámetros de resultado de la búsqueda, consulte el sitio web de HL7.
| Parámetros de resultados de búsqueda | Azure API for FHIR | Servicio FHIR en Azure Health Data Services | Comentario |
|---|---|---|---|
| _elements | Sí | Sí | |
| _contar | Sí | Sí | _count se limita a 1000 recursos. Si se establece más de 1000, solo se devuelven 1000 y se devolverá una advertencia en el lote. |
| _include | Sí | Sí | Los elementos incluidos se limitan a 100. _include en PaaS y OSS en Azure Cosmos DB no incluyen compatibilidad con :iterate (n.º 2137). |
| _revinclude | Sí | Sí | Los elementos incluidos se limitan a 100. _revinclude en PaaS y OSS en Azure Cosmos DB no incluyen compatibilidad con :iterate (n.º 2137). También hay un código de estado incorrecto para una solicitud incorrecta n.º 1319 |
| _summary | Sí | Sí | |
| _total | Parcial | Parcial | _total=none y _total=accurate |
| _sort | Parcial | Parcial | sort=_lastUpdated se admite en Azure API for FHIR y el servicio FHIR. 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 | No | |
| _containedType | No | No | |
| _score | No | N.º |
Nota:
De manera predeterminada, _sort ordena el registro en orden ascendente. Puede usar el prefijo '-' para ordenar en orden descendente. Además, el servicio FHIR y Azure API for FHIR solo permiten ordenar un solo campo a la vez.
De manera predeterminada, Azure API for FHIR se establece en control sensible. Esto significa que el servidor omite los parámetros desconocidos o no admitidos. Si quiere usar un control estricto, puede usar el encabezado Prefer y establecer handling=strict.
Búsqueda encadenada y búsqueda encadenada inversa
Una búsqueda encadenada permite buscar mediante un parámetro de búsqueda en un recurso al que hace referencia 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.
De forma similar, puede realizar una búsqueda encadenada inversa. Esto le permite obtener recursos donde se especifican criterios en otros recursos que hacen referencia a ellos. Para obtener más ejemplos de búsqueda encadenada e inversa, consulte la página de ejemplos de búsqueda de FHIR.
Nota:
En Azure API for FHIR y el código abierto con respaldo de Azure Cosmos DB, hay una limitación por la que cada subconsulta necesaria para las búsquedas encadenadas y encadenadas inversas solo devolverá 1000 elementos. Si se encuentran más de 1000 elementos, recibirá este mensaje de error: "Las subconsultas en una expresión encadenada no pueden devolver más de 1000 resultados, use un criterio más selectivo". Para obtener una consulta correcta, debe ser más específico en lo que busca.
Paginación
Como se mencionó anteriormente, los resultados de una búsqueda son una agrupación paginada. De forma predeterminada, la búsqueda devuelve 10 resultados por página, pero esto se puede aumentar (o disminuir) especificando _count. Dentro de la agrupación, habrá un vínculo propio que contiene el resultado actual de la búsqueda. Si hay coincidencias adicionales, la agrupación contendrá un vínculo siguiente. Puede seguir usando el vínculo siguiente para obtener las páginas de resultados posteriores. _count se limita a 1000 elementos o menos.
El siguiente vínculo de la agrupación tiene un límite de tamaño de token de continuación de 3 KB. Tiene flexibilidad para ajustar el tamaño del token de continuación entre 1 KB y 3 KB mediante el encabezado x-ms-documentdb-responsecontinuationtokenlimitinkb.
Actualmente, Azure API for FHIR solo admite el vínculo siguiente en las agrupaciones y no admite los vínculos primero, último o anterior.
Pasos siguientes
Ahora que ha aprendido sobre los conceptos básicos de la búsqueda, consulte la página de ejemplos de búsqueda para obtener más información sobre cómo buscar mediante distintos parámetros de búsqueda, modificadores y otros escenarios de búsqueda de FHIR.
Nota:
FHIR® es una marca registrada de HL7 y se usa con su permiso.