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ê através de alguns aspectos importantes 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, demonstraremos 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. No caso do serviço do serviço FHIR nos Serviços de Dados de Saúde do Azure, essa URL seria 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 efetuar pull de todos os recursos Patient no banco de dados, poderá usar a seguinte solicitação:
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 POST ou GET, se a solicitação de pesquisa for bem-sucedida, você receberá um pacote searchset FHIR 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, abordaremos os vários aspectos dos recursos de consulta 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
Quando você faz uma pesquisa no FHIR, você está pesquisando no banco de dados por recursos que correspondem a determinados critérios de pesquisa. 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 que contém as instâncias de recurso cujos elementos atenderam aos critérios de pesquisa.
Para cada parâmetro de pesquisa, a especificação FHIR define os tipos de dados que podem ser usados. Veja abaixo o suporte no serviço FHIR para os vários tipos de dados.
| Pesquisar tipo de parâmetro | Serviço FHIR nos Serviços de Dados de Saúde do Azure | API do Azure para FHIR | Comentário |
|---|---|---|---|
| número | Sim | Yes | |
| date | Sim | Sim | |
| string | Sim | Yes | |
| token | Sim | Yes | |
| reference | Sim | Yes | |
| composto | Parcial | Parcial | A lista de tipos compostos com suporte é fornecida posteriormente neste artigo. |
| quantity | Sim | Yes | |
| uri | Sim | Yes | |
| especial | Não | Não |
Parâmetros de pesquisa comum
Há parâmetros de pesquisa comuns que se aplicam a todos os recursos no FHIR. Eles estão listados abaixo, juntamente com o suporte no serviço FHIR:
| Parâmetro de pesquisa comum | Serviço FHIR nos Serviços de Dados de Saúde do Azure | API do Azure para FHIR | Comentário |
|---|---|---|---|
_id |
Sim | Sim | |
_lastUpdated |
Sim | Sim | |
_tag |
Sim | Sim | |
_type |
Sim | Sim | |
_security |
Sim | Sim | |
_profile |
Sim | Sim | |
_has |
Sim | Sim | |
_query |
Não | No | |
_filter |
No | No | |
_list |
No | No | |
_text |
No | No | |
_content |
No | Não |
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 suportados estão listados nos links abaixo:
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.
Observação
O serviço FHIR nos Serviços de Dados de Saúde do Azure não indexa automaticamente parâmetros de pesquisa que não estão definidos na especificação FHIR base. No entanto, o serviço FHIR dá suporte a parâmetros de pesquisa personalizados.
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). Você não iria querer o retorno de uma correspondência positiva em uma observação com o código de altura e um comprimento de braço a braço acima de 60 polegadas, por exemplo. 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 Saúde do Azure dá suporte aos seguintes emparelhamentos 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.
Observação
Os parâmetros de pesquisa compostos não dão suporte a modificadores, de acordo com a especificação FHIR.
Modificadores & prefixos
Os modificadores permitem que você qualifique os parâmetros de pesquisa com condições adicionais. Abaixo está uma lista de modificadores FHIR e o suporte deles no serviço FHIR:
| Modificadores | Serviço FHIR nos Serviços de Dados de Saúde do Azure | API do Azure para FHIR | Comentário |
|---|---|---|---|
:missing |
Sim | Sim | |
:exact |
Sim | Sim | |
:contains |
Sim | Sim | |
:text |
Sim | Yes | |
:type (referência) |
Sim | Sim | |
:not |
Sim | Yes | |
:below (uri) |
Sim | Yes | |
:above (uri) |
Sim | Yes | |
:in (token) |
Não | Não | |
:below (token) |
Não | Não | |
:above (token) |
Não | Não | |
:not-in (token) |
Não | Não |
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 informações detalhadas sobre como usar os parâmetros de resultado de pesquisa no FHIR, confira o site da HL7. Veja abaixo uma lista de parâmetros de resultado de pesquisa do FHIR e seu suporte no serviço FHIR.
| Parâmetros de resultado de pesquisa | Serviço FHIR nos Serviços de Dados de Saúde do Azure | API do Azure para FHIR | Comentário |
|---|---|---|---|
_elements |
Sim | Sim | |
_count |
Sim | Yes | _count é limitado a 1000 recursos. Se ele estiver definido acima de 1000, apenas 1000 serão retornados e um aviso será incluído no pacote. |
_include |
Sim | Yes | Os itens recuperados com _include são limitados a 100. _include no PaaS e no OSS no Azure Cosmos DB não dá suporte a :iterate(nº 2137). |
_revinclude |
Sim | Yes | Os itens recuperados com _revinclude são limitados a 100. _revinclude no PaaS e no OSS no Azure Cosmos DB não dá suporte a :iterate(nº 2137). Há também um código de status incorreto para uma solicitação incorreta nº 1319. |
_summary |
Sim | Sim | |
_total |
Parcial | Parcial | _total=none e _total=accurate |
_sort |
Parcial | Parcial | sort=_lastUpdated tem suporte no serviço FHIR. Para o serviço FHIR e os servidores FHIR do BD SQL de software de código aberto, há suporte para classificação por cadeias de caracteres e campos dateTime. Para bancos de dados da API do Azure para FHIR e Azure Cosmos DB de software de código aberto criados após 20 de abril de 2021, há suporte para classificação em nome, sobrenome, data de nascimento e clínica. |
_contained |
Não | No | |
_containedType |
No | No | |
_score |
No | Não |
Observação:
- Por padrão,
_sortorganiza 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. - O serviço FHIR suporta pesquisas curinga com revinclude. Adicionando o parâmetro de consulta "." na consulta revinclude, ele 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.
Encadeado & pesquisa 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
. na solicitação acima direciona o caminho da pesquisa encadeada para o parâmetro de destino (name nesse 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 acima, os resultados de uma pesquisa FHIR estão disponíveis em forma paginada 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. A busca repetida 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.
FHIR® é uma marca registrada da HL7 e é usado com a permissão da HL7.