Funciones avanzadas de búsqueda de FHIR

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

En esta página, se explica cómo buscar recursos de FHIR mediante una funcionalidad de consulta más avanzada disponible a través del método projects.locations.datasets.fhirStores.fhir.search. En esta guía, se da por sentado que estás familiarizado con el contenido de la Búsqueda de recursos de FHIR.

Modificadores de búsqueda de strings

La búsqueda de strings se configura de forma predeterminada como una coincidencia de prefijo que distingue entre mayúsculas y minúsculas y se distingue entre mayúsculas y minúsculas mediante el plegado al formulario estándar Unicode NFC. Se ignoran los signos de puntuación y el espacio en blanco adicional.

Los siguientes modificadores están disponibles:

  • :contains reconoce los recursos con el valor especificado en cualquier parte de la string, por ejemplo, name:contains=eve reconoce Evelyn y Severine.
  • :exact coincide con toda la string, incluidos las mayúsculas y minúsculas y los acentos, por ejemplo, name:exact=Eve no coincide con eve o Evelyn.

Comparadores y precisión para números, fechas y cantidades

Los valores que se usan en una búsqueda numérica o de fecha dependen de la precisión del valor del parámetro. Por ejemplo, el número 7.00 tiene un rango implícito de 6.995 inclusive a 7.005. La fecha 2015-08-12 tiene un rango de 2015-08-12T00:00:00 inclusivo a 2015-08-13T00:00:00.

La precisión afecta los resultados que se muestran para las comparaciones de igualdad. Por ejemplo, un valor de 7.03 en un recurso coincidiría con una búsqueda de value=7.0, pero no con value=7.00.

Todos los valores de punto flotante clínicos significativos en FHIR se representan con tipos como Decimal y Cantidad que registran la precisión del valor almacenado. Como excepción, hay algunos campos que usan números enteros simples, por ejemplo, para representar una posición en una secuencia, y las búsquedas en esos campos son coincidencias numéricas exactas.

Los siguientes prefijos se aplican a las comparaciones numéricas con un valor singleton. Si no se especifican prefijos, el valor predeterminado es eq.

  • eq: es igual, el valor almacenado exacto dentro del rango definido por la precisión del valor del parámetro
  • ne: no es igual, lo opuesto a eq
  • gt: el valor almacenado exacto es mayor que el valor del parámetro exacto.
  • lt: el valor almacenado exacto es menor que el valor del parámetro exacto.
  • ge: el valor almacenado exacto es mayor o igual que el valor del parámetro exacto.
  • le: el valor almacenado exacto es menor o igual que el valor del parámetro exacto.

Los valores de fecha tienen un rango implícito en función del nivel de especificidad del valor (un año, un mes, un día). Otros tipos de datos, como Rango y Período, contienen límites superiores y inferiores explícitos. Los siguientes prefijos se aplican a las comparaciones de rango. Si no se especifican prefijos, el valor predeterminado es eq.

  • eq: es igual, el rango del valor del parámetro que contiene por completo el rango del objetivo
  • ne: no es igual, lo opuesto a eq
  • gt: mayor que, el rango por encima del valor del parámetro se superpone con el rango de destino.
  • lt: menor que, el rango por debajo del valor del parámetro se superpone con el rango de destino.
  • ge: Mayor o igual que
  • le: Menor o igual que
  • sa: el rango del valor del parámetro comienza después del rango de destino.
  • eb: el rango del valor del parámetro finaliza antes del rango de destino.

Los parámetros de búsqueda de tokens se aplican a casos en los que un valor no es una string arbitraria, sino una entidad en un sistema de nombres. La coincidencia de string en un parámetro de token es exacta.

La mayoría de las búsquedas de tokens se aplican a tipos de datos complejos que contienen una system que es un URI que indica el sistema de nombres del que se toma el valor code. Estas búsquedas admiten las siguientes sintaxis de valor:

  • [parameter]=[code] coincide con el valor code independientemente de system.
  • [parameter]=[system]|[code] debe coincidir con el system y el code especificados.
  • [parameter]=|[code] coincide con code cuando el valor system está vacío
  • [parameter]=[system]| coincide con cualquier code con el valor de system determinado

Hay varios modificadores que activan la función de búsqueda de tokens alternativos:

  • :not anula las condiciones de coincidencia de una búsqueda de token.
  • :text realiza una búsqueda de string (no una coincidencia exacta) en el campo text o display asociado con el código, en lugar del valor de código en sí.
  • :above toma un parámetro solo con el formato [system]|[code] y hace coincidir los recursos en los que el código del recurso incluye al parámetro de consulta. Para usar este modificador, el system especificado debe existir en el almacén de FHIR como un recurso de CodeSystem.
  • :below es como :above, pero coincide si el parámetro de búsqueda incluye el código del recurso.
  • :in toma un solo parámetro mediante el uso de la sintaxis del parámetro de referencia, por ejemplo code:in=ValueSet/1234. La referencia debe hacer referencia a un recurso ValueSet dentro del mismo almacén de FHIR. El modificador coincide con cualquier código que esté en el ValueSet al que se hace referencia.
  • :not-in anula las condiciones de :in.

