Share via

Exemplos de pesquisa do FHIR da API do Azure para FHIR

  • Artigo

Abaixo estão alguns exemplos do uso de operações de pesquisa do FHIR® (Fast Healthcare Interoperability Resources), incluindo parâmetros e modificadores de pesquisa, pesquisa em cadeia e em cadeia reversa, pesquisa composta, exibição do próximo conjunto de entradas para resultados da pesquisa e pesquisa com uma solicitação POST. Para saber mais sobre pesquisa, confira Visão geral da Pesquisa do FHIR.

Parâmetros de resultado de pesquisa

_include

_include pesquisa entre recursos os que incluem o parâmetro especificado do recurso. Por exemplo, você pode pesquisar entre recursos MedicationRequest para encontrar somente os que incluem informações sobre as receitas para determinado paciente, que é o parâmetro referencepatient. No exemplo abaixo, isso efetuará pull de todas as MedicationRequests e todos os pacientes referenciados de MedicationRequests:

 GET [your-fhir-server]/MedicationRequest?_include=MedicationRequest:patient

Observação

_include e _revinclude estão limitados a 100 itens.

_revinclude

_revinclude permite que você pesquise na direção oposta de _include. Por exemplo, você pode procurar pacientes e, em seguida, reverter a inclusão de todos os encontros que fazem referência aos pacientes:

GET [your-fhir-server]/Patient?_revinclude=Encounter:subject

_elements

_elements restringe o resultado da pesquisa a um subconjunto de campos para reduzir o tamanho da resposta com a omissão de dados desnecessários. O parâmetro aceita uma lista separada por vírgulas de elementos base:

GET [your-fhir-server]/Patient?_elements=identifier,active

Nesta solicitação, você receberá de volta um pacote de pacientes, mas cada recurso incluirá apenas os identificadores e o status ativo do paciente. Os recursos nessa resposta retornada conterão um valor meta.tag de SUBSETTED para indicar que são um conjunto de resultados incompleto.

Modificadores de pesquisa

:not

:not permite que você encontre recursos em que um atributo não é verdadeiro. Por exemplo, você pode procurar pacientes em que o gênero não seja feminino:

GET [your-fhir-server]/Patient?gender:not=female

Como valor retornado, você obteria todas as entradas de pacientes em que o gênero não é feminino, incluindo valores vazios (entradas especificadas sem gênero). Isso é diferente de procurar pacientes em que o sexo é masculino, já que isso não incluiria as entradas sem um gênero específico.

:missing

:missing retorna todos os recursos que não têm um valor para o elemento especificado quando o valor é true e retorna todos os recursos que contêm o elemento especificado quando o valor é false. Para elementos de tipo de dados simples, :missing=true corresponderá todos os recursos em que o elemento estiver presente com extensões, mas com valor vazio. Por exemplo, se você quiser encontrar todos os recursos Patient com ausência de informações sobre data de nascimento, pode:

GET [your-fhir-server]/Patient?birthdate:missing=true

:exact

:exact é usado para parâmetros string e retorna resultados que correspondem ao parâmetro de forma precisa, por exemplo, maiúsculas e concatenação de caracteres.

GET [your-fhir-server]/Patient?name:exact=Jon

Essa solicitação retorna recursos Patient que têm o nome exatamente igual a Jon. Se o recurso tivesse Pacientes com nomes como Jonathan ou joN, a pesquisa ignoraria o recurso, pois ele não corresponde exatamente ao valor especificado.

:contains

:contains é usado em parâmetros string e pesquisa recursos com correspondências parciais do valor especificado em qualquer lugar na cadeia de caracteres no campo pesquisado. contains diferencia maiúsculas de minúsculas e permite a concatenação de caracteres. Por exemplo:

GET [your-fhir-server]/Patient?address:contains=Meadow

Essa solicitação retornaria para você todos os recursos Patient com campos address que têm valores contendo a cadeia de caracteres “Flores”. Isso significa que você pode ter endereços que incluem valores como "Floresta" ou "Rua das Flores, 123" retornados como resultados da pesquisa.

Para fazer uma série de operações de pesquisa que abordam vários parâmetros de referência, você poderá “encadear” uma série de parâmetros de referência acrescentando-os à solicitação do servidor um de cada vez com um . de ponto. Por exemplo, se quiser exibir todos os recursos DiagnosticReport com uma referência subject a um recurso Patient que inclui determinado name:

 GET [your-fhir-server]/DiagnosticReport?subject:Patient.name=Sarah

Essa solicitação retornaria todos os recursos DiagnosticReport com uma paciente chamada “Sara”. O . de ponto após o campo Patient faz a pesquisa encadeada no parâmetro de referência do parâmetro subject.

Outro uso comum de uma pesquisa regular (não uma pesquisa encadeada) é encontrar todos os encontros de um paciente específico. Patient costuma ter um ou mais Encounters com uma pessoa. Para pesquisar todos os recursos Encounter de um Patient com o id fornecido:

GET [your-fhir-server]/Encounter?subject=Patient/78a14cbe-8968-49fd-a231-d43e6619399f

Usando a pesquisa encadeada, você pode encontrar todos os recursos Encounter que correspondem a uma informação de Patient específica, por exemplo, birthdate:

GET [your-fhir-server]/Encounter?subject:Patient.birthdate=1987-02-20

Isso permitiria não só pesquisar um único paciente em recursos Encounter, mas entre todos os pacientes que tenham o valor de data de nascimento especificado.

