Definición de parámetros de búsqueda personalizados

  • Artículo

La especificación FHIR define un conjunto de parámetros de búsqueda que se aplican a todos los recursos. Además, FHIR define muchos parámetros de búsqueda específicos de determinados recursos. Sin embargo, hay escenarios en los que es posible que quiera buscar en un elemento de un recurso que no esté definido por la especificación de FHIR como parámetro de búsqueda estándar. En este artículo se describe cómo definir sus propios parámetros de búsqueda personalizados para su uso en el servicio FHIR en Azure Health Data Services.

Nota:

Cada vez que cree, actualice o elimine un parámetro de búsqueda, deberá ejecutar un trabajo de reindexación para habilitar el parámetro de búsqueda para producción activa. A continuación se describe cómo probar los parámetros de búsqueda antes de volver a indexar toda la base de datos del servicio FHIR.

Creación de un parámetro de búsqueda

Para crear un nuevo parámetro de búsqueda, debe tener un SearchParameter recurso en POST la base de datos del servicio FHIR.

POST {{FHIR_URL}}/SearchParameter

En los ejemplos siguientes se muestra cómo crear un nuevo parámetro de búsqueda personalizado

Creación de un nuevo parámetro de búsqueda por definición en la Guía de implementación

En el ejemplo de código siguiente se muestra cómo agregar el parámetro de búsqueda US Core Race al tipo de recurso en la Patient base de datos del servicio FHIR.

