Recursos avançados de pesquisa FHIR

Nesta página, explicamos como pesquisar recursos FHIR usando a funcionalidade de consulta mais avançada disponível por meio do método projects.locations.datasets.fhirStores.fhir.search. Este guia pressupõe que você tenha familiaridade com o conteúdo em Como pesquisar recursos FHIR.

Modificadores de pesquisa de string

O padrão de uma pesquisa de string é uma correspondência de prefixo que não diferencia maiúsculas de minúsculas e acentos por meio da dobra para o formulário Unicode NFC padrão. Pontuação e espaços em branco extras são ignorados.

Os seguintes modificadores estão disponíveis:

  • :contains corresponde a recursos com o valor especificado em qualquer parte da string, por exemplo, name:contains=eve corresponde a Evelyn e Severine.
  • :exact corresponde à string inteira, incluindo maiúsculas e minúsculas, por exemplo, name:exact=Eve não corresponde a eve ou Evelyn.

Comparadores e precisão de números, datas e quantidades

Os valores usados em uma pesquisa numérica ou de data dependem da precisão do valor do parâmetro. Por exemplo, o número 7.00 tem um intervalo implícito de 6.995, inclusive 7.005. A data 2015-08-12 tem um intervalo de 2015-08-12T00:00:00, inclusive 2015-08-13T00:00:00.

A precisão afeta os resultados retornados para comparações de igualdade. Por exemplo, um valor de 7.03 em um recurso corresponderia a uma pesquisa por value=7.0, mas não a uma pesquisa por value=7.00.

Todos os valores de pontos flutuantes clicados no FHIR são representados por tipos, como Decimal e Quantidade, que registram a precisão do valor armazenado. Como exceção, há alguns campos que usam números inteiros simples para representar, por exemplo, uma posição em uma sequência. Nesses campos, as pesquisas são correspondências numéricas exatas.

Os prefixos a seguir se aplicam a comparações numéricas em relação a um valor singleton. Se nenhum prefixo for especificado, o padrão será eq.

  • eq: igual a, o valor armazenado exato está dentro do intervalo definido pela precisão do valor do parâmetro
  • ne: diferente de, o oposto de eq
  • gt: o valor exato armazenado é maior que o valor exato do parâmetro
  • lt: o valor exato armazenado é menor que o valor exato do parâmetro
  • ge: o valor exato armazenado é maior ou igual ao valor exato do parâmetro
  • le: o valor exato armazenado é menor ou igual ao valor exato do parâmetro

Os valores de data têm um intervalo implícito baseado no nível de especificidade do valor (um ano, um mês, um dia). Outros tipos de dados, como Intervalo e Período, têm limites superiores e inferiores explícitos. Os prefixos a seguir se aplicam às comparações de intervalos. Se nenhum prefixo for especificado, o padrão será eq.

  • eq: igual a, o intervalo do valor do parâmetro inclui todo o intervalo do destino
  • ne: diferente de, o oposto de eq
  • gt: maior que, o intervalo acima do valor do parâmetro se sobrepõe ao intervalo do destino
  • lt: menor que, o intervalo abaixo do valor do parâmetro se sobrepõe ao intervalo do destino
  • ge: maior que ou igual a
  • le: menor que ou igual a
  • sa: o intervalo do valor do parâmetro começa após o intervalo de destino
  • eb: o intervalo do valor do parâmetro termina antes do intervalo de destino

Os parâmetros de pesquisa de token se aplicam a casos em que um valor não é uma string arbitrária, mas sim uma entidade em um sistema de nomenclatura. Para parâmetros de token, a correspondência de string é exata.

A maioria das pesquisas de token se aplica a tipos de dados complexos com um system que é um URI que indica o sistema de nomenclatura de onde o valor code é obtido. Essas pesquisas são compatíveis com as seguintes sintaxes de valor:

  • [parameter]=[code] corresponde ao valor code, independentemente do system
  • [parameter]=[system]|[code] precisa corresponder ao system e ao code especificados
  • [parameter]=|[code] corresponde a code quando o valor system está vazio
  • [parameter]=[system]| corresponde a qualquer code com o valor system fornecido

Há vários modificadores que acionam a funcionalidade alternativa de pesquisa de tokens:

  • :not nega as condições correspondentes de uma pesquisa de token
  • :text faz uma pesquisa de string (sem correspondência exata) no campo text ou display associado ao código, em vez do próprio valor de código
  • :above usa um parâmetro apenas no formato [system]|[code] e corresponde aos recursos em que o código no recurso substitui o parâmetro de consulta. Para usar esse modificador, o system especificado precisa existir no armazenamento FHIR como um recurso CodeSystem.
  • :below é como :above, mas corresponde se o código no recurso for subsumido pelo parâmetro de consulta.
  • :in usa um único parâmetro usando a sintaxe de parâmetro de referência, por exemplo, code:in=ValueSet/1234. A referência precisa se referir a um recurso ValueSet no mesmo armazenamento FHIR. O modificador corresponde a qualquer código que esteja no ValueSet referenciado.
  • :not-in nega as condições de :in

