Destaque de Busca FHIR 2025.1 - Suporte a Buscas Relacionadas a Listas (_List, $find, Listas Funcionais/"Atuais")

Às vezes é mais conveniente, eficiente e seguro limitar as Buscas FHIR por "Listas" de Recursos pré-definidas.

Desde a v2025.1, suportamos vários recursos relacionados a Listas em nosso Servidor FHIR.

Vou destacar estes recursos aqui e fornecer alguns exemplos.

Em geral, você pode ver os detalhes sobre o Recurso List na documentação oficial do FHIR.

Mas aqui está uma breve descrição baseada no link acima:

O Recurso FHIR List representa uma coleção plana (opcionalmente ordenada) de registros usados para listas clínicas (ex: alergias, medicamentos, alertas, históricos) e gerenciamento de fluxo de trabalho (ex: rastreamento de pacientes, casos de ensino).
Listas podem ser homogêneas (tipo de recurso único) ou heterogêneas (tipos mistos, ex: uma lista de problemas abrangendo Conditions, AllergyIntolerances e Procedures).
Use List quando precisar de um conjunto curado/filtrado que não pode ser obtido via uma consulta simples (ex: alergias “atuais” vs. todas as alergias registradas).
Consultar uma List produz um snapshot de um ponto no tempo curado por humanos, enquanto consultar o endpoint do recurso geralmente retorna um conjunto de dados mais amplo, não curado, “no estado atual”.

Em nossas versões mais recentes (2025.1+), você pode encontrar novos suportes para trabalhar com Listas:

• O Parâmetro de Busca _list

Veja a documentação FHIR relacionada para uma descrição completa. Veja nossa Documentação relacionada para detalhes sobre o suporte disponível (especificamente sobre buscas em nível de Tipo vs. nível de Sistema).

Usando este recurso, você pode definir, por exemplo, uma Lista de certos Recursos (como Encounters ou Patients, etc.) pelos quais você deseja buscar, sem ter que detalhar todos eles como múltiplos Parâmetros de Busca.

Por exemplo, eu poderia definir uma Lista de Pacientes:

curl --location --request PUT 'http://myserver/fhir/r4/List/OrgAPatients'

--header 'Content-Type: application/fhir+json'

--header 'Authorization: *******'

--data '{   "resourceType": "List",   "id":"OrgAPatients",   "status":"current",   "mode":"snapshot",   "entry": [       {         "item": {            "reference": "Patient/2"         }       },       {         "item": {            "reference": "Patient/3"         }       },       {         "item": {            "reference": "Patient/4"         }       }     ] }'

E então buscá-los desta forma:

curl --location 'http://myserver/fhir/r4/Patient?_list=OrgAPatients'

--header 'Content-Type: application/fhir+json'

--header 'Authorization: *****'

E receber de volta uma lista curada dos Pacientes que eu queria, em vez de ter que "mencionar" todos eles em vários Parâmetros de Busca.

E, claro, existem muitos outros casos de uso.

• Listas Funcionais (incluindo a Operação Customizada $update-functional)

Um tipo especial de listas são as Listas Funcionais (ou Listas de "Recursos Atuais").

Veja a documentação FHIR relacionada para uma descrição completa.

Para sua conveniência, aqui está uma breve descrição baseada no link acima:

