このページでは、projects.locations.datasets.fhirStores.fhir.search メソッドで利用できる高度なクエリ機能を使用して FHIR リソースを検索する方法について説明します。このガイドは、FHIR リソースの検索の内容をすでに理解していることを前提としています。
文字列検索修飾子
文字列検索は、標準の Unicode NFC 形式への畳み込みによって大文字と小文字およびアクセントを区別しない接頭辞一致にデフォルトで設定されます。句読点と余分な空白は無視されます。
次の修飾子を使用できます。
:containsは、文字列内に指定された値を持つリソースに一致します。たとえば、name:contains=eveはEvelynとSeverineに一致します。:exactは、大文字と小文字、アクセントを含む文字列全体と一致します。たとえば、name:exact=Eveはeveや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 の医療的に重要な浮動小数点値はすべて、格納された値の精度を記録する Decimal や Quantity などの型で表されます。例外として、単純な整数を使用するフィールド（シーケンス内の位置を表すためなど）がいくつかあり、これらのフィールドでの検索は完全数値一致です。
次の接頭辞は、シングルトン値に対する数値比較に適用されます。接頭辞が指定されていない場合、デフォルトは eq です。
eq: 等しい。保存された正確な値は、パラメータ値の精度で定義された範囲内にあるne: 等しくない、eqの逆gt: 保存された正確な値が正確なパラメータ値よりも大きいlt: 保存された正確な値が正確なパラメータ値よりも小さいge: 保存された正確な値が正確なパラメータ値と同じかそれよりも大きいle: 保存された正確な値が正確なパラメータ値と同じかそれよりも小さい
日付値には、値の具体性レベル（1 年、1 か月、1 日）に基づく暗黙的な範囲があります。Range や Period などの他のデータ型には、明示的な上限と下限があります。範囲の比較には次の接頭辞が適用されます。接頭辞が指定されていない場合、デフォルトは eq です。
eq: 等しい、パラメータ値の範囲にターゲットの範囲全体が含まれるne: 等しくない、eqの逆gt: 大きい、パラメータ値の上の範囲がターゲットの範囲と重なっているlt: 小さい、パラメータ値の下の範囲がターゲットの範囲と重なっているge: 大きいまたは同じle: 小さいまたは同じsa: パラメータ値の範囲がターゲット範囲の後で始まるeb: パラメータ値の範囲がターゲット範囲の前で終了する
トークン検索
トークン検索パラメータは、値が任意の文字列ではなく、命名システムのエンティティである場合に適用されます。トークン パラメータの文字列一致は完全一致です。
ほとんどのトークン検索は、code 値の取得元の命名システムを示す URI である system を含む複雑なデータ型に適用されます。これらの検索では、次の値の構文がサポートされます。
[parameter]=[code]は、systemに関係なくcode値と一致します。[parameter]=[system]|[code]は、指定されたsystemとcodeの両方に一致する必要があります。systemの値が空の場合、[parameter]=|[code]はcodeと一致します。[parameter]=[system]|は、指定されたsystem値を持つ任意のcodeと一致します。
代替トークン検索機能をトリガーするいくつかの修飾子があります。
:notはトークン検索の一致条件を否定します。:textは、コード値自体ではなく、コードに関連付けられたtextフィールドまたはdisplayフィールドで文字列検索を行います（完全一致ではありません）。:aboveは[system]|[code]という形式のパラメータのみを受け取り、リソース内のコードがクエリ パラメータを含むリソースと一致します。この修飾子を使用するには、指定されたsystemがCodeSystemリソースとして FHIR ストアに存在する必要があります。: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 xyzはxyzと 1 つ以上のabcdefghiを含むリソースに一致します。-は NOT 演算子です。たとえば、abc -defはabcを含むがdefを含まないリソースと一致します。
照合は単語全体に基づいており、部分文字列または英数字以外の一致は含まれません。単語の順序は関係ありません。一致する単語は、リソース内の複数のフィールドに分散している可能性があります。
パラメータ _text は、人が読める形式のリソース コンテンツの概要を含めることを目的とした Narrative フィールドに対してのみ同じタイプの一致を実行します。Cloud Healthcare API はこの概要を自動的に生成しませんが、リソースの作成または更新時にこのデータがクライアントによって入力された場合、_text 検索パラメータをサポートします。
複合検索パラメータ
複数のクエリ パラメータを使用して検索する場合、個々の検索パラメータを AND で結合すると意図しない結果と一致することがあります。複合検索パラメータは、この問題に対処するための特殊なタイプの検索パラメータです。
たとえば、Observation リソースの component フィールドには複数の値を含めることができ、各値には code と value のペアが含まれます。Observation?component-code=8867-4&component-value-quantity=lt50 の検索は、code が 8867-4 のコンポーネントを 1 つ含み、value が 50 未満の異なるコンポーネントを含むリソースに一致します。この検索を使用して、同じコンポーネント内でこれら 2 つの値に一致するように制限することはできません。
複合検索パラメータは、他の 2 つの検索パラメータを組み合わせ、両方のパラメータが一致する必要があるネストレベルを定義する新しいパラメータを定義します。クエリでは、2 つの値は $ によって結合されます。たとえば、Observation には複合パラメータ component-code-value-quantity があり、これにより前の例を Observation?component-code-value-quantity=8867-4$lt50 で検索して 1 つのコンポーネントに制限できます。これらのパラメータは FHIR 仕様で定義されており、検索パラメータのすべての組み合わせに対応しているわけではありません。
複合検索パラメータでは修飾子を使用できません。
すべての検索パラメータと同様に、Cloud Healthcare API でサポートされる複合パラメータに関する情報は、機能ステートメントまたは FHIR 適合性宣言で確認できます。
チェーン検索
チェーン検索を使用すると、クエリのコンテキスト内で参照を走査できます。チェーン検索の基本的な構文は次のとおりです。
[reference parameter]:[resource type].[inner search parameter]=[inner value]
参照パラメータが 1 つのリソースタイプのみを参照する場合は、:[resource
type] を省略できます。
[reference parameter].[inner search parameter]=[inner value]
たとえば、Observation には Group、Device、Patient、または Location を参照する参照検索パラメータ subject があります。名前が「Joe」で始まる Patient の subject を持つ Observations を検索するには、Observation?subject:Patient.name=Joe を検索します。
クエリに複数のチェーン パラメータがある場合、各チェーンは個別に評価されます。たとえば、Patient?general-practitioner.name=Joe&general-practitioner.address-country=Canada は、「Joe」という名前とカナダの住所という 2 つの general-practitioner 参照を持つ Patient と一致します。これらの句をグループ化してカナダの Joe のみに一致させる構文はありません。
Cloud Healthcare API は、単一レベルのチェーン検索をサポートしています。複数レベルのチェーンを使用するチェーン検索を行うことはできません。
リバース チェーン検索
リバース チェーン検索は、そのリソースを参照する他のリソースの条件に基づいてリソースを照合します。リバース チェーン検索の構文は次のとおりです。
_has:[resource type]:[reference parameter]:[search parameter]=[value]
たとえば、Appointment リソースには Patient リソースを参照する検索パラメータ patient があります。日付が 2020-04-01 の Appointment リソースに参照されるすべての 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-01 は Practitioner P に一致します。
検索結果に追加リソースを含める
_include パラメータと _revinclude パラメータは、クエリに直接一致するリソース（「プライマリ結果」）に関連する追加リソース（「包含リソース」）を検索結果に含むようリクエストします。これらのパラメータを使用すると、これらの追加リソースを繰り返し個別に取得するよりも効率的です。検索から返された searchset バンドルでは、これらのパラメータによって追加されたリソースに entry.search.mode = include のフラグが付けられ、entry.search.mode = match を持つプライマリ結果と区別されます。
_include による順方向の包含では、メインの結果により参照されるリソースとリソース バージョンが追加され、_revinclude による逆方向の包含ではメインの結果を参照するリソースが追加されます。後に続く参照は検索パラメータの名前で指定され、検索パラメータとして使用できる参照フィールドのみがこの方法で使用できます。
_include と _revinclude のパラメータ形式は同じで、2 つまたは 3 つの値を : で区切ります。最初の値は参照元のリソースタイプ、2 番目の値は検索パラメータ名、3 番目の値は省略可能で、参照が複数のタイプを指す可能性がある場合にリソースタイプを 1 種類に制限します。
例:
MedicationRequest?_include=MedicationRequest:subjectはMedicationRequestリソースを検索し、返される各リソースについて、FHIR 仕様で定義されているGroupまたはPatientの可能性があるsubject参照のターゲットも返します。MedicationRequest?_include=MedicationRequest:subject:Patientも同様ですが、Patientリソースへのsubject参照のみを返します。MedicationRequest?_revinclude=Provenance:targetはMedicationRequestリソースを検索し、返された各リソースについて、Provenanceのtarget参照が一致するリソースを参照するProvenanceリソースも返します。
修飾子 :iterate を指定すると、_include が反復的に評価されます。この修飾子は、追加された結果から参照の追加レイヤをたどるか、Observation:derived-from が別の Observation を参照するなどの再帰構造に従う場合があります。再帰の深さには制限があります。
例:
Observation?_include:iterate=Observation:derived-from:ObservationはObservationのリソースを検索し、一致するObservationリソースからの派生参照、続いて包含リソースからの派生参照などを再帰的にたどります。MedicationRequest?_revinclude=Provenance:target&_include:iterate=Provenance:agentはMedicationRequestを検索し、この結果セットにtargetを持つProvenanceリソースを含め、さらにこれらのProvenanceリソースのagentパラメータで参照されるリソースも含めます。
ワイルドカード * は、検索パラメータとして使用可能なすべてのリファレンスを含める必要があることを示します。* ワイルドカードは、_include 内の最初で唯一の引数、あるいは標準の _include の検索パラメータ名の代わりに使用できます。オプションの 3 つ目の値は、元の動作と同様に、リソースタイプを 1 つのタイプに制限します。
例:
Observation?_include=*はObservationリソースを検索し、各リソースが参照するすべてのリソースも含めて返します。Observation?_include=Observation:*は、上記と同等です。MedicationRequest?_include=MedicationRequest:*:Patientは、各MedicationRequestリソースが参照するすべてのPatientリソースを返します。
包含リソースは重複除去されるため、複数の参照で見つかった場合でも、結果のページ内にリソースのコピーが 1 つだけ返されます。プライマリ結果が関連する結果の各ページで、同じ包含リソースが返されます。
検索結果に返されるフィールドの制限
_elements パラメータを使用すると、クライアントは検索結果ごとにフィールドのサブセットのみが返されるようリクエストできるため、不要なデータを省略してレスポンスのサイズを小さくできます。パラメータには、リソース内のベース要素名のカンマ区切りのリスト（Patient?_elements=identifier,contact,link など）を指定できます。これらのフィールドとその子のみが、返されるリソースに含まれます。このパラメータによって変更されたレスポンス内のリソースには、SUBSETTED の meta.tag 値が含まれ、不完全であることを示します。
Cloud Healthcare API でサポートされている _summary パラメータは制限されており、_elements と同様のリソース フィールドの事前定義されたサブセットが提供されます。
_summary=textは、text、id、およびmetaのトップレベル フィールドのみを返します。_summary=dataはtextフィールドを削除し、他のすべてのフィールドを返します。