As pesquisas de token também se aplicam aos campos booleanos, de URI e a determinados campos de string em que só é permitida correspondência exata. Nesses casos, o único formato de parâmetro é [parameter]=[value].

Como pesquisar valores ausentes

O modificador de pesquisa :missing pode ser usado em qualquer parâmetro de pesquisa para corresponder à presença ou ausência de qualquer valor no campo especificado. Por exemplo, Patient?gender=unknown corresponde a recursos que contêm explicitamente o valor de enum unknown para gênero. No entanto, como esse campo não é obrigatório, pode haver outros recursos que não preencham o campo. Esses recursos podem ser correspondidos por Patient?gender:missing=true. A conversão, Patient?gender:missing=false, corresponde a qualquer recurso que preenche explicitamente esse campo.

Pesquisa de texto

O parâmetro de pesquisa especial _content realiza uma correspondência de texto em campos baseados em strings (excluindo campos de número, data ou enum), se o campo é o destino de qualquer parâmetro de pesquisa no recurso. Por padrão, ele corresponde a recursos com todas as palavras da consulta e é compatível com outros operadores:

  • | é o operador OR. Por exemplo, abc | def | ghi xyz corresponderá a um recurso que contenha xyz e um ou mais de abc def ghi.
  • - é o operador NOT. Por exemplo, abc -def corresponderá a um recurso que contém abc, mas não contém def.

A correspondência é baseada em palavras completas e não corresponde a substrings ou caracteres não alfanuméricos. A ordem das palavras não importa. As palavras correspondentes podem ser distribuídas por vários campos no recurso.

O parâmetro _text executa o mesmo tipo de correspondência apenas no campo Narrative, que serve para armazenar um resumo legível do conteúdo do recurso. A API Cloud Healthcare não gera esse resumo automaticamente, mas aceita o parâmetro de pesquisa _text se esses dados foram preenchidos pelo cliente ao criar ou atualizar o recurso.

Parâmetros de pesquisa compostos

Ao pesquisar usando vários parâmetros de consulta, há casos em que os parâmetros de pesquisa individuais combinados com AND correspondem a resultados indesejados. Os parâmetros de pesquisa compostos são um tipo especial de parâmetro de pesquisa que soluciona esse problema.

Por exemplo, o recurso Observation pode ter vários valores no campo component, cada um com um par de code e value. Uma pesquisa por Observation?component-code=8867-4&component-value-quantity=lt50 corresponderia a um recurso com um componente contendo um code de 8867-4 e um componente diferente contendo um value menor que 50. Essa pesquisa não pode ser usada para restringir a uma correspondência desses dois valores no mesmo componente.

Os parâmetros de pesquisa compostos definem um novo parâmetro que combina dois outros parâmetros de pesquisa e define um nível de aninhamento a que ambos devem corresponder. Na consulta, os dois valores são unidos por $. Por exemplo, Observation tem um parâmetro composto component-code-value-quantity que pode restringir o exemplo anterior a um único componente pesquisando por Observation?component-code-value-quantity=8867-4$lt50. Esses parâmetros são definidos pela especificação FHIR e não existem para todas as combinações de parâmetros de pesquisa.

Os parâmetros de pesquisa composta não permitem modificadores.

Assim como acontece com todos os parâmetros de pesquisa, as informações sobre quais parâmetros compostos são compatíveis com a API Cloud Healthcare podem ser encontradas na declaração de capacidade ou na declaração de conformidade FHIR.

Uma pesquisa encadeada permite que uma pesquisa passe por referências dentro do contexto de uma consulta. A sintaxe básica de uma pesquisa encadeada é:

[reference parameter]:[resource type].[inner search parameter]=[inner value]

Se o parâmetro de referência se referir apenas a um tipo de recurso, o :[resource type] poderá ser omitido, resultando em:

[reference parameter].[inner search parameter]=[inner value]

Por exemplo, Observation tem um parâmetro de pesquisa de referência subject que pode apontar para um Group, Device, Patient ou Location. Para encontrar Observations com um subject que é um Patient com um nome que começa com "Joe", pesquise Observation?subject:Patient.name=Joe.

Se a consulta tiver vários parâmetros encadeados, cada cadeia será avaliada separadamente. Por exemplo, Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada corresponderia a um Patient com duas referências general-practitioner, uma chamada "Joe" e a outra com um endereço no Canadá. Não há sintaxe para agrupar essas cláusulas para corresponder apenas a Joe do Canadá.

Uma pesquisa em cadeia reversa corresponde a recursos com base em critérios em outros recursos que se referem a eles. A sintaxe de uma pesquisa em cadeia reversa é:

_has:[resource type]:[reference parameter]:[search parameter]=[value]

Por exemplo, o recurso Appointment tem um parâmetro de pesquisa patient que se refere a um recurso Patient. Para encontrar todos os recursos Patient referenciados por um recurso Appointment com uma data de 2020-04-01, use Patient?_has:Appointment:patient:date=eq2020-04-01.

