기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# HealthLake에 대한 FHIR R4 검색 파라미터
FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search) 상호 작용을 사용하여 일부 필터 기준에 따라 HealthLake 데이터 스토어에서 FHIR 리소스 세트를 검색합니다. 상호 `search` 작용은 `GET` 또는 `POST` 요청을 사용하여 수행할 수 있습니다. 개인 식별 정보(PII) 또는 보호 대상 건강 정보(PHI)가 포함된 검색의 경우 PII 및 PHI가 `POST` 요청 본문의 일부로 추가되고 전송 중에 암호화되므로 요청을 사용하는 것이 좋습니다.
**참고**
이 장에 설명된 FHIR `search` 상호 작용은 의료 데이터 교환을 위한 HL7 FHIR R4 표준을 준수하도록 구축되었습니다. HL7 FHIR 서비스의 표현이므로 AWS CLI 및 AWS SDKs 통해 제공되지 않습니다. 자세한 내용은 **FHIR R4 RESTful API 설명서**[https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)의 섹션을 참조하세요.
Amazon Athena를 사용하여 SQL을 사용하여 HealthLake 데이터 스토어를 쿼리할 수도 있습니다. 자세한 내용은 통합을 참조하세요.
HealthLake는 다음과 같은 FHIR R4 검색 파라미터의 하위 집합을 지원합니다. 자세한 내용은 [HealthLake에 대한 FHIR R4 검색 파라미터](#reference-fhir-search-parameters) 단원을 참조하십시오.
## 지원되는 검색 파라미터 유형
다음 표에는 HealthLake에서 지원되는 검색 파라미터 유형이 나와 있습니다.
**지원되는 검색 파라미터 유형**
| 검색 파라미터 | 설명 |
| --- | --- |
| \$1id | 리소스 ID(전체 URL 아님) |
| \$1lastUpdated | 마지막으로 업데이트된 날짜입니다. 서버는 경계 정밀도에 대한 재량이 있습니다. |
| \$1태그 | 리소스 태그로 검색합니다. |
| \$1profile | 프로필로 태그가 지정된 모든 리소스를 검색합니다. |
| \$1보안 | 이 리소스에 적용된 보안 레이블을 검색합니다. |
| \$1소스 | 리소스의 출처를 검색합니다. |
| \$1텍스트 | 리소스의 서술을 검색합니다. |
| createdAt | createdAt 사용자 지정 확장을 검색합니다. |
**참고**
다음 검색 파라미터는 2023년 12월 9일 이후에 생성된 데이터 스토어에만 지원됩니다. \$1security, \$1source, \$1text, createdAt.
다음 표에는 지정된 리소스 유형에 대해 지정된 데이터 유형을 기반으로 쿼리 문자열을 수정하는 방법의 예가 나와 있습니다. 명확성을 위해 예제 열의 특수 문자는 인코딩되지 않았습니다. 쿼리에 성공하려면 쿼리 문자열이 제대로 인코딩되었는지 확인합니다.
**검색 파라미터 예제**
| 파라미터 유형 검색 | 세부 정보 | 예제 |
| --- | --- | --- |
| 숫자 | 지정된 리소스에서 숫자 값을 검색합니다. 중요한 수치가 관찰됩니다. 유효 자릿수는 선행 0을 제외하고 검색 파라미터 값에 따라에 고유합니다. 비교 접두사는 허용됩니다. | `[parameter]=100` `[parameter]=1e2` `[parameter]=lt100` |
| 날짜/DateTime | 특정 날짜 또는 시간을 검색합니다. 예상 형식은 `yyyy-mm-ddThh:mm:ss[Z\|(+\|-)hh:mm]` 이지만 다를 수 있습니다. `date`, , `dateTime`, 및 데이터 형식을 허용합니다`instant``Period``Timing`. 검색에서 이러한 데이터 유형을 사용하는 자세한 내용은 **FHIR R4 RESTful API 설명서**의 [날짜를](https://www.hl7.org/fhir/search.html#date) 참조하세요. 비교 접두사는 허용됩니다. | `[parameter]=eq2013-01-14` `[parameter]=gt2013-01-14T10:00` `[parameter]=ne2013-01-14` |
| 문자열 | 대소문자를 구분하여 문자 시퀀스를 검색합니다. `HumanName` 및 `Address` 유형을 모두 지원합니다. 자세한 내용은 **FHIR R4 설명서**의 [HumanName 데이터 유형](https://www.hl7.org/fhir/datatypes.html#HumanName) 항목과 [`Address` 데이터 유형](https://www.hl7.org/fhir/datatypes.html#Address) 항목을 참조하세요. 고급 검색은 `:text` 한정자를 사용하여 지원됩니다. | `[base]/Patient?given=eve` `[base]/Patient?given:contains=eve` |
| 토큰 | 종종 한 쌍의 의료 코드 값과 비교하여 문자열에 대해 close-to-exact 일치하는 항목을 검색합니다. 대소문자 구분은 쿼리를 생성할 때 사용되는 코드 시스템에 연결됩니다.소비 기반 쿼리는 대소문자 구분과 관련된 문제를 줄이는 데 도움이 될 수 있습니다. 명확성을 위해 `\|`는 인코딩되지 않았습니다. | `[parameter]=[system]\|[code]`: 여기서 `[system]`는 코딩 시스템을 참조하고,는 해당 특정 시스템 내에 있는 코드 값을 `[code]` 참조합니다. `[parameter]=[code]`: 여기서 입력은 코드 또는 시스템과 일치합니다. `[parameter]=\|[code]`: 여기서 입력은 코드와 일치하며 시스템 속성에는 식별자가 없습니다. |
| 복합 | 한정자`$` 및 `,` 작업을 사용하여 단일 리소스 유형 내에서 여러 파라미터를 검색합니다. 비교 접두사는 허용됩니다. | `/Patient?language=FR,NL&language=EN` `Observation?component-code-value-quantity=http://loinc.org\|8480-6$lt60` `[base]/Group?characteristic-value=gender$mixed` |
| 수량 | 숫자, 시스템 및 코드를 값으로 검색합니다. 숫자는 필수이지만 시스템 및 코드는 선택 사항입니다. 수량 데이터 유형에 따라 다릅니다. 자세한 내용은 **FHIR R4 설명서**의 [수량](https://www.hl7.org/fhir/datatypes.html#Quantity)을 참조하세요. 다음과 같이 가정된 구문을 사용합니다. `[parameter]=[prefix][number]\|[system]\|[code]` | `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=5.4\|http://unitsofmeasure.org\|mg` `[base]/Observation?value-quantity=le5.4\|http://unitsofmeasure.org\|mg` |
| 레퍼런스 | 다른 리소스에 대한 참조를 검색합니다. | `[base]/Observation?subject=Patient/23` `test` |
| URI | 특정 리소스를 명확하게 식별하는 문자열을 검색합니다. | `[base]/ValueSet?url=http://acme.org/fhir/ValueSet/123` |
| 특별 | 통합된 의료 NLP 확장을 기반으로 검색합니다. |
## HealthLake에서 지원하는 고급 검색 파라미터
HealthLake는 다음과 같은 고급 검색 파라미터를 지원합니다.
| 이름 | 설명 | 예제 | 기능 |
| --- | --- | --- | --- |
| \$1include | 검색 요청에서 추가 리소스를 반환하도록 요청하는 데 사용됩니다. 대상 리소스 인스턴스에서 참조하는 리소스를 반환합니다. | Encounter?\$1include=Encounter:subject | |
| \$1revinclude | 검색 요청에서 추가 리소스를 반환하도록 요청하는 데 사용됩니다. 기본 리소스 인스턴스를 참조하는 리소스를 반환합니다. | Patient?\$1id=patient-identifier&\$1revinclude=Encounter:patient | |
| \$1summary | 요약을 사용하여 리소스의 하위 집합을 요청할 수 있습니다. | Patient?\$1summary=text | 지원되는 요약 파라미터는 \$1summary=true, \$1summary=false, \$1summary=text, 입니다\$1summary=data. |
| \$1elements | 검색 결과에 리소스의 일부로 반환할 특정 요소 세트를 요청합니다. | Patient?\$1elements=identifier,active,link | |
| \$1total | 검색 파라미터와 일치하는 리소스 수를 반환합니다. | Patient?\$1total=accurate | \$1total=accurate,를 지원합니다\$1total=none. |
| \$1sort | 쉼표로 구분된 목록을 사용하여 반환된 검색 결과의 정렬 순서를 지정합니다. - 접두사는 쉼표로 구분된 목록의 모든 정렬 규칙에 사용하여 내림차순을 나타낼 수 있습니다. | Observation?\$1sort=status,-date | 유형별 필드 정렬을 지원합니다Number, String, Quantity, Token, URI, Reference. 정렬 기준 Date는 2023년 12월 9일 이후에 생성된 데이터 스토어에만 지원됩니다. 최대 5개의 정렬 규칙을 지원합니다. |
| \$1count | 검색 번들의 페이지당 반환되는 리소스 수를 제어합니다. | Patient?\$1count=100 | 최대 페이지 크기는 100입니다. |
| chaining | 참조된 리소스의 요소를 검색합니다. 는 연결된 검색을 참조된 리소스 내의 요소로 . 전달합니다. | DiagnosticReport?subject:Patient.name=peter | |
| reverse chaining (\$1has) | 리소스를 참조하는 리소스 요소를 기반으로 리소스를 검색합니다. | Patient?\$1has:Observation:patient:code=1234-5 | |
`_include`
검색 쿼리`_include`에서를 사용하면 지정된 추가 FHIR 리소스도 반환할 수 있습니다. `_include`를 사용하여 앞으로 연결된 리소스를 포함합니다.
**Example - `_include`를 사용하여 환자 또는 환자의 그룹을 찾으려면**
진단 코드를 지정하는 `Condition` 리소스 유형을 검색한 다음 해당 진단`subject`의 도 반환하도록 `_include` 지정합니다. `Condition` 리소스 유형에서 `subject`는 환자 리소스 유형 또는 그룹 리소스 유형을 나타냅니다.
명확성을 위해 예제의 특수 문자는 인코딩되지 않았습니다. 쿼리를 성공적으로 수행하려면 쿼리 문자열이 제대로 인코딩되었는지 확인합니다.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Condition?code=49727002&_include=Condition:subject
```
`_include:iterate` 수정자
`_include:iterate` 한정자를 사용하면 두 수준에서 참조된 리소스를 재귀적으로 포함할 수 있습니다. 예:
```
GET /ServiceRequest?identifier=025C0931195&_include=ServiceRequest:requester&_include:iterate=PractitionerRole:practitioner
```
는 ServiceRequest, 연결된 PractitionerRole(요청자 참조를 통해)을 반환한 다음 해당 PractitionerRole 재귀적으로 포함합니다. 이 한정자는 HealthLake의 모든 리소스 유형에 사용할 수 있습니다.
`_include=*` 수정자
`_include=*` 한정자는 검색 결과에서 직접 참조하는 모든 리소스를 자동으로 포함하는 와일드카드입니다. 예:
```
GET /ServiceRequest?specimen.accession=12345&_include=*
```
는 각 참조 경로를 개별적으로 지정할 필요 없이 참조하는 모든 리소스(예: 환자, 의사, 표본 등)와 함께 일치하는 ServiceRequest를 반환합니다. 이 한정자는 HealthLake의 모든 리소스 유형에 사용할 수 있습니다.
`_revinclude`
검색 쿼리`_revinclude`에서를 사용하면 지정된 추가 FHIR 리소스도 반환할 수 있습니다. `_revinclude`를 사용하여 역방향으로 연결된 리소스를 포함합니다.
**Example - `_revinclude`를 사용하여 특정 환자와 연결된 관련 상황 및 관찰 리소스 유형을 포함하려면**
이 검색을 수행하려면 먼저 `_id` 검색 파라미터에 식별자를 지정`Patient`하여 개인을 정의해야 합니다. 그런 다음 구조 `Encounter:patient` 및를 사용하여 추가 FHIR 리소스를 지정합니다`Observation:patient`.
명확성을 위해 예제의 특수 문자는 인코딩되지 않았습니다. 쿼리를 성공적으로 수행하려면 쿼리 문자열이 제대로 인코딩되었는지 확인합니다.
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/
Patient?_id=patient-identifier&_revinclude=Encounter:patient&_revinclude=Observation:patient
```
`_summary`
검색 쿼리`_summary`에서를 사용하면 사용자가 FHIR 리소스의 하위 집합을 요청할 수 있습니다. 다음 값 중 하나를 포함할 수 있습니다`true, text, data, false`. 다른 모든 값은 유효하지 않은 것으로 처리됩니다. 반환된 리소스는 meta.tag`'SUBSETTED'`에 로 표시되어 리소스가 불완전함을 나타냅니다.
+ `true`: 리소스의 기본 정의에서 'summary(요약)'로 표시된 지원되는 모든 요소를 반환합니다.
+ `text`: 'text', 'id', 'meta' 요소만 반환하고 최상위 필수 요소만 반환합니다.
+ `data`: 'text' 요소를 제외한 모든 부분을 반환합니다.
+ `false`: 리소스(들)의 모든 부분 반환
단일 검색 요청에서는 `_include` 또는 `_revinclude` 검색 파라미터와 결합할 수 `_summary=text` 없습니다.
**Example - 데이터 스토어에서 환자 리소스의 “텍스트” 요소를 가져옵니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_summary=text
```
`_elements`
검색 쿼리`_elements`에서를 사용하면 특정 FHIR 리소스 요소를 요청할 수 있습니다. 반환된 리소스는 meta.tag`'SUBSETTED'`에 로 표시되어 리소스가 불완전함을 나타냅니다.
`_elements` 파라미터는 리소스의 루트 수준에서 정의된 요소와 같이 쉼표로 구분된 기본 요소 이름 목록으로 구성됩니다. 나열된 요소만 반환됩니다. `_elements` 파라미터 값에 잘못된 요소가 포함된 경우 서버는 해당 요소를 무시하고 필수 요소와 유효한 요소를 반환합니다.
`_elements`는 포함된 리소스(검색 모드가 인 반환된 리소스)에는 적용되지 않습니다`include`.
단일 검색 요청에서는를 `_summary` 검색 파라미터와 결합할 수 `_elements` 없습니다.
**Example - HealthLake 데이터 스토어에서 환자 리소스의 “식별자”, “활성”, “링크” 요소를 가져옵니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_elements=identifier,active,link
```
`_total`
검색 쿼리`_total`에서를 사용하면 요청된 검색 파라미터와 일치하는 리소스 수가 반환됩니다. HealthLake는 검색 응답의에서 일치하는 리소스(검색 모드가 인 반환된 리소스`match`)`Bundle.total`의 총 수를 반환합니다.
`_total`는 `accurate`, `none` 파라미터 값을 지원합니다. `_total=estimate`는 지원되지 않습니다. 다른 모든 값은 유효하지 않은 것으로 처리됩니다. `_total`는 포함된 리소스(검색 모드가 인 반환된 리소스)에는 적용되지 않습니다`include`.
**Example - 데이터 스토어의 총 환자 리소스 수를 가져옵니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_total=accurate
```
`_sort`
검색 쿼리`_sort`에서를 사용하면 결과가 특정 순서로 정렬됩니다. 결과는 쉼표로 구분된 정렬 규칙 목록을 기준으로 우선 순위에 따라 정렬됩니다. 정렬 규칙은 유효한 검색 파라미터여야 합니다. 다른 모든 값은 유효하지 않은 것으로 처리됩니다.
단일 검색 요청에서 최대 5개의 정렬 검색 파라미터를 사용할 수 있습니다. 선택적으로 `-` 접두사를 사용하여 내림차순을 나타낼 수 있습니다. 서버는 기본적으로 오름차순으로 정렬됩니다.
지원되는 정렬 검색 파라미터 유형은 입니다`Number, String, Date, Quantity, Token, URI, Reference`. 검색 파라미터가 중첩된 요소를 참조하는 경우이 검색 파라미터는 정렬에 지원되지 않습니다. 예를 들어, 리소스 유형의 '이름'에 대한 검색 환자란 HumanName 데이터 형식이 중첩된 것으로 간주되는 Patient.name 요소를 말합니다. 따라서 '이름'을 기준으로 환자 리소스를 정렬하는 것은 지원되지 않습니다.
**Example - 데이터 스토어에서 환자 리소스를 가져오고 생년월일을 기준으로 오름차순으로 정렬합니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_sort=birthdate
```
`_count`
파라미터`_count`는 단일 페이지에서 반환해야 하는 리소스 수에 대한 서버 지침으로 정의됩니다.
최대 페이지 크기는 100입니다. 100보다 큰 값은 유효하지 않습니다. `_count=0`는 지원되지 않습니다.
**Example - 환자 리소스를 검색하고 검색 페이지 크기를 25로 설정합니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_count=25
```
`Chaining and Reverse Chaining(_has)`
FHIR에서 연결 및 역방향 연결은 상호 연결된 데이터를 얻는 보다 효율적이고 컴팩트한 방법을 제공하여 여러 개의 개별 쿼리에 대한 필요성을 줄이고 개발자와 사용자에게 데이터 검색을 더 편리하게 만듭니다.
재귀 수준이 100개 이상의 결과를 반환하는 경우 HealthLake는 4xx를 반환하여 데이터 스토어가 오버로드되어 여러 페이지 매김이 발생하지 않도록 보호합니다.
**Example - 연결 - 환자 이름이 피터인 환자를 참조하는 모든 DiagnosticReport를 가져옵니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/DiagnosticReport?subject:Patient.name=peter
```
**Example - 역방향 연결 - 환자 리소스를 가져옵니다. 여기서 환자 리소스는 관찰의 코드가 1234인 하나 이상의 관찰에 의해 참조되고 관찰은 환자 검색 파라미터의 환자 리소스를 참조합니다.**
```
GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_has:Observation:patient:code=1234
```
## 지원되는 검색 한정자
검색 한정자는 문자열 기반 필드에 사용됩니다. HealthLake의 모든 검색 한정자는 부울 기반 로직을 사용합니다. 예를 들어, 검색 결과에 포함할 수 `:contains` 있도록 더 큰 문자열 필드에 작은 문자열을 포함하도록 지정할 수 있습니다.
**지원되는 검색 한정자**
| 검색 한정자 | Type |
| --- | --- |
| :missing | 를 제외한 모든 파라미터 Composite |
| :exact | 문자열 |
| :포함 | 문자열 |
| :not | 토큰 |
| :text | 토큰 |
| :identifier | 레퍼런스 |
| :아래 | URI |
## 지원되는 검색 비교기
검색 비교기를 사용하여 검색에서 일치하는의 특성을 제어할 수 있습니다. 번호, 날짜 및 수량 필드를 검색할 때 비교기를 사용할 수 있습니다. 다음 표에는 HealthLake에서 지원하는 검색 비교기 및 해당 정의가 나열되어 있습니다.
**지원되는 검색 비교기**
| 검색 비교기 | 설명 |
| --- | --- |
| eq | 리소스의 파라미터 값이 제공된 값과 같습니다. |
| ne | 리소스의 파라미터 값이 제공된 값과 같지 않습니다. |
| gt | 리소스의 파라미터 값이 제공된 값보다 큽니다. |
| lt | 리소스의 파라미터 값이 제공된 값보다 작습니다. |
| ge | 리소스의 파라미터 값이 제공된 값보다 크거나 같습니다. |
| le | 리소스의 파라미터 값이 제공된 값보다 작거나 같습니다. |
| sa | 리소스의 파라미터 값은 제공된 값 이후에 시작됩니다. |
| eb | 리소스의 파라미터 값은 제공된 값보다 먼저 종료됩니다. |
## HealthLake에서 지원하지 않는 FHIR 검색 파라미터
HealthLake는 다음 표에 나열된 파라미터를 제외한 모든 FHIR 검색 파라미터를 지원합니다. FHIR 검색 파라미터의 전체 목록은 [FHIR 검색 파라미터 레지스트리를 참조하세요.](https://hl7.org/fhir/R4/searchparameter-registry.html)
**지원되지 않는 검색 파라미터**
| | |
| --- |--- |
| 번들 구성 | 위치-근접 |
| 번들 식별자 | Consent-source-reference |
| 번들 메시지 | 계약 환자 |
| 번들 유형 | Resource-content |
| 번들 타임스탬프 | 리소스 쿼리 |