고급 FHIR 검색 기능

이 페이지에서는 projects.locations.datasets.fhirStores.fhir.search 메서드를 통해 제공되는 고급 쿼리 기능을 사용하여 FHIR 리소스를 검색하는 방법을 설명합니다. 이 가이드에서는 사용자가 FHIR 리소스 검색에 이미 익숙하다고 가정합니다.

문자열 검색 한정자

문자열 검색은 기본적으로 표준 Unicode NFC 형식에 따라 대소문자를 및 악센트를 구분하지 않는 프리픽스 일치로 지정됩니다. 구두점 및 추가 공백은 무시됩니다.

사용할 수 있는 한정자는 다음과 같습니다.

  • :contains는 리소스를 문자열의 모든 위치에 있는 지정된 값과 일치합니다. 예를 들어 name:contains=eveEvelynSeverine과 일치합니다.
  • :exact는 대소문자 및 악센트를 포함한 전체 문자열과 일치합니다. 예를 들어 name:exact=Eveeve 또는 Evelyn과 일치하지 않습니다.

숫자, 날짜, 수량 비교 연산자 및 정밀도

숫자 또는 날짜 검색에 사용되는 값은 매개변수 값의 정밀도에 따라 다릅니다. 예를 들어 숫자 7.00의 암시적 범위는 6.995(포함)~7.005(제외)입니다. 2015-08-12 날짜의 범위는 2015-08-12T00:00:00(포함)~2015-08-13T00:00:00(제외)입니다.

정밀도는 같음 비교로 반환되는 결과에 영향을 줍니다. 예를 들어 리소스에서 7.03 값은 value=7.0 검색과 일치하지만, value=7.00 검색과 일치하지 않습니다.

FHIR의 임상학적으로 유의미한 모든 부동 소수점 값은 저장된 값의 정밀도를 기록하는 DecimalQuantity와 같은 유형으로 표현됩니다. 예외적으로, 시퀀스에서 위치를 나타내는 등 간단한 정수를 사용하는 필드가 몇 개 있는데, 이러한 필드에 대한 검색은 정확히 일치하는 숫자입니다.

다음 프리픽스는 싱글톤 값에 대한 숫자 비교에 적용됩니다. 프리픽스가 지정되지 않은 경우 기본값은 eq입니다.

  • eq: 같음, 정확한 저장 값이 매개변수 값의 정밀도로 정의된 범위 내에 있음
  • ne: 같지 않음, eq의 반대
  • gt: 정확한 저장 값이 정확한 매개변수 값보다 큼
  • lt: 정확한 저장 값이 정확한 매개변수 값보다 작음
  • ge: 정확한 저장 값이 정확한 매개변수 값보다 크거나 같음
  • le: 정확한 저장 값이 정확한 매개변수 값보다 작거나 같음

날짜 값은 값의 구체성 수준에 따라 암시적 범위를 갖습니다(1년, 1개월, 1일). 범위기간과 같은 다른 데이터 유형은 명시적 상한 및 하한을 포함합니다. 다음 프리픽스는 범위 비교에 적용됩니다. 프리픽스가 지정되지 않은 경우 기본값은 eq입니다.

  • eq: 같음, 매개변수 값의 범위에 대상의 범위가 완전히 포함됨
  • ne: 같지 않음, eq의 반대
  • gt: 보다 큼, 매개변수 값 위의 범위가 대상 범위와 겹침
  • lt: 미만, 매개변수 값 아래의 범위가 대상의 범위와 겹침
  • ge: 크거나 같음
  • le: 작거나 같음
  • sa: 매개변수 값의 범위가 대상 범위 이후에 시작
  • eb: 매개변수 값의 범위가 대상 범위 이전에 종료

토큰 검색 매개변수는 임의의 문자열이 아니라 이름 지정 시스템의 항목에 적용됩니다. 토큰 매개변수의 문자열 일치는 정확합니다.