As redes reversas podem ser recursivas. Por exemplo, Practitioner?_has:Encounter:practitioner:_has:Claim:encounter:created=eq2020-04-01 corresponderia a um P Practitioner se houver um E Encounter e um C Claim de modo que C tenha uma data de criação de 2020-04-01, C refere-se a E por meio da referência encounter e E refere-se a P por meio da referência practitioner.

Como incluir mais recursos nos resultados da pesquisa

Os parâmetros _include e _revinclude solicitam que os resultados da pesquisa incluam recursos extras ("recursos incluídos") relacionados aos recursos que correspondem diretamente à consulta ("resultados principais"). Usar esses parâmetros é mais eficiente do que fazer uma série de solicitações para recuperar esses recursos extras separadamente. No pacote searchset retornado da pesquisa, os recursos adicionados por esses parâmetros serão sinalizados com entry.search.mode = include para diferenciá-los dos resultados principais que terão entry.search.mode = match.

A inclusão direta com _include adiciona recursos e versões de recursos referenciados pelos resultados principais, e a inclusão reversa com _revinclude adiciona recursos que fazem referência aos resultados principais. A referência a seguir é especificada pelo nome de um parâmetro de pesquisa, e apenas os campos de referência disponíveis como parâmetros de pesquisa podem ser usados dessa maneira.

Os formatos de parâmetro para _include e _revinclude são os mesmos, usando dois ou três valores delimitados por :. O primeiro valor é o tipo de recurso de origem, o segundo é o nome do parâmetro de pesquisa e o terceiro valor opcional limita o tipo de recurso a um único tipo nos casos em que a referência pode apontar para mais de um tipo.

Exemplo:

  • MedicationRequest?_include=MedicationRequest:subject pesquisa recursos MedicationRequest e, para cada recurso retornado, também retorna o destino da referência subject, que pode ser Group ou Patient, conforme definido na especificação FHIR.
  • MedicationRequest?_include=MedicationRequest:subject:Patient é semelhante, mas retorna apenas referências subject a recursos Patient.
  • MedicationRequest?_revinclude=Provenance:target pesquisa recursos MedicationRequest e, para cada recurso retornado, também retorna quaisquer recursos Provenance em que a referência target em Provenance se refere ao recurso correspondente.

O modificador :iterate faz com que uma _include seja avaliada iterativamente. Esse modificador pode seguir uma camada extra de referências dos resultados incluídos ou seguir estruturas recursivas, como Observation:derived-from, referenciando outro Observation. A profundidade da recursão é limitada.

Exemplo:

  • Observation?_include:iterate=Observation:derived-from:Observation pesquisa recursos Observation e segue recursivamente a referência derivada de recursos Observation correspondentes e, em seguida, de recursos incluídos e assim por diante.
  • MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agent pesquisará MedicationRequest, incluirá Provenance recursos com um target que está nesse conjunto de resultados e incluirá recursos referenciados por meio do parâmetro agent desses Provenance recursos.

Um curinga, *, indica que todas as referências disponíveis como parâmetros de pesquisa precisam ser incluídas. É possível usar o curinga curinga * como o primeiro e único argumento em _include ou no lugar do nome do parâmetro de pesquisa do _include padrão, em que o terceiro valor opcional limita o tipo de recurso a um único tipo, como no comportamento original.

Por exemplo:

  • Observation?_include=* pesquisa recursos Observation e, para cada recurso, também retorna todos os recursos referenciados.
  • Observation?_include=Observation:* é equivalente ao anterior.
  • MedicationRequest?_include=MedicationRequest:*:Patient retorna todas as referências a recursos Patient para cada recurso MedicationRequest.

Os recursos incluídos serão duplicados, de modo que apenas uma cópia de um recurso será retornada em uma página de resultados, mesmo que seja encontrada por meio de várias referências. O mesmo recurso incluído será retornado em cada página de resultados em que um resultado principal estiver relacionado a ele.

Como limitar os campos retornados nos resultados da pesquisa

O parâmetro _elements permite que o cliente solicite que apenas um subconjunto de campos seja retornado para cada resultado da pesquisa, reduzindo o tamanho da resposta por meio da omissão de dados desnecessários. O parâmetro aceita uma lista separada por vírgulas com nomes de elementos básicos no recurso, por exemplo, Patient?_elements=identifier,contact,link. Somente esses campos e seus filhos serão incluídos nos recursos retornados. Os recursos na resposta que foram alterados por esse parâmetro conterão um valor meta.tag de SUBSETTED para indicar que estão incompletos.

A API Cloud Healthcare tem compatibilidade limitada com o parâmetro _summary, que fornece subconjuntos predefinidos de campos de recursos semelhantes a _elements:

  • _summary=text retorna apenas os campos de nível superior text, id e meta
  • _summary=data remove o campo text e retorna todos os outros campos