このページでは、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 つ以上のabc
def
ghi
を含むリソースに一致します。-
は 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 のみに一致させる構文はありません。
リバース チェーン検索
リバース チェーン検索は、そのリソースを参照する他のリソースの条件に基づいてリソースを照合します。リバース チェーン検索の構文は次のとおりです。
_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
フィールドを削除し、他のすべてのフィールドを返します。