IV.後端基礎操作

10 FHIR Search

https://www.hl7.org/fhir/search.html

今天的部分滿重要的，講FHIR的search方法如何使用，有哪些東西可以用

因為這個文件的內容範圍非常大，不可能在一篇之內全部講完，細節請自行點進去看。

這個文件其實大致上就是說明使用者該如何透過RESTful API跟FHIR Server溝通的方式，
也可以說是一個比較粗略的FHIR API文件，

因為FHIR本身的結構設計，FHIR Server可以視為是一個儲存FHIR文件的資料庫，自然需要有方法能夠將儲存於內部的資料提取出來，

除了直接存取底層的SQL資料庫外，在正常的Client與Server關係間，能夠使用的大約也就是API了，

結合昨天所提到的Postman，看完今天的文章後，可以開始實際測試一下該如何與FHIR Server溝通，

先前有提過Bundle中有一個Type叫做Searchset，這個Bundle Type是FHIR Server在使用者發出Search請求時會回覆的FHIR Resource，

因為本身是Bundle的緣故，Bundle內含的entry都是由使用者發出Search請求的條件中吻合的Resource構成，

以概觀來看，Search的使用方法如下：

 GET | [base]/?parameter(statement)
 
其中[base]為目標FHIR Server的URL位址，
在這之中，Search Parameter可以大概分為兩類：

 1. 全域(global)參數    
 2. 特定Resource內的屬性項參數
 
 還有一類是
 3.Search Result修飾參數，但這並不會是主要的搜尋參數
 
以下會說明各項內容，
值得注意的是，FHIR本身也有將Search Parameter以Resource的方式實作，有興趣的可以看看。
https://www.hl7.org/fhir/searchparameter.html

 1. 全域(global)參數：
  對應3.2.1.8.1 Standard Parameters - Parameters for all resources
  
  這個分類主要是對應所有Resource都共有的屬性項，雖然並不是每個Resource內都一定會必填上某些欄位，
  但在概括尋找共通屬性時非常好用。
  
  _content  -> 查詢某些關鍵詞是否在這個Resource內，
   GET [base]/Observation?_content=cancer OR metastases OR tumor
   
  _filter   -> 進階查詢，將屬性項搜尋內置，一個parameter搜尋多個條件
   GET [base]/Observation?_filter=code eq http://loinc.org|1234-5 and subject.name co "peter"
   
  _has   -> 連鎖搜尋，跨Resource尋找指定的條件
   GET [base]/Patient?_has:Observation:patient:code=1234-5
   
  _id    -> 找符合Resource ID的Resource
   GET [base]/Observation?_id=101
   
  _in    -> 找某個Group中有的Resource ID
   GET [base]/Patient?_in=CareTeam/103
   
  _language  -> 找某個有標註其Resource.language欄位的Resource
   GET [base]/Questionnaire?_language=es
   
  _lastUpdated -> 找符合條件的上一次更新Resource的日期
   GET [base]/Observation?_lastUpdated=gt2010-10-01
   
  _list   -> 找符合條件的被參照Resource
   GET [base]/?_list=101
   
  _profile  -> 找Resource中參照的Profile的Resource
   GET [base]/Observation?_profile=http://hl7.org/fhir/StructureDefinition/bp
   
  _query   -> Named Queries，要事先定義parameter才能使用
   GET [base]/Patient?_query=current-high-risk&ward=1A
  
  _security  -> 找Resource.meta.security的欄位
   GET [base]/Observation?_security=http://terminology.hl7.org/CodeSystem/v3-Confidentiality|R
   
  _source   -> 找Resource.meta.source的欄位
   GET [base]/Patient?_source=http://example.com/Organization/123
   
  _tag   -> 找Resource.meta.tag的欄位
   GET [base]/Observation?_tag=http://terminology.hl7.org/ValueSet/v3-SeverityObservation|H
   
  _text   -> 找Resource中有該文本的Resource
   GET [base]/Observation?_text=cancer OR metastases OR tumor
   
  _type   -> 找指定Resource Type中符合條件的Resource
   GET [base]/?_type=Observation,Condition&patient=Patient/123

 2. 特定Resource內的屬性項參數
  這一項就比較容易懂了，其實就是去搜尋符合指定Resource中某個屬性項的值的Resource

   GET [base]/Observation?code=loinc|1234-1
   GET [base]/DocumentReference?contenttype=text/xml

 
 特定的operator可以見文章內3.2.1.5.6與3.2.1.6.3，Table可以看3.2.1.11
 如gt(greater than), below, eq(equal)等。
 
 3. 修飾搜尋結果的參數
  內容放在3.2.1.7，這個參數是要求FHIR Server在回傳搜尋結果時將結果的內文做一定程度的整理或型態改變，
  如_summary、_graph、_sort等，需要注意的是，這一類型的參數在一次搜尋需求中只能出現唯一一個。
 

會在這裡特別把Search拿出來講的原因是，FHIR是由下至上的資料堆砌方法，一個高層資源必由底層資源們構成，相互引用，

透過Search的操作，實作者可以把多個不同的Resource透過RESTful API與FHIR Server溝通，取得這些不同的Resource再組合成Bundle，

實際上這篇Search.html實在是太長了，很多時候筆者也是面對需要使用的條件搜尋才來找該怎麼使用他。

在FUME與HAPI FHIR協作的過程中，Search的行為也會一再的被提及起來使用，有興趣的讀者在看完今天的文章後

可以利用Postman到FHIR的公開伺服器搜尋測試
https://hapi.fhir.org/

另外補充一下，在FHIR的文件裡面到處充斥著MUST REQUIRED SHALL等關鍵全大寫詞，這個是RFC 2119 的五級要求標準

FHIR 要求發布者/實作者遵守這些層級的規範，標準化實作上的限制。

MUST / REQUIRED / SHALL
SHOULD / RECOMMENDED
MAY / OPTIONAL
SHOULD NOT / NOT RECOMMENDED
MUST NOT / SHALL NOT

明天開始會正式進入 FHIR Server的介紹，事實上有非常多家公司都有實作FHIR Server，本文會以開源的HAPI FHIR作為主要使用演示。