{
  "resourceType" : "SearchParameter",
  "id" : "us-core-race",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "Returns patients with a race extension matching the specified code.",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

Creación de un nuevo parámetro de búsqueda para atributos de recursos con tipo de referencia

En el ejemplo de código se muestra cómo crear un parámetro de búsqueda personalizado para buscar recursos MedicationDispense en función de la ubicación donde se dispensaron. Este es un ejemplo de cómo agregar un parámetro de búsqueda personalizado para un tipo de referencia.

{
 "resourceType": "SearchParameter",
  "id": "a3c28d46-fd06-49ca-aea7-5f9314ef0497",
  "url": "{{An absolute URI that is used to identify this search parameter}}",
  "version": "1.0",
  "name": "MedicationDispenseLocationSearchParameter",
  "status": "active",
  "description": "Search parameter for MedicationDispense by location",
  "code": "location",
  "base": ["MedicationDispense"],
  "target": ["Location"],
  "type": "reference",
  "expression": "MedicationDispense.location"
}

Nota:

El nuevo parámetro de búsqueda aparecerá en la instrucción de funcionalidad del servicio FHIR después de que POST el parámetro de búsqueda se realice en la base de datos y vuelva a indexar la base de datos. Ver en SearchParameter la instrucción de funcionalidad es la única manera de indicar si se admite un parámetro de búsqueda en el servicio FHIR. Si no encuentra en SearchParameter la instrucción capability, deberá volver a indexar la base de datos para activar el parámetro de búsqueda. Puede POST realizar varios parámetros de búsqueda antes de desencadenar una operación de reindexación.

Elementos importantes de un SearchParameter recurso:

  • url: clave única para describir el parámetro de búsqueda. Las organizaciones como HL7 usan un formato de dirección URL estándar para los parámetros de búsqueda que definen, tal como se muestra anteriormente en el parámetro de búsqueda US Core Race.

  • code: el valor almacenado en el elemento de código es el nombre que se usa para el parámetro de búsqueda cuando se incluye en una llamada API. Para el ejemplo anterior con la extensión "US Core Race", buscaría donde GET {{FHIR_URL}}/Patient?race=<code><code> se encuentra en el valor establecido desde el sistema de codificación especificado. Esta llamada recuperaría a todos los pacientes de una determinada raza.

  • base: describe a qué tipos de recursos se aplica el parámetro de búsqueda. Si el parámetro de búsqueda se aplica a todos los recursos, puede usar Resource; de lo contrario, puede enumerar todos los tipos de recursos pertinentes.

  • target: describe a qué tipos de recursos coincide el parámetro de búsqueda.

  • type: describe el tipo de datos para el parámetro de búsqueda. El tipo está limitado por la compatibilidad con los tipos de datos en el servicio FHIR. Esto significa que no se puede definir un parámetro de búsqueda de tipo Special o definir un parámetro de búsqueda compuesto a menos que sea una combinación admitida.

  • expression: describe cómo calcular el valor de la búsqueda. Al describir un parámetro de búsqueda, debe incluir la expresión, aunque la especificación no lo requiera. Esto se debe a que necesita la expresión o la sintaxis xpath y el servicio FHIR omite la sintaxis xpath.

Prueba de nuevos parámetros de búsqueda

Aunque no puede usar los nuevos parámetros de búsqueda en producción hasta que ejecute un trabajo de reindexación, hay algunas maneras de probar los parámetros de búsqueda personalizados antes de volver a indexar toda la base de datos.

En primer lugar, puede probar un nuevo parámetro de búsqueda para ver qué valores se devolverán. Al ejecutar el comando siguiente en una instancia de recurso específica (proporcionando el identificador de recurso), se obtiene una lista de pares de valores con el nombre del parámetro de búsqueda y el valor almacenado en el elemento correspondiente. Esta lista incluye todos los parámetros de búsqueda del recurso. Puede desplazarse por para buscar el parámetro de búsqueda que ha creado. La ejecución de este comando no cambiará ningún comportamiento en el servicio FHIR.

GET https://{{FHIR_URL}}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

Por ejemplo, para buscar todos los parámetros de búsqueda de un paciente, ejecute lo siguiente:

GET https://{{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

El resultado tiene el aspecto siguiente:

{
  "resourceType": "Parameters",
  "id": "8be24e78-b333-49da-a861-523491c3437a",
  "meta": {
    "versionId": "1"
  },
  "parameter": [
    {
      "name": "deceased",
      "valueString": "http://hl7.org/fhir/special-values|false"
    },
    {
      "name": "language",
      "valueString": "urn:ietf:bcp:47|en-US"
    },
    {
      "name": "race",
      "valueString": "2028-9"
    }
    ]
    ...}

Una vez que vea que el parámetro de búsqueda se muestra según lo previsto, puede volver a indexar un único recurso para probar la búsqueda con el nuevo parámetro de búsqueda. Para volver a indexar un único recurso:

POST https://{{FHIR_URL}/{{RESOURCE}}/{{RESOURCE_ID}}/$reindex

Al ejecutar esta llamada, POST se establecen los índices de los parámetros de búsqueda definidos para la instancia de recurso especificada en la solicitud. Esta llamada realiza un cambio en la base de datos del servicio FHIR. Ahora puede buscar y establecer el x-ms-use-partial-indices encabezado trueen , lo que hace que el servicio FHIR devuelva resultados para cualquiera de los recursos que tienen el parámetro de búsqueda indizado, incluso si no todas las instancias de recursos de ese tipo lo han indexado.

Siguiendo con nuestro ejemplo, podría indexar un paciente para habilitar SearchParameter:

POST {{FHIR_URL}}/Patient/{{PATIENT_ID}}/$reindex

Y, a continuación, realice una búsqueda de prueba.

  1. Para el paciente por raza:
GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true
  1. Para Ubicación (tipo de referencia):
{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Después de probar el nuevo parámetro de búsqueda y confirmar que funciona según lo previsto, ejecute o programe el trabajo de reindexación para que los nuevos parámetros de búsqueda se puedan usar en producción activa.

Consulte Ejecución de un trabajo de reindexación para obtener información sobre cómo volver a indexar la base de datos del servicio FHIR.

Actualización de un parámetro de búsqueda

Para actualizar un parámetro de búsqueda, use PUT para crear una versión del parámetro. Debe incluir el identificador del parámetro de búsqueda en el id campo en el cuerpo de la PUT solicitud, así como la cadena de PUT solicitud.

Nota:

Si no conoce el identificador del parámetro de búsqueda, puede buscarlo mediante GET {{FHIR_URL}}/SearchParameter. Esto devolverá todos los parámetros de búsqueda personalizados, así como los parámetros de búsqueda estándar, y puede desplazarse por la lista para encontrar el parámetro de búsqueda que necesita. También puede limitar la búsqueda por nombre. Como se muestra en la solicitud de ejemplo siguiente, el nombre de la instancia de recurso personalizado SearchParameter es USCoreRace. Puede buscar este SearchParameter recurso por su nombre mediante GET {{FHIR_URL}}/SearchParameter?name=USCoreRace.

PUT {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

{
  "resourceType" : "SearchParameter",
  "id" : "{{SearchParameter_ID}}",
  "url" : "http://hl7.org/fhir/us/core/SearchParameter/us-core-race",
  "version" : "3.1.1",
  "name" : "USCoreRace",
  "status" : "active",
  "date" : "2019-05-21",
  "publisher" : "US Realm Steering Committee",
  "contact" : [
    {
      "telecom" : [
        {
          "system" : "other",
          "value" : "http://www.healthit.gov/"
        }
      ]
    }
  ],
  "description" : "New Description!",
  "jurisdiction" : [
    {
      "coding" : [
        {
          "system" : "urn:iso:std:iso:3166",
          "code" : "US",
          "display" : "United States of America"
        }
      ]
    }
  ],
  "code" : "race",
  "base" : [
    "Patient"
  ],
  "type" : "token",
  "expression" : "Patient.extension.where(url = 'http://hl7.org/fhir/us/core/StructureDefinition/us-core-race').extension.value.code"
}

El resultado de la solicitud anterior será un recurso actualizado SearchParameter .

Advertencia

Tenga cuidado al actualizar los parámetros de búsqueda. Cambiar un parámetro de búsqueda existente podría afectar al comportamiento esperado. Se recomienda ejecutar un trabajo de reindexación inmediatamente.

Eliminación de un parámetro de búsqueda

Si necesita eliminar un parámetro de búsqueda, use lo siguiente:

DELETE {{FHIR_URL}}/SearchParameter/{{SearchParameter_ID}}

Advertencia

Tenga cuidado al eliminar parámetros de búsqueda. La eliminación de un parámetro de búsqueda existente podría afectar al comportamiento esperado. Se recomienda ejecutar un trabajo de reindexación inmediatamente.

Pasos siguientes

En este artículo, ha aprendido a crear un parámetro de búsqueda personalizado. A continuación, puede aprender a volver a indexar la base de datos del servicio FHIR. Para obtener más información, vea

Procedimientos para ejecutar un trabajo de reindexación

FHIR® es una marca registrada de HL7 y se usa con su permiso.