Muitos sistemas clínicos mantêm listas de pacientes “atuais” (por exemplo, uma lista de problemas atual e uma lista de medicamentos atual), mas o FHIR não pode inferir com segurança a “atualidade” inspecionando uma única instância de recurso. Usando Condition como exemplo, o mesmo tipo de recurso pode ser postado para múltiplos propósitos legítimos (entrada de lista de problemas curada, queixa/diagnóstico de encontro, contexto de fluxo de trabalho diagnóstico ou dados de encaminhamento de entrada), e a Condition não possui nenhum elemento que distingua claramente esses usos. Como distinguir o atual vs. o passado exigiria alteração retrospectiva (criando preocupações de integridade e assinatura digital), uma busca normal em Condition para um paciente retornará mais do que apenas os “problemas atuais” curados, e limitá-la apenas ao “atual” ocultaria outros registros importantes de Condition. Portanto, se uma Condition (ou registro similar) está na “lista atual” de um paciente pode ser determinado pelo fato de estar ou não referenciada na List apropriada. Via API REST, isso é expresso através do mecanismo de busca de lista usando _list com nomes de listas funcionais padrão (ex: GET [base]/AllergyIntolerance?patient=42&_list=$current-allergies), e o servidor pode suportar isso sem necessariamente expor uma instância de List independente. Existem vários nomes de listas funcionais "comuns", como $current-problems, $current-medications, $current-allergies e $current-drug-allergies (um subconjunto de alergias).

Para permitir a manutenção dessas Listas Funcionais, definimos uma Operação Customizada, chamada $update-functional, que permite a criação e atualização desses tipos de listas. Veja mais detalhes em nossa Documentação.

Você pode definir uma lista de alergias atuais, por exemplo, assim:

curl --location 'http://fhirserver/fhir/r4/List/$update-functional?for=34&name=%5C%24current-allergies'

--header 'Content-Type: application/fhir+json'

--header 'Authorization: *****'

--data '{   "resourceType": "List",   "status":"current",   "mode":"working",   "subject":  { "reference":"Patient/34" },   "entry": [       {         "item": {            "reference": "AllergyIntolerance/159"         }       },       {         "item": {            "reference": "AllergyIntolerance/160"         }       },       {         "item": {            "reference": "AllergyIntolerance/161"         }       }     ] }'

Isso criará/atualizará a Lista $current-allergies, para um paciente específico (ID 34 no exemplo acima)

Note que eu incluí o 'for=' na URL apontando ao ID do paciente, e na liste eu tenho o 'subject' referenciando o paciente.

(Note também que para o cifrão ($) eu usei uma barra invertida antes (\), ou seja: \$)

E agora, posso solicitar o Recurso AllergyIntolerance deste Paciente e, em vez de receber todos eles, posso pedir apenas os "atuais", conforme definido na Lista acima.

Isso ficaria assim:

curl --location 'http://fhirserver/fhir/r4/AllergyIntolerance?patient=34&_list=%5C%24current-allergies'

--header 'Authorization: *****'

E isso retornaria um subconjunto das alergias deste Paciente, conforme a lista de alergias atuais.

Note que estamos usando o mesmo Parâmetro de Busca _list mencionado anteriormente, apenas desta vez com uma "Lista Funcional" em vez de uma "Lista Customizada".

Note que você pode controlar os nomes das listas funcionais (e para cada lista, seu Parâmetro de Busca subject e o Tipo de Recurso subject; por exemplo, no exemplo acima, o parâmetro de busca subject foi patient e o Tipo de Recurso subject foi Patient), através da configuração do Endpoint FHIR, especificamente em "Interactions Strategy Settings", veja a documentação relacionada aqui. A aparência é esta:

• Operação $find

Além disso, se você simplesmente quiser obter a própria Lista Funcional (para um assunto específico e de um tipo específico), pode usar a operação $find.

Veja a documentação FHIR relacionada para uma descrição completa. E veja também nossa Documentação relacionada.

Aqui está um exemplo, seguindo o anterior:

curl --location 'http://fhirserver/fhir/r4/List/$find?patient=34&name=%5C%24current-allergies'

--header 'Authorization: *****'

Isso retornará a lista $current-allergies relacionada para este Paciente, conforme definido acima via a função $update-functional.

Veja o aplicativo relacionado no Open Exchange que inclui uma Postman Collection com os exemplos acima (e um pouco mais) e instruções sobre como executar isso no container docker do FHIR server template de @Evgeny Shvarov (de fato, o exemplo acima foi criado com base neste modelo; com uma pequena alteração... veja detalhes nas instruções de uso do meu app).