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 al 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 Azure API for FHIR que permite a los clientes administrar los servicios FHIR, DICOM y MedTech 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 guiará 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. A lo largo de este artículo, se proporcionarán ejemplos de sintaxis de búsqueda. Cada búsqueda se realizará en el servidor de FHIR, que normalmente tiene una dirección URL de https://<FHIRSERVERNAME>.azurewebsites.net. En los ejemplos, se usará 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 quiere extraer todos los pacientes de la base de datos, podría usar la solicitud siguiente:
GET {{FHIR_URL}}/Patient
También puede buscar mediante POST, lo que resulta útil si la cadena de consulta es demasiado 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, encontrará los detalles del error en OperationOutcome para ayudarle a entender por qué se ha producido.
En las secciones siguientes, se describirán 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
Cuando realice una búsqueda, lo hará en función de 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. A continuación 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 más información, consulte 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. |
| 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. Se enumeran a continuación, junto con su compatibilidad dentro de 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 para Azure API for FHIR y la versión de OSS con respaldo de Azure Cosmos DB. En la sección de encadenamiento siguiente se incluye más información. |
| _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 FHIR Capability Statement con la siguiente solicitud:
GET {{FHIR_URL}}/metadata
A fin de ver los parámetros de búsqueda en la declaración de funcionalidad, vaya a CapabilityStatement.rest.resource.searchParam para ver los parámetros de búsqueda de cada recurso y a 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 tipo de parámetro 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. A continuación se muestra una introducción de todos los modificadores de FHIR y la compatibilidad en 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 facilitar la administración de los recursos devueltos, puede usar parámetros de resultado de la búsqueda en la búsqueda. 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 en un valor superior a 1000, solo se devolverán 1000 y una advertencia en el conjunto. |
| _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 omitirá 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 ha mencionado antes, los resultados de una búsqueda serán una agrupación paginada. De forma predeterminada, la búsqueda devolverá 10 resultados por página, pero esto se puede aumentar (o disminuir) si se especifica _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 está limitado 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 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 los conceptos básicos de la búsqueda, 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 escenarios de búsqueda de FHIR.
FHIR® es una marca registrada de HL7 y se usa con su permiso.