대부분의 토큰 검색은 code 값을 가져온 이름 지정 시스템을 나타내는 URI인 system을 포함하는 복잡한 데이터 유형에 적용됩니다. 이러한 검색은 다음 값 구문을 지원합니다.

  • [parameter]=[code]system에 관계없이 code 값과 일치합니다.
  • [parameter]=[system]|[code]는 지정된 systemcode와 모두 일치해야 합니다.
  • system 값이 비어 있으면 [parameter]=|[code]code와 일치합니다.
  • [parameter]=[system]|은 지정된 system 값을 가진 모든 code와 일치합니다.

대체 토큰 검색 기능을 실행하는 몇 가지 한정자가 있습니다.

  • :not는 토큰 검색의 일치 조건을 무효화합니다.
  • :text는 코드 값 자체 대신 코드와 연결된 text 또는 display 필드에서 일치검색이 아닌 문자열 검색을 수행합니다.
  • :above[system]|[code] 형식의 매개변수만 가져와서 리소스의 코드가 쿼리 매개변수를 포함하는 리소스와 일치합니다. 이 한정자를 사용하려면 지정된 system이 FHIR 저장소에 CodeSystem 리소스로 존재해야 합니다.
  • :below:above와 비슷하지만 리소스의 코드를 쿼리 매개변수가 포함하는 경우에 일치합니다.
  • :in은 참조 매개변수 구문(예: code:in=ValueSet/1234)을 사용하여 단일 매개변수를 사용합니다. 참조는 동일한 FHIR 저장소 내의 ValueSet 리소스를 참조해야 합니다. 한정자는 참조된 ValueSet에 있는 모든 코드와 일치합니다.
  • :not-in:in의 조건을 무효화합니다.

토큰 검색은 부울 및 URI 필드와 일치검색만 허용되는 특정 문자열 필드에도 적용됩니다. 이 경우 유일한 매개변수 형식은 [parameter]=[value]입니다.

누락된 값 검색

모든 검색 매개변수에서 검색 한정자 :missing을 사용하면 지정된 필드의 값이 있거나 없는지에 따라 일치하는 값을 찾을 수 있습니다. 예를 들어 Patient?gender=unknown은 성별에 unknown 열거형 값이 명시적으로 포함된 리소스와 일치하지만, 이 필드가 필수가 아니므로, 필드를 전혀 채우지 않는 다른 리소스도 있을 수 있습니다. 이러한 리소스는 Patient?gender:missing=true와 일치할 수 있습니다. 반대되는 Patient?gender:missing=false는 명시적으로 이 필드를 채우는 리소스와 일치합니다.

특수 검색 매개변수 _content는 모든 리소스에 있는 모든 검색 매개변수의 대상인 모든 필드에서 텍스트 일치를 수행합니다. 기본적으로 쿼리에 모든 단어가 포함된 리소스와 일치하며 추가 연산자가 지원됩니다.

  • |는 OR 연산자입니다. 예를 들어 abc | def | ghi xyzxyz 및 하나 이상의 abc def ghi가 포함된 리소스와 일치합니다.
  • -는 NOT 연산자입니다. 예를 들어 abc -defabc를 포함하지만 def를 포함하지 않는 리소스와 일치합니다.

_text 매개변수는 사람이 읽을 수 있는 리소스 콘텐츠 요약이 포함된 설명 필드에서만 동일한 일치 유형을 수행합니다. Cloud Healthcare API는 이 요약을 자동으로 생성하지 않지만 리소스를 만들거나 업데이트할 때 클라이언트가 이 데이터를 채운 경우 _text 검색 매개변수를 지원합니다.

복합 검색 매개변수

여러 쿼리 매개변수를 사용하여 검색할 때 AND와 결합된 개별 검색 매개변수가 의도하지 않은 결과와 일치하는 경우가 있습니다. 복합 검색 매개변수는 이 문제를 해결하는 특별한 유형의 검색 매개변수입니다.

예를 들어 Observation 리소스는 component 필드에 여러 값을 포함할 수 있으며, 각 값에는 codevalue 쌍이 포함됩니다. Observation?component-code=8867-4&component-value-quantity=lt50에 대한 검색은 8867-4 code를 포함하는 구성요소 하나와 value가 50 미만인 다른 구성요소와 일치합니다. 동일한 구성요소 내에서 이 두 값의 일치를 제한하는 데 이 검색을 사용할 수 없습니다.

