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 aEvelyn
eSeverine
.:exact
corresponde à string inteira, incluindo maiúsculas e minúsculas, por exemplo,name:exact=Eve
não corresponde aeve
ouEvelyn
.
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âmetrone
: diferente de, o oposto deeq
gt
: o valor exato armazenado é maior que o valor exato do parâmetrolt
: o valor exato armazenado é menor que o valor exato do parâmetroge
: o valor exato armazenado é maior ou igual ao valor exato do parâmetrole
: 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 destinone
: diferente de, o oposto deeq
gt
: maior que, o intervalo acima do valor do parâmetro se sobrepõe ao intervalo do destinolt
: menor que, o intervalo abaixo do valor do parâmetro se sobrepõe ao intervalo do destinoge
: maior que ou igual ale
: menor que ou igual asa
: o intervalo do valor do parâmetro começa após o intervalo de destinoeb
: o intervalo do valor do parâmetro termina antes do intervalo de destino
Pesquisa de token
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 valorcode
, independentemente dosystem
[parameter]=[system]|[code]
precisa corresponder aosystem
e aocode
especificados[parameter]=|[code]
corresponde acode
quando o valorsystem
está vazio[parameter]=[system]|
corresponde a qualquercode
com o valorsystem
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 campotext
oudisplay
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, osystem
especificado precisa existir no armazenamento FHIR como um recursoCodeSystem
.: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 recursoValueSet
no mesmo armazenamento FHIR. O modificador corresponde a qualquer código que esteja noValueSet
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 contenhaxyz
e um ou mais deabc
def
ghi
.-
é o operador NOT. Por exemplo,abc -def
corresponderá a um recurso que contémabc
, mas não contémdef
.
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.
Pesquisa encadeada
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á.
Pesquisa encadeada reversa
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 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 assim.
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 recursosMedicationRequest
e, para cada recurso retornado, também retorna o destino da referênciasubject
, que pode serGroup
ouPatient
, conforme definido na especificação FHIR.MedicationRequest?_include=MedicationRequest:subject:Patient
é semelhante, mas retorna apenas referênciassubject
a recursosPatient
.MedicationRequest?_revinclude=Provenance:target
pesquisa recursosMedicationRequest
e, para cada recurso retornado, também retorna quaisquer recursosProvenance
em que a referênciatarget
emProvenance
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 recursosObservation
e segue recursivamente a referência derivada de recursosObservation
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 umtarget
que está nesse conjunto de resultados e incluirá recursos referenciados por meio do parâmetroagent
dessesProvenance
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 recursosObservation
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 recursosPatient
para cada recursoMedicationRequest
.
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 superiortext
,id
emeta
_summary=data
remove o campotext
e retorna todos os outros campos