Além disso, a pesquisa encadeada pode ser feita mais de uma vez em uma solicitação com o símbolo &, que permite que você pesquise várias condições em uma solicitação. Nesses casos, a pesquisa encadeada pesquisa cada parâmetro "independentemente", em vez de procurar condições que atendam apenas a todas as condições ao mesmo tempo:

GET [your-fhir-server]/Patient?general-practitioner:Practitioner.name=Sarah&general-practitioner:Practitioner.address-state=WA

Isso retornaria todos os recursos Patient que tenham “Sara” como generalPractitioner e tenham um generalPractitioner com endereço no estado de SP. Em outras palavras, se um paciente tivesse Sara do estado da BA e Mateus do estado de SP, ambos referenciados como generalPractitioner do paciente, eles seriam retornados.

Para cenários em que a pesquisa tenha que ser uma operação AND que aborda todas as condições como um grupo, confira o exemplo de pesquisa composta abaixo.

A pesquisa em cadeia permite que você pesquise recursos com base nas propriedades dos recursos aos quais eles se referem. Usar a pesquisa em cadeia reversa permite que você faça o contrário. Você pode pesquisar recursos com base nas propriedades dos recursos que fazem referência a eles, usando o parâmetro _has. Por exemplo, o recurso Observation tem um parâmetro de pesquisa patient que faz referência a um recurso de paciente. Para encontrar todos os recursos de paciente que são referenciados por Observation com um code específico:

GET [base]/Patient?_has:Observation:patient:code=527

Essa solicitação retorna recursos de paciente que sejam referenciados por Observation com o código 527.

Além disso, a pesquisa em cadeia reversa pode ter uma estrutura recursiva. Por exemplo, se você quiser pesquisar todos os pacientes que tenham Observation, em que a observação tenha um evento de auditoria de uma usuária janedoe específica, poderá:

GET [base]/Patient?_has:Observation:patient:_has:AuditEvent:entity:agent:Practitioner.name=janedoe

Observação

Na API do Azure para FHIR e no FHIR Server de código aberto apoiado pelo Azure Cosmos DB, a pesquisa encadeada e a pesquisa encadeada reversa são uma implementação de MVP. Para realizar uma pesquisa encadeada no Azure Cosmos DB, a implementação percorre a expressão de pesquisa e emite subconsultas para resolver os recursos correspondentes. Isso é feito em cada nível da expressão. Se alguma consulta retornar mais de 100 resultados, um erro será gerado.

Para pesquisar recursos que atendam a várias condições ao mesmo tempo, use pesquisa composta que una uma sequência de valores de parâmetro simples com um símbolo $. O resultado retornado seria a interseção dos recursos que correspondem a todas as condições especificadas pelos parâmetros de pesquisa unidos. Esses parâmetros de pesquisa são chamados de parâmetros de pesquisa composta e definem um novo parâmetro que combina os vários parâmetros em uma estrutura aninhada. Por exemplo, se você quer encontrar todos os recursos DiagnosticReport que contêm Observation com valor de potássio menor ou igual a 9,2:

GET [your-fhir-server]/DiagnosticReport?result.code-value-quantity=2823-3$lt9.2

Essa solicitação especifica o componente que contém um código de 2823-3, que, nesse caso, seria potássio. A seguir ao símbolo $, ele especifica o intervalo dos valores de componente usando lt para “menor ou igual a” e 9.2 para o intervalo de valores de potássio.

Pesquisar o próximo conjunto de entradas

O número máximo de entradas que podem ser retornadas por uma única consulta de pesquisa é 1000. No entanto, você pode ter mais de 1000 entradas que correspondem à consulta de pesquisa e talvez queira ver o próximo conjunto de entradas após as primeiras 1000 entradas retornadas. Nesse caso, você usa o valor de url do token de continuação no searchset como no resultado Bundle abaixo:

    "resourceType": "Bundle",
    "id": "98731cb7-3a39-46f3-8a72-afe945741bd9",
    "meta": {
        "lastUpdated": "2021-04-22T09:58:16.7823171+00:00"
    },
    "type": "searchset",
    "link": [
        {
            "relation": "next",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd"
        },
        {
            "relation": "self",
            "url": "[your-fhir-server]/Patient?_sort=_lastUpdated"
        }
    ],

E você faz uma solicitação GET para a URL fornecida abaixo do campo relation: next:

GET [your-fhir-server]/Patient?_sort=_lastUpdated&ct=WzUxMDAxNzc1NzgzODc5MjAwODBd

Isso retornará o próximo conjunto de entradas para o resultado da pesquisa. O searchset é o conjunto completo de entradas de resultado da pesquisa e o token de continuação url é o link fornecido pelo servidor a você para recuperar as entradas que não aparecem no primeiro conjunto por causa da restrição ao número máximo de entradas retornadas por uma consulta de pesquisa.

Pesquisar usando POST

Todos os exemplos de pesquisa mencionados acima usaram solicitações GET. Você também pode fazer operações de pesquisa usando solicitações POST com _search:

POST [your-fhir-server]/Patient/_search?_id=45

Essa solicitação retornaria todos os recursos Patient com o valor id de 45. Assim como nas solicitações GET, o servidor determina qual conjunto de recursos atende às condições e retorna um recurso de pacote na resposta HTTP.

Outro exemplo de pesquisa usando POST em que os parâmetros de consulta são enviados como um corpo de formulário é:

POST [your-fhir-server]/Patient/_search
content-type: application/x-www-form-urlencoded

name=John

Próximas etapas

Neste artigo, você aprendeu a pesquisar usando diferentes parâmetros de pesquisa, modificadores e ferramentas de pesquisa do FHIR. Para saber mais sobre Pesquisa do FHIR, confira

Visão geral da Pesquisa do FHIR

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