Pesquisa da visão geral da FHIR

A especificação FHIR® (Fast Healthcare Interoperability Resources) define uma API para consultar recursos em um banco de dados do servidor FHIR. Este artigo orienta você pelos principais aspectos da consulta de dados no FHIR. Para obter detalhes completos sobre a API de pesquisa do FHIR, confira a documentação da Pesquisa sobre FHIR da HL7.

Ao longo deste artigo, demonstramos a sintaxe de pesquisa FHIR em chamadas de API de exemplo com o espaço reservado {{FHIR_URL}} para representar a URL do servidor FHIR. Se o serviço FHIR estiver nos Serviços de Dados de Integridade do Azure, essa URL será https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.

As pesquisas FHIR podem ser feitas em um tipo de recurso específico, em um compartimento especificado ou em todos os recursos no banco de dados do servidor FHIR. A maneira mais simples de executar uma pesquisa no FHIR é usar uma solicitação GET. Por exemplo, se você quiser extrair todos os Patient recursos no banco de dados, poderá usar a solicitação a seguir.

GET {{FHIR_URL}}/Patient

Você também pode pesquisar usando POST. Para pesquisar usando POST, os parâmetros de pesquisa são entregues no corpo da solicitação. Isso facilita o envio de consultas com uma série mais longa e complexa de parâmetros.

Com ou POST GET, se a solicitação de pesquisa for bem-sucedida, você receberá um pacote FHIR searchset contendo as instâncias de recurso retornadas da pesquisa. Se a pesquisa falhar, você encontrará os detalhes do erro em uma resposta OperationOutcome.

Nas seções a seguir, abordamos os vários aspectos da consulta de recursos no FHIR. Depois de examinar esses tópicos, confira a página de exemplos de pesquisa do FHIR, que apresenta exemplos de diferentes métodos de pesquisa FHIR.

Parâmetros de pesquisa

Ao fazer uma pesquisa no FHIR, você está pesquisando no banco de dados recursos que correspondam a determinados critérios. A API de FHIR especifica um conjunto avançado de parâmetros de pesquisa para critérios de pesquisa de ajuste fino. Cada recurso no FHIR carrega informações como um conjunto de elementos, e os parâmetros de pesquisa funcionam para consultar as informações nesses elementos. Em uma chamada à API de pesquisa FHIR, se uma correspondência positiva for encontrada entre os parâmetros de pesquisa da solicitação e os valores de elemento correspondentes armazenados em uma instância de recurso, o servidor FHIR retornará um pacote contendo as instâncias de recurso cujos elementos atenderam aos critérios de pesquisa.

Para cada parâmetro de pesquisa, a especificação FHIR define o tipo de dados que pode ser usado. Veja abaixo o suporte no serviço FHIR para os vários tipos de dados.

Parâmetros de pesquisa comum

Há parâmetros de pesquisa comuns que se aplicam a todos os recursos no FHIR. Estes estão listados a seguir, juntamente com seu apoio no serviço FHIR.

Parâmetros específicos ao recurso

O serviço FHIR nos Serviços de Dados de Saúde do Azure dá suporte a quase todos os parâmetros de pesquisa específicos aos recursos definidos na especificação FHIR. Os parâmetros de pesquisa que não são compatíveis estão listados nos links abaixo:

• Parâmetros de pesquisa STU3 sem suporte

• Parâmetros de pesquisa R4 sem suporte

Você também pode ver o suporte atual para parâmetros de pesquisa na Instrução de Funcionalidade FHIR com a seguinte solicitação:

GET {{FHIR_URL}}/metadata

Para exibir os parâmetros de pesquisa com suporte na instrução de funcionalidade, navegue até CapabilityStatement.rest.resource.searchParam para obter os parâmetros de pesquisa específicos ao recurso e até CapabilityStatement.rest.searchParam para obter os parâmetros de pesquisa que se aplicam a todos os recursos.

Parâmetros de pesquisa compostos