복합 검색 매개변수는 두 개의 다른 검색 매개변수를 조합하는 새 매개변수를 정의하고 둘 다 일치해야 하는 중첩 수준을 정의합니다. 쿼리에서 두 값은 $로 연결됩니다. 예를 들어 ObservationObservation?component-code-value-quantity=8867-4$lt50을 검색하여 이전 예시를 단일 구성요소로 제한할 수 있는 복합 매개변수 component-code-value-quantity를 포함합니다. 이러한 매개변수는 FHIR 사양으로 정의되며 검색 매개변수의 모든 조합에 대해 존재하지 않습니다.

복합 검색 매개변수는 한정자를 허용하지 않습니다.

모든 검색 매개변수와 마찬가지로 Cloud Healthcare API에서 지원하는 복합 매개변수에 대한 정보는 기능 설명 또는 FHIR 적합성 명세에서 확인할 수 있습니다.

연결된 검색은 쿼리 컨텍스트 내에서 검색이 참조를 순회하도록 허용합니다. 연결된 검색의 기본 구문은 다음과 같습니다.

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

참조 매개변수가 하나의 리소스 유형만 참조하는 경우 :[resource type]이 생략될 수 있습니다.

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

예를 들어 Observation에는 Group, Device, Patient 또는 Location를 가리킬 수 있는 참조 검색 매개변수 subject가 있습니다. 이름이 'Joe'로 시작하는 Patientsubject가 있는 Observations를 찾으려면 Observation?subject:Patient.name=Joe를 검색하세요.

쿼리에 체인 매개변수가 여러 개 있으면 각 체인이 별도로 평가됩니다. 예를 들어 Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada는 두 개의 general-practitioner 참조가 있는 Patient(하나는 'Joe'이고 다른 하나는 캐나다에 주소가 있음)와 일치합니다. 이러한 절을 캐나다의 Joe만 일치시킬 수 있는 구문은 없습니다.

역방향 연결된 검색은 이를 참조하는 다른 리소스에 대한 기준에 따라 리소스와 일치합니다. 역방향 연결된 검색의 구문은 다음과 같습니다.

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

예를 들어 Appointment 리소스에는 Patient 리소스를 참조하는 검색 매개변수 patient가 있습니다. 날짜가 2020-04-01Appointment 리소스에서 참조하는 모든 Patient 리소스를 찾으려면 Patient?_has:Appointment:patient:date=eq2020-04-01을 사용합니다.

역 체인은 재귀적일 수 있습니다. 예를 들어 Encounter E와 Claim C가 있고 C의 생성 날짜가 2020-04-01이며 C는 encounter 참조를 통해 E를 참조하고 E는 practitioner 참조를 통해 P를 참조하는 경우 Practitioner?_has:Encounter:practitioner:_has:Claim:encounter:created=eq2020-04-01Practitioner P와 일치시킵니다.

검색결과에 추가 리소스 포함

_include_revinclude 매개변수는 검색결과에 쿼리와 직접 일치하는 리소스('기본 결과')와 관련된 추가 리소스('포함된 리소스')를 포함하도록 요청합니다. 이러한 매개변수를 사용하면 이러한 추가 리소스를 개별적으로 검색하기 위한 일련의 요청보다 더 효율적입니다. 검색에서 반환된 searchset 번들에서 이 매개변수로 추가된 리소스는 entry.search.mode = include로 표시되어 entry.search.mode = match가 있는 기본 결과와 구분됩니다.

_include를 사용하여 포함하면 기본 결과로 참조되는 리소스가 추가되고 _revinclude를 사용하여 역으로 포함하면 기본 결과를 참조하는 리소스가 추가됩니다. 따를 참조는 검색 매개변수의 이름으로 지정되며, 검색 매개변수로 사용할 수 있는 참조 필드만 이 방법으로 사용할 수 있습니다.

