Definindo parâmetros de pesquisa personalizados

Artigo
03/18/2023

A especificação FHIR define um conjunto de parâmetros de pesquisa que se aplicam a todos os recursos. Além disso, o FHIR define muitos parâmetros de pesquisa específicos para determinados recursos. No entanto, há cenários em que talvez você queira pesquisar em um elemento em um recurso que não é definido pela especificação FHIR como um parâmetro de pesquisa padrão. Este artigo descreve como você pode definir seus próprios parâmetros de pesquisa personalizados para uso no serviço FHIR nos Serviços de Dados de Integridade do Azure.

Observação

Sempre que criar, atualizar ou excluir um parâmetro de pesquisa, você precisará executar um trabalho de reindexação para habilitar o parâmetro de pesquisa para produção dinâmica. Abaixo, descreveremos como você pode testar parâmetros de pesquisa antes de reindexar todo o banco de dados do serviço FHIR.

Criar novo parâmetro de pesquisa

Para criar um novo parâmetro de pesquisa, você precisa POST de um SearchParameter recurso para o banco de dados de serviço FHIR.

POST {{FHIR_URL}}/SearchParameter

Os exemplos abaixo demonstram a criação de um novo parâmetro de pesquisa personalizado

Criar um novo parâmetro de pesquisa por definição no Guia de Implementação

O exemplo de código abaixo mostra como adicionar o parâmetro de pesquisa US Core Race ao Patient tipo de recurso em seu banco de dados de serviço 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"
}

Criar um novo parâmetro de pesquisa para atributos de recurso com o tipo de referência

O exemplo de código mostra como criar um parâmetro de pesquisa personalizado para pesquisar recursos do MedicationDispense com base no local em que eles foram dispensados. Este é um exemplo de adição de parâmetro de pesquisa personalizado para um tipo de Referência.

{
 "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"
}

Observação

O novo parâmetro de pesquisa aparecerá na instrução capability do serviço FHIR após o POST parâmetro de pesquisa para o banco de dados e reindexar o banco de dados. Exibir o SearchParameter na instrução capability é a única maneira de saber se há suporte para um parâmetro de pesquisa em seu serviço FHIR. Se você não encontrar o SearchParameter na instrução capability, ainda precisará reindexar o banco de dados para ativar o parâmetro de pesquisa. Você pode POST vários parâmetros de pesquisa antes de disparar uma operação de reindexação.

Elementos importantes de um SearchParameter recurso:

url: uma chave exclusiva para descrever o parâmetro de pesquisa. Organizações como a HL7 usam um formato de URL padrão para os parâmetros de pesquisa que definem, conforme mostrado acima no parâmetro de pesquisa Us Core Race.
code: o valor armazenado no elemento de código é o nome usado para o parâmetro de pesquisa quando ele é incluído em uma chamada à API. Para o exemplo acima com a extensão "US Core Race", você pesquisaria com GET {{FHIR_URL}}/Patient?race=<code> onde <code> está no valor definido do sistema de codificação especificado. Essa chamada recuperaria todos os pacientes de uma determinada raça.
base: descreve a quais tipos de recurso o parâmetro de pesquisa se aplica. Se o parâmetro de pesquisa se aplicar a todos os recursos, você poderá usar Resource; caso contrário, você poderá listar todos os tipos de recursos relevantes.
target: descreve a quais tipos de recurso o parâmetro de pesquisa corresponde.
type: descreve o tipo de dados para o parâmetro de pesquisa. O tipo é limitado pelo suporte para tipos de dados no serviço FHIR. Isso significa que você não pode definir um parâmetro de pesquisa do tipo Especial ou definir um parâmetro de pesquisa composto , a menos que seja uma combinação com suporte.
expression: descreve como calcular o valor da pesquisa. Ao descrever um parâmetro de pesquisa, você deve incluir a expressão, mesmo que ela não seja exigida pela especificação. Isso ocorre porque você precisa da expressão ou da sintaxe xpath e o serviço FHIR ignora a sintaxe xpath.

Testar novos parâmetros de pesquisa

Embora você não possa usar os novos parâmetros de pesquisa em produção até executar um trabalho de reindexação, há algumas maneiras de testar seus parâmetros de pesquisa personalizados antes de reindexar todo o banco de dados.

