本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # HealthLake 的 FHIR R4 搜尋參數 使用 FHIR [https://hl7.org/fhir/R4/http.html#search](https://hl7.org/fhir/R4/http.html#search)互動，根據一些篩選條件在 HealthLake 資料存放區中搜尋一組 FHIR 資源。您可以使用 `GET`或 `POST`請求來執行`search`互動。對於涉及個人身分識別資訊 (PII) 或受保護醫療資訊 (PHI) 的搜尋，建議使用`POST`請求，因為 PII 和 PHI 會新增為請求內文的一部分，並在傳輸中加密。 **注意** 本章所述的 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 中支援的搜尋參數類型。 **支援的搜尋參數類型** | 搜尋參數 | Description | | --- | --- | | \$1id | 資源 ID （非完整 URL) | | \$1lastUpdated | 上次更新日期。伺服器可自行決定邊界精確度。 | | \$1tag | 依資源標籤搜尋。 | | \$1profile | 搜尋標記設定檔的所有資源。 | | \$1安全性 | 搜尋套用至此資源的安全標籤。 | | \$1source | 搜尋資源的來源。 | | \$1text | 搜尋資源的敘述。 | | createdAt | 搜尋自訂擴充功能 createdAt。 | **注意** 下列搜尋參數僅支援 2023 年 12 月 9 日之後建立的資料存放區：\$1security， \$1source， \$1text， createdAt。 下表顯示如何根據指定資源類型的指定資料類型修改查詢字串的範例。為了清楚起見，範例欄中的特殊字元尚未編碼。若要成功進行查詢，請確定查詢字串已正確編碼。 **搜尋參數範例** | 搜尋參數類型 | 詳細資訊 | 範例 | | --- | --- | --- | | Number | 搜尋指定資源中的數值。觀察到重要的數字。有效數字的數量依搜尋參數值在 中是特定的，前導零除外。允許比較字首。 | `[parameter]=100` `[parameter]=1e2` `[parameter]=lt100` | | 日期/DateTime | 搜尋特定日期或時間。預期的格式是 `yyyy-mm-ddThh:mm:ss[Z\|(+\|-)hh:mm]`，但可能會有所不同。 接受下列資料類型：`date`、`dateTime`、`Period`、 `instant`和 `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` | | String | 以區分大小寫的方式搜尋一系列字元。 同時支援 `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。只有 2023 年 12 月 9 日之後建立的資料存放區Date才支援依 排序。最多支援 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`的資源類型，然後使用 `_include` 指定也要傳回該診斷`subject`的 。在 `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 參考的 Practitioner。此修飾詞適用於 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`：傳回資源 （基本定義） 中標示為「摘要」的所有支援元素。 + `text`：僅傳回 'text'、'id'、'meta' 元素，以及僅傳回頂層強制性元素。 + `data`：傳回除了「文字」元素以外的所有部分。 + `false`：傳回資源的所有部分 （多個） 在單一搜尋請求中， `_summary=text`無法與 `_include`或 `_revinclude` 搜尋參數結合。 **Example – 取得資料存放區中病患資源的「文字」元素。** ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_summary=text ``` `_elements` 在搜尋查詢`_elements`中使用 允許請求特定的 FHIR 資源元素。傳回的資源會在 meta.tag `'SUBSETTED'`中標示為 ，表示資源不完整。 `_elements` 參數包含以逗號分隔的基本元素名稱清單，例如在資源的根層級定義的元素。只有列出的元素才會傳回。如果`_elements`參數值包含無效的元素，伺服器會忽略它們並傳回強制性元素和有效的元素。 `_elements` 不適用於包含的資源 （搜尋模式為 的傳回資源`include`)。 在單一搜尋請求中， `_elements`無法與`_summary`搜尋參數結合。 **Example – 取得 HealthLake 資料存放區中病患資源的「識別符」、「作用中」、「連結」元素。** ``` GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient?_elements=identifier,active,link ``` `_total` 在搜尋查詢`_total`中使用 會傳回符合所請求搜尋參數的資源數量。HealthLake 會在搜尋`Bundle.total`回應的 中傳回相符資源的總數 （傳回的搜尋模式為 的資源`match`)。 `_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`。如果搜尋參數是指巢狀元素，則不支援此搜尋參數進行排序。例如，搜尋資源類型的 'name' 病患參考具有 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，其是指病患名稱為 Peter 的 病患。** ``` 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 | String | | ：包含 | String | | ：not | 權杖 | | ：text | 權杖 | | ：識別符 | 參考資料 | | ：以下 | URI | ## 支援的搜尋比較器 您可以使用搜尋比較器來控制搜尋中相符項目的性質。您可以在搜尋數字、日期和數量欄位時使用比較器。下表列出 HealthLake 支援的搜尋比較器及其定義。 **支援的搜尋比較器** | 搜尋比較程式 | Description | | --- | --- | | eq | 資源中 參數的值等於提供的值。 | | ne | 資源中 參數的值不等於提供的值。 | | gt | 資源中 參數的值大於提供的值。 | | lt | 資源中 參數的值小於提供的值。 | | ge | 資源中 參數的值大於或等於提供的值。 | | le | 資源中 參數的值小於或等於提供的值。 | | sa | 資源中 參數的值會在提供的值之後啟動。 | | eb | 資源中 參數的值會在提供的值之前結束。 | ## HealthLake 不支援 FHIR 搜尋參數 HealthLake 支援所有 FHIR 搜尋參數，但下表所列的參數除外。如需 FHIR 搜尋參數的完整清單，請參閱 [FHIR 搜尋參數登錄檔。](https://hl7.org/fhir/R4/searchparameter-registry.html) **不支援的搜尋參數** | | | | --- |--- | | Bundle-composition | Location-near | | 套件識別符 | Consent-source-reference | | Bundle-message | 合約患者 | | Bundle-type | 資源內容 | | Bundle-timestamp | 資源查詢 |