Las búsquedas de tokens también se aplican a los campos booleanos y de URI, y a ciertos campos de string en los que solo se permite la coincidencia exacta. En estos casos, el único formato de parámetro es [parameter]=[value].

Busca valores faltantes

El modificador de búsqueda :missing se puede usar en cualquier parámetro de búsqueda para hacer coincidir en función de la presencia o ausencia de cualquier valor en el campo especificado. Por ejemplo, Patient?gender=unknown coincide con los recursos que contienen de forma explícita el valor de enumeración unknown para el género, pero como este campo no es obligatorio, puede haber otros recursos que no propaguen el campo en todo. Estos recursos pueden coincidir con Patient?gender:missing=true. Por el contrario, Patient?gender:missing=false coincide con cualquier recurso que propague de forma explícita este campo.

El parámetro de búsqueda especial _content realiza una coincidencia de texto en campos basados en strings (sin incluir los campos de número, fecha o enumeración) si el campo es el destino de cualquier parámetro de búsqueda en el recurso. De forma predeterminada, coincide con los recursos que contienen todas las palabras en la consulta y admite operadores adicionales:

  • | es el operador OR, por ejemplo, abc | def | ghi xyz coincidirá con un recurso que contenga xyz y uno o más que contenga abc def ghi.
  • - es el operador NOT, por ejemplo, abc -def coincidirá con un recurso que contenga abc, pero no def.

La coincidencia se basa en palabras completas y no coincide con substrings ni caracteres no alfanuméricos. No importa el orden de las palabras. Las palabras que coinciden se pueden distribuir en varios campos del recurso.

El parámetro _text realiza el mismo tipo de coincidencia solo en el campo Texto que tiene un resumen legible del contenido del recurso. La API de Cloud Healthcare no genera automáticamente este resumen, sino que admite el parámetro de búsqueda de _text si el cliente propagó estos datos cuando creó o actualizó el recurso.

Parámetros de búsqueda compuestos

Cuando se buscan con varios parámetros de búsqueda, hay casos en los que los parámetros de búsqueda individuales combinados con AND coincidirían con resultados no deseados. Los parámetros de búsqueda compuestos son un tipo especial de parámetro de búsqueda que aborda este problema.

Por ejemplo, el recurso Observation puede contener varios valores en el campo component, cada uno de los cuales contiene un par de code y value. Una búsquedaObservation?component-code=8867-4&component-value-quantity=lt50 coincidiría con un recurso que tuviera un componente que contenga una code de 8867-4 y un componente diferente que contiene un value inferior a 50. Esta búsqueda no se puede usar para restringir una coincidencia de estos dos valores dentro del mismo componente.

Los parámetros de búsqueda compuestos definen un nuevo parámetro que combina otros dos parámetros de búsqueda y define un nivel de anidación dentro del cual ambos deben coincidir. En la consulta, los dos valores se unen con $. Por ejemplo, Observation tiene un parámetro compuesto component-code-value-quantity que puede restringir el ejemplo anterior a un solo componente mediante la búsqueda en Observation?component-code-value-quantity=8867-4$lt50. La especificación de FHIR define estos parámetros y no existen para todas las combinaciones de parámetros de búsqueda.

Los parámetros de búsqueda compuestos no permiten modificadores.

Al igual que con todos los parámetros de búsqueda, la información sobre los parámetros compuestos compatibles con la API de Cloud Healthcare se puede encontrar en la declaración de capacidad o en la Declaración de conformidad de FHIR.

Una búsqueda en cadena permite una búsqueda para recorrer referencias dentro del contexto de una consulta. A continuación, se muestra la sintaxis básica de una búsqueda en cadena:

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

Si el parámetro de referencia solo hace referencia a un tipo de recurso, se puede omitir :[resource type], lo que genera lo siguiente:

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

Por ejemplo, Observation tiene un parámetro de búsqueda de referencia subject que puede apuntar a un Group, un Device, un Patient o una Location. Para encontrar Observations que tengan como subject un Patient cuyo nombre comience con "Joe", puedes buscar Observation?subject:Patient.name=Joe.

Si la consulta tiene varios parámetros encadenados, cada cadena se evalúa por separado. Por ejemplo, Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada coincidiría con una Patient que tenía dos referencias de general-practitioner, una llamada “Joe” y la otra con una dirección en Canadá. No hay una sintaxis para agrupar estas cláusulas a fin de que coincidan solo con Joe de Canadá.

La API de Cloud Healthcare admite búsquedas en cadena de un solo nivel. No puedes realizar una búsqueda en cadena con más de un nivel de encadenamiento.

Una búsqueda en cadena inversa coincide con los recursos en función de los criterios en otros recursos que hacen referencia a ellos. La sintaxis para una búsqueda en cadena inversa es la siguiente:

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

Por ejemplo, el recurso Appointment tiene un parámetro de búsqueda patient que hace referencia a un recurso de Patient. Para encontrar todos los recursos de Patient a los que hace referencia un recurso de Appointment con una fecha de 2020-04-01, usa Patient?_has:Appointment:patient:date=eq2020-04-01.