_include_revinclude의 매개변수 형식은 동일하며 :으로 구분된 2~3개의 값을 사용합니다. 첫 번째 값은 참조의 출처인 리소스 유형이고, 두 번째 값은 검색 매개변수 이름이며, 선택사항인 세 번째 값은 참조가 둘 이상의 유형을 가리킬 수 있는 경우 리소스 유형을 하나의 유형으로 제한합니다.

예를 들면 다음과 같습니다.

  • MedicationRequest?_include=MedicationRequest:subjectMedicationRequest 리소스를 검색하고 반환되는 각 리소스에 대해 FHIR 사양에 정의된 대로 Group 또는 Patient일 수 있는 subject 참조의 대상도 반환합니다.
  • MedicationRequest?_include=MedicationRequest:subject:Patient는 비슷하지만 Patient 리소스에 대한 subject 참조만 반환합니다.
  • MedicationRequest?_revinclude=Provenance:targetMedicationRequest 리소스를 검색하고 반환되는 각 리소스에 대해 Provenancetarget 참조가 일치하는 리소스를 나타내는 Provenance 리소스도 반환합니다.

:iterate 한정자로 인해 _include가 재귀적으로 평가됩니다. 이 한정자는 포함된 결과에서 참조의 추가 레이어를 따르거나 다른 Observation을 참조하는 Observation:derived-from과 같은 재귀 구조를 따를 수 있습니다. 재귀 수준은 제한되어 있습니다.

예를 들면 다음과 같습니다.

  • Observation?_include:iterate=Observation:derived-from:ObservationObservation 리소스를 검색하고 일치하는 Observation 리소스 및 포함된 리소스 등에서 파생된 참조를 재귀적으로 따릅니다.
  • MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agentMedicationRequest를 검색하고 이 결과 집합에 있는 target과 함께 Provenance 리소스를 포함한 다음 Provenance 리소스의 agent 매개변수를 통해 참조되는 리소스도 포함합니다.

와일드 카드(*)는 검색 매개변수로 사용할 수 있는 모든 참조가 포함되어야 함을 나타냅니다. * 와일드 카드를 _include의 첫 번째이자 유일한 인수로만 사용하거나 표준 _include의 검색 매개변수 이름 대신 사용할 수 있습니다. 여기서 선택사항인 세 번째 값은 원래 동작과 같이 리소스 유형을 단일 유형으로 제한합니다.

예를 들면 다음과 같습니다.

  • Observation?_include=*Observation 리소스를 검색하고 각 리소스에 대해 참조된 모든 리소스도 반환합니다.
  • Observation?_include=Observation:*은 앞의 예시와 같습니다.
  • MedicationRequest?_include=MedicationRequest:*:Patient는 각 MedicationRequest 리소스의 Patient 리소스에 대한 모든 참조를 반환합니다.

포함된 리소스는 중복 삭제되므로 여러 참조를 통해 찾더라도 결과 페이지 내에서 리소스의 복사본 하나만 반환됩니다. 동일한 결과가 포함된 리소스는 기본 결과와 관련된 결과의 각 페이지에 반환됩니다.

검색결과에 표시되는 필드 제한

_elements 매개변수를 사용하면 클라이언트가 불필요한 데이터를 생략하여 응답의 크기를 줄이기 위해 각 검색 결과에 대해 필드의 하위 집합만 반환하도록 요청할 수 있습니다. 이 매개변수는 쉼표로 구분된 리소스의 기본 요소 이름 목록을 허용합니다(예: Patient?_elements=identifier,contact,link). 이러한 필드와 하위 요소만 반환된 리소스에 포함됩니다. 이 매개변수로 변경한 응답의 리소스는 SUBSETTEDmeta.tag 값을 포함하여 불완전함을 나타냅니다.

Cloud Healthcare API에는 _elements와 비슷한 리소스 필드의 사전 정의된 하위 집합을 제공하는 _summary 매개변수에 대한 지원이 제한되어 있습니다.

  • _summary=texttext, id, meta 최상위 필드만 반환합니다.
  • _summary=datatext 필드를 제거하고 다른 모든 필드를 반환합니다.