As pesquisas compostas no FHIR permitem que você pesquise em pares de elementos como unidades logicamente conectadas. Por exemplo, se você estivesse procurando observações em que a altura do paciente fosse superior a 60 polegadas, teria que ter certeza de que uma única propriedade da observação continha o código de altura e um valor maior do que 60 polegadas (o valor só deve pertencer à altura). Por exemplo, você não gostaria de uma correspondência positiva em uma observação com o código de altura e um código de comprimento de braço acima de 60 polegadas. Os parâmetros de pesquisa compostos impedem esse problema pesquisando em pares pré-especificados de elementos cujos valores devem atender aos critérios de pesquisa para que uma correspondência positiva ocorra.

O serviço FHIR nos Serviços de Dados de Integridade do Azure dá suporte aos seguintes pares de tipo de parâmetro de pesquisa para pesquisas compostas.

• Referência, Token
• Token, Data
• Token, Número, Número
• Token, Quantidade
• Token, Cadeia de caracteres
• Token, Token

Para saber mais, confira a documentação sobre Parâmetros de pesquisa compostos da HL7.

Modificadores e prefixos

Os modificadores permitem que você qualifique os parâmetros de pesquisa com condições adicionais. Abaixo está uma tabela de modificadores FHIR e seu suporte no serviço FHIR.

Para parâmetros de pesquisa que têm uma ordem específica (números, datas e quantidades), você pode usar um prefixo antes do valor do parâmetro para refinar os critérios de pesquisa (por exemplo, Patient?_lastUpdated=gt2022-08-01 onde o prefixo gt significa "maior que"). O serviço FHIR nos Serviços de Dados de Saúde do Azure dá suporte a todos os prefixos definidos no padrão FHIR.

Parâmetros de resultado de pesquisa

FHIR especifica um conjunto de parâmetros de resultado de pesquisa para ajudar a gerenciar as informações retornadas de uma pesquisa. Para obter detalhes sobre como usar parâmetros de resultado de pesquisa no FHIR, consulte o site do HL7 . A seguir está uma tabela de parâmetros de resultado de pesquisa FHIR e seu suporte no serviço FHIR.

Observação:

1. Por padrão, _sort organiza os registros em ordem crescente. Você também pode usar o prefixo - para classificar em ordem decrescente. O serviço FHIR só permite que você classifique em um único campo de cada vez.
2. O serviço FHIR oferece suporte a pesquisas de curinga com revinclude. Adicionar um parâmetro de consulta "." em uma consulta revinclude direciona o serviço FHIR para fazer referência a todos os recursos mapeados para o recurso de origem.

Por padrão, o serviço FHIR nos Serviços de Dados de Saúde do Azure é definido como manipulação branda. Isso significa que o servidor ignora quaisquer parâmetros desconhecidos ou sem suporte. Se você quiser usar a manipulação estrita, poderá incluir o cabeçalho Prefer e definir handling=strict.

Busca encadeada e encadeada reversa

Uma pesquisa encadeada permite que você execute consultas com alvo preciso para recursos que tenham uma referência a outro recurso. Por exemplo, se você quiser achar encontros em que o nome da paciente é Jane, use:

GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane

O . na solicitação anterior direciona o caminho da pesquisa encadeada para o parâmetro de destino (name neste caso).

Da mesma forma, você pode fazer uma pesquisa encadeada reversa com o parâmetro _has. Isso permite que você recupere instâncias de recurso especificando critérios em outros recursos que fazem referência aos recursos de interesse. Para obter exemplos de pesquisa encadeada e encadeada reversa, confira a página de exemplos de pesquisa do FHIR.

Paginação

Como mencionado anteriormente, os resultados de uma pesquisa FHIR estão disponíveis em formato paginado em um link fornecido no searchset pacote. Por padrão, o serviço FHIR exibe 10 resultados de pesquisa por página, mas isso pode ser aumentado (ou diminuído) definindo o _count parâmetro. Se houver mais correspondências do que cabem em uma página, o pacote incluirá um next link. Buscar repetidamente no next link produz as páginas subsequentes de resultados. Observe que o valor do _count parâmetro não pode exceder 1000.

Atualmente, o serviço FHIR nos Serviços de Dados de Saúde do Azure dá suporte apenas ao link next e não dá suporte aos links first, last ou previous em pacotes retornados de uma pesquisa.

Próximas etapas

Agora que você aprendeu sobre os conceitos básicos da pesquisa FHIR, confira a página de exemplos de pesquisa para obter detalhes sobre como pesquisar usando parâmetros de pesquisa, modificadores e outros métodos de pesquisa FHIR.