Las cadenas invertidas pueden ser recurrentes, por ejemplo, Practitioner?_has:Encounter:practitioner:_has:Claim:encounter:created=eq2020-04-01 coincidiría con una Practitioner P si hay una Encounter E y una Claim C tal que C tenga una fecha creada de 2020-04-01, C se refiere a E a través de su referencia de encounter y E se refiere a P a través de su referencia de practitioner.

Incluye recursos adicionales en los resultados de la búsqueda

Los parámetros _include y _revinclude solicitan que los resultados de la búsqueda incluyan recursos adicionales (“recursos incluidos”) relacionados con los recursos que coinciden directamente con la consulta (“resultados principales”). El uso de estos parámetros es más eficiente que realizar una serie de solicitudes para recuperar estos recursos adicionales por separado. En el paquete searchset que se muestra en la búsqueda, los recursos que agregan estos parámetros se marcan con entry.search.mode = include para distinguirlos de los resultados principales que tendrán entry.search.mode = match.

La inclusión directa con _include agrega recursos y versiones de recursos a los que hacen referencia los resultados principales, y la inclusión inversa con _revinclude agrega recursos que hacen referencia a los resultados principales. La referencia que se sigue se especifica por el nombre de un parámetro de búsqueda y solo los campos de referencia que están disponibles como parámetros de búsqueda se pueden usar de esta manera.

Los formatos de los parámetros para _include y _revinclude son los mismos, y toman dos o tres valores delimitados por :. El primer valor es el tipo de recurso del que proviene la referencia, el segundo valor es el nombre del parámetro de búsqueda y el tercer valor opcional limita el tipo de recurso a un solo tipo en los casos en los que la referencia puede apuntar a más de un tipo.

Por ejemplo:

  • MedicationRequest?_include=MedicationRequest:subject busca en recursos MedicationRequest y, para cada recurso que se muestra, también se muestra el objetivo de la referencia subject, que puede ser Group o Patient, según se define en la especificación FHIR.
  • MedicationRequest?_include=MedicationRequest:subject:Patient es similar, pero solo muestra referencias subject a los recursos de Patient.
  • MedicationRequest?_revinclude=Provenance:target busca en recursos MedicationRequest y para cada recurso que se muestra, también se muestra cualquiera de los recursos Provenance en los que la referencia target en Provenance se refiere al recurso coincidente.

El modificador :iterate hace que una _include se evalúe de forma iterativa. Este modificador puede seguir una capa adicional de referencias de los resultados incluidos o seguir estructuras recurrentes como Observation:derived-from que se refiere a otra Observation. La profundidad de la recurrencia es limitada.

Por ejemplo:

  • Observation?_include:iterate=Observation:derived-from:Observation busca en recursos Observation y sigue la referencia derivada de los recursos Observation coincidentes y, luego, de los recursos incluidos, y así sucesivamente.
  • MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agent buscará en MedicationRequest, incluirá recursos Provenance con un target que esté en este conjunto de resultados y, luego, incluirá recursos a los que se hace referencia a través del parámetro agent de esos recursos Provenance.

Un comodín, *, indica que se deben incluir todas las referencias disponibles como parámetros de búsqueda. Puedes usar la tarjeta comodín * como primer y único argumento en _include o en lugar del nombre del parámetro de búsqueda del _include estándar, en el que el tercer valor opcional es opcional limita el tipo de recurso a un solo tipo, como en el comportamiento original.

Por ejemplo:

  • Observation?_include=* busca en recursos Observation y para cada recurso también se muestran todos los recursos a los que se hace referencia.
  • Observation?_include=Observation:* es equivalente a la anterior.
  • MedicationRequest?_include=MedicationRequest:*:Patient muestra todas las referencias a los recursos Patient para cada recurso MedicationRequest.

Se anularán los duplicados de los recursos incluidos para que solo se muestre una copia de un recurso en una página de resultados, incluso si se encuentra a través de varias referencias. Se mostrará el mismo recurso incluido en cada página de resultados donde resultado principal se relacione a él.

Limita los campos que se muestran en los resultados de la búsqueda

El parámetro _elements permite que el cliente solicite que solo se muestre un subconjunto de campos para cada resultado de la búsqueda a fin de reducir el tamaño de la respuesta si omite datos innecesarios. El parámetro acepta una lista separada por comas de nombres de elementos base en el recurso, por ejemplo Patient?_elements=identifier,contact,link. Solo estos campos y sus elementos secundarios se incluirán en los recursos que se muestran. Los recursos de la respuesta que este parámetro alteró contendrá un valor meta.tag de SUBSETTED para indicar que están incompletos.

La API de Cloud Healthcare tiene compatibilidad limitada con el parámetro _summary, que proporciona subconjuntos predefinidos de campos de recursos de manera similar a _elements:

  • _summary=text solo muestra los campos de nivel superior text, id y meta.
  • _summary=data quita el campo text y muestra todos los otros campos