Primeiro, você pode testar um novo parâmetro de pesquisa para ver quais valores serão retornados. Ao executar o comando abaixo em uma instância de recurso específica (fornecendo a ID do recurso), você obtém de volta uma lista de pares de valores com o nome do parâmetro de pesquisa e o valor armazenado no elemento correspondente. Essa lista inclui todos os parâmetros de pesquisa para o recurso. Você pode rolar para localizar o parâmetro de pesquisa criado. A execução desse comando não alterará nenhum comportamento no serviço FHIR.

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

Por exemplo, para localizar todos os parâmetros de pesquisa para um paciente:

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

O resultado será semelhante a este:

{
  "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"
    }
    ]
    ...}

Depois de ver que o parâmetro de pesquisa está sendo exibido conforme o esperado, você pode reindexar um único recurso para testar a pesquisa com o novo parâmetro de pesquisa. Para reindexar um único recurso:

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

A execução dessa POST chamada define os índices de todos os parâmetros de pesquisa definidos para a instância de recurso especificada na solicitação. Essa chamada faz uma alteração no banco de dados do serviço FHIR. Agora você pode pesquisar e definir o x-ms-use-partial-indices cabeçalho como true, o que faz com que o serviço FHIR retorne resultados para qualquer um dos recursos que têm o parâmetro de pesquisa indexado, mesmo que nem todas as instâncias de recurso desse tipo o tenham indexado.

Continuando com nosso exemplo, você pode indexar um paciente para habilitar SearchParameter:

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

E, em seguida, fazer uma pesquisa de teste

Para o paciente por raça:

GET {{FHIR_URL}}/Patient?race=2028-9
x-ms-use-partial-indices: true

Para Localização (tipo de referência):

{{fhirurl}}/MedicationDispense?location=<locationid referenced in MedicationDispense Resource>
x-ms-use-partial-indices: true

Depois de testar o novo parâmetro de pesquisa e confirmar que ele está funcionando conforme o esperado, execute ou agende seu trabalho de reindexação para que os novos parâmetros de pesquisa possam ser usados na produção dinâmica.

Consulte Executando um trabalho de reindexação para obter informações sobre como reindexar seu banco de dados de serviço FHIR.

Atualizar um parâmetro de pesquisa

Para atualizar um parâmetro de pesquisa, use PUT para criar uma nova versão do parâmetro de pesquisa. Você deve incluir a ID do id parâmetro de pesquisa no campo no corpo da solicitação PUT , bem como a cadeia de caracteres de PUT solicitação.

Observação

Se você não souber a ID do parâmetro de pesquisa, poderá pesquisá-la usando GET {{FHIR_URL}}/SearchParameter. Isso retornará todos os parâmetros de pesquisa personalizados, bem como padrão, e você poderá percorrer a lista para localizar o parâmetro de pesquisa necessário. Você também pode limitar a pesquisa por nome. Conforme mostrado na solicitação de exemplo abaixo, o nome da instância de recurso personalizado SearchParameter é USCoreRace. Você pode pesquisar esse SearchParameter recurso pelo nome usando 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"
}

O resultado da solicitação acima será um recurso atualizado SearchParameter .

Aviso

Tenha cuidado ao atualizar parâmetros de pesquisa. Alterar um parâmetro de pesquisa existente pode ter impactos no comportamento esperado. É recomendável executar um trabalho de reindexação imediatamente.

Excluir um parâmetro de pesquisa

Se você precisar excluir um parâmetro de pesquisa, use o seguinte:

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

Aviso

Tenha cuidado ao excluir parâmetros de pesquisa. A exclusão de um parâmetro de pesquisa existente pode ter impactos no comportamento esperado. É recomendável executar um trabalho de reindexação imediatamente.

Próximas etapas

Neste artigo, você aprendeu a criar um parâmetro de pesquisa personalizado. Em seguida, você pode aprender a reindexar seu banco de dados de serviço FHIR. Para obter mais informações, consulte

Como executar um trabalho de reindexação

FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.

Definindo parâmetros de pesquisa personalizados

Criar novo parâmetro de pesquisa

Criar um novo parâmetro de pesquisa por definição no Guia de Implementação

Criar um novo parâmetro de pesquisa para atributos de recurso com o tipo de referência

Testar novos parâmetros de pesquisa

Atualizar um parâmetro de pesquisa

Excluir um parâmetro de pesquisa

Próximas etapas

Recursos adicionais