Visão geral da pesquisa FHIR
A especificação Fast Healthcare Interoperability Resources (FHIR)® define uma API para consultar recursos em um banco de dados de servidor FHIR. Este artigo orienta você pelos principais aspetos da consulta de dados no FHIR. Para obter detalhes completos sobre a API de pesquisa FHIR, consulte a documentação da Pesquisa FHIR 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 Saúde do Azure, essa URL será https://<WORKSPACE-NAME>-<FHIR-SERVICE-NAME>.fhir.azurehealthcareapis.com.
As pesquisas FHIR podem ser em relação a um tipo de recurso específico, um compartimento especificado ou todos os recursos no banco de dados do servidor FHIR. A maneira mais simples de executar uma pesquisa no FHIR é usar uma GET solicitação. Por exemplo, se você quiser extrair todos os Patient recursos no banco de dados, você pode usar a seguinte solicitação.
GET {{FHIR_URL}}/Patient
Você também pode pesquisar usando POSTo . Para pesquisar usando POSTo , os parâmetros de pesquisa são entregues no corpo da solicitação. Isso facilita o envio de consultas com séries de parâmetros mais longas e complexas.
Com um ou POST GET, se a solicitação de pesquisa for bem-sucedida, você receberá um pacote FHIR searchset contendo as instâncias de recursos retornadas da pesquisa. Se a pesquisa falhar, você encontrará os detalhes do erro em uma OperationOutcome resposta.
Nas seções a seguir, abordamos os vários aspetos da consulta de recursos no FHIR. Depois de revisar esses tópicos, consulte a página de exemplos de pesquisa FHIR, que apresenta exemplos de diferentes métodos de pesquisa FHIR.
Parâmetros de pesquisa
Quando faz uma pesquisa no FHIR, está a procurar na base de dados recursos que correspondam a determinados critérios. A API FHIR especifica um rico conjunto de parâmetros de pesquisa para ajustar os critérios de pesquisa. 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 de API de pesquisa FHIR, se for encontrada uma correspondência positiva 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 satisfizeram os critérios de pesquisa.
Para cada parâmetro de pesquisa, a especificação FHIR define o tipo de dados que pode ser usado. O suporte no serviço FHIR para os vários tipos de dados é descrito abaixo.
| Tipo de parâmetro de pesquisa | Serviço FHIR nos Serviços de Dados de Saúde do Azure | API do Azure para FHIR | Comentário |
|---|---|---|---|
| Número | Sim | Sim | |
| data | Sim | Sim | |
| string | Yes | Sim | |
| token | Sim | Sim | |
| referência | Sim | Sim | |
| compósito | Parcial | Parcial | A lista de tipos compostos suportados segue neste artigo. |
| quantidade | Sim | Sim | |
| uri | Sim | Sim | |
| Especial | No | Não |
Parâmetros de pesquisa comuns
Existem parâmetros de pesquisa comuns que se aplicam a todos os recursos no FHIR. Estes estão listados da seguinte forma, juntamente com o seu apoio 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 |
No | No | |
_filter |
No | No | |
_list |
No | No | |
_text |
No | No | |
_content |
No | Não |
Parâmetros específicos do 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 de 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 Declaração de Capacidade FHIR com a seguinte solicitação:
GET {{FHIR_URL}}/metadata
Para exibir os parâmetros de pesquisa suportados na instrução de capacidade, navegue até para CapabilityStatement.rest.resource.searchParam os parâmetros de pesquisa específicos do recurso e CapabilityStatement.rest.searchParam para os parâmetros de pesquisa que se aplicam a todos os recursos.
Nota
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. O serviço FHIR suporta parâmetros de pesquisa personalizados.
Parâmetros de pesquisa compostos
As pesquisas compostas no FHIR permitem pesquisar em pares de elementos como unidades logicamente conectadas. Por exemplo, se você estava procurando por observações em que a altura do paciente era superior a 60 polegadas, você gostaria de ter certeza de que uma única propriedade da observação continha o código de altura e um valor maior que 60 polegadas (o valor deve pertencer apenas à 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 evitam esse problema pesquisando em pares pré-especificados de elementos cujos valores devem atender aos critérios de pesquisa para que ocorra uma correspondência positiva.
O serviço FHIR nos Serviços de Dados de Saúde do Azure dá suporte aos seguintes emparelhamentos de tipos de parâmetros de pesquisa para pesquisas compostas.
- Referência, Token
- Token, Data
- Token, Número, Número
- Token, Quantidade
- Token, String
- Token, Token
Para obter mais informações, consulte a documentação HL7 Composite Search Parameters .
Nota
Os parâmetros de pesquisa compostos não suportam modificadores, de acordo com a especificação FHIR.
Modificadores e prefixos
Os modificadores permitem qualificar os parâmetros de pesquisa com condições adicionais. Abaixo está uma tabela de modificadores FHIR e seu suporte 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 | Sim | |
:type (referência) |
Sim | Sim | |
:not |
Sim | Sim | |
:below (uri) |
Sim | Sim | |
:above (uri) |
Sim | Sim | |
:in (token) |
No | Não | |
:below (token) |
No | Não | |
:above (token) |
No | Não | |
:not-in (token) |
No | No | |
:identifier |
No | 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 dos resultados da pesquisa
FHIR especifica um conjunto de parâmetros de resultados 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 . Segue-se uma tabela de parâmetros de resultados de pesquisa FHIR e o seu suporte no serviço FHIR.
| Parâmetros dos resultados da 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 | Sim | _count está limitada a 1000 recursos. Se estiver definido acima de 1000, apenas 1000 são devolvidos e um aviso será incluído no pacote. |
_include |
Sim | Sim | Os itens recuperados com _include são limitados a 100. _includeem PaaS e OSS no Azure O Cosmos DB não suporta :iterate (#2137). |
_revinclude |
Sim | Sim | Os itens recuperados com _revinclude são limitados a 100. _revincludeem PaaS e OSS no Azure O Cosmos DB não suporta :iterate (#2137). Há também um código de status incorreto para uma solicitação incorreta: #1319. |
_summary |
Sim | Sim | |
_total |
Parcial | Parcial | _total=none e _total=accurate |
_sort |
Parcial | Parcial | sort=_lastUpdated é suportado no serviço FHIR. Para o serviço FHIR e os servidores FHIR SQL DB OSS, há suporte para a classificação por cadeias de caracteres e campos dateTime. Para bancos de dados do Azure API for FHIR e OSS Azure Cosmos DB criados após 20 de abril de 2021, a classificação é suportada no nome, sobrenome, data de nascimento e data clínica. |
_contained |
No | No | |
_containedType |
No | No | |
_score |
No | Não |
Nota:
- 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 ordenar num único campo de cada vez. - O serviço FHIR suporta pesquisas 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 tratamento leniente. Isso significa que o servidor ignora quaisquer parâmetros desconhecidos ou não suportados. Se você quiser usar um tratamento rigoroso, você pode incluir o Prefer cabeçalho e definir handling=strict.
Pesquisa encadeada ou encadeada reversa
Uma pesquisa encadeada permite que você execute consultas direcionadas para recursos que tenham uma referência a outro recurso. Por exemplo, se você quiser encontrar encontros em que o nome do paciente é Jane, use:
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane
A . 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 _has parâmetro. Isso permite recuperar instâncias de recursos especificando critérios em outros recursos que fazem referência aos recursos de interesse. Para obter exemplos de pesquisa encadeada e encadeada inversamente, consulte a página de exemplos de pesquisa FHIR.
Paginação
Como mencionado anteriormente, 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 inclui 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 Integridade do Azure dá suporte apenas ao next link e não oferece suporte firsta , lastou previous links em pacotes retornados de uma pesquisa.
FAQ
O que significa "suporte parcial" em R4 Parâmetros de pesquisa não suportados?
Alguns dos parâmetros de pesquisa específicos do recurso abrangem mais de um tipo de dados, e o serviço FHIR nos Serviços de Dados de Saúde do Azure só pode dar suporte a esse parâmetro de pesquisa em um desses tipos de dados. Por exemplo, Condição-redução-idade e Condição-início-idade abrangem dois tipos de dados diferentes, Idade e Intervalo; no entanto, o serviço FHIR nos Serviços de Dados de Saúde do Azure dá suporte a esses dois parâmetros de pesquisa no Intervalo, mas não no Idade.
A operação $lastn para Observações é suportada?
Esta ação não é suportada. A abordagem alternativa seria usar _count para restringir os recursos retornados por página e _sort fornecer resultados em ordem decrescente.
Próximos passos
Agora que você aprendeu sobre os conceitos básicos da pesquisa FHIR, consulte 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.
Nota
FHIR® é uma marca registada da HL7 e é utilizada com a permissão da HL7.