Azure API for FHIR での検索の概要
重要
Azure API for FHIR は、2026 年 9 月 30 日に廃止されます。 移行戦略に従って、その日までに Azure Health Data Services FHIR® サービスに切り替えてください。 Azure API for FHIR が廃止されたため、2025 年 4 月 1 日以降、新しいデプロイは許可されません。 Azure Health Data Services FHIR サービス は、お客様が他の Azure サービスへの統合を使用して、FHIR、DICOM、および MedTech サービスを管理できるようにする、進化したバージョンの Azure API for FHIR です。
高速ヘルスケア相互運用性リソース (FHIR) の仕様では、FHIR リソースの検索の基礎が定義されています。 この記事では、FHIR でリソースを検索する際の重要な側面について説明します。 FHIR リソースの検索の詳細については、HL7 FHIR 仕様の 検索 に関するページを参照してください。 この記事では、検索構文の例を示します。 各検索は、通常、 https://<FHIRSERVERNAME>.azurewebsites.netの URL を持つ FHIR サーバーに対して行われます。 この例では、この URL にプレースホルダー {{FHIR_URL}} を使用します。
FHIR 検索は、特定のリソースの種類、指定されたコンパートメント、すべてのリソースに対して実行できます。 FHIR で検索を実行する最も簡単な方法は、GET 要求を使用する方法です。 たとえば、データベース内のすべての患者をプルする場合は、次の要求を使用できます。
GET {{FHIR_URL}}/Patient
POSTを使用して検索することもできます。これは、クエリ文字列が長い場合に便利です。 POST を使用して検索するには、検索パラメーターをフォーム本文として送信できます。 これにより、クエリ文字列では表示と理解が困難になる可能性がある、より長く複雑な一連のクエリ パラメーターが可能になります。
検索要求が成功した場合は、種類が searchsetの FHIR バンドル応答を受け取ります。 検索が失敗した場合は、 OperationOutcome でエラーの詳細を見つけ、検索が失敗した理由を理解するのに役立ちます。
以降のセクションでは、検索に関連するさまざまな側面について説明します。 これらの詳細を確認したら、Azure API for FHIR で実行できる検索の例があるサンプル ページを参照してください。
検索パラメーター
検索は、リソースのさまざまな属性に基づいています。 これらの属性は検索パラメーターと呼ばれます。 各リソースには、定義された検索パラメーターのセットがあります。 検索パラメーターを正しく検索するには、データベースで検索パラメーターを定義してインデックスを作成する必要があります。
各検索パラメーターには、定義済みのデータ型があります。 次の表は、さまざまなデータ型のサポートの概要を示しています。
警告
現在、チェーン検索で Azure API for FHIR で _sort を使用する場合に問題があります。 詳細については、オープンソースの問題 #2344を参照してください。 この問題は、2021 年 12 月のリリース中に解決される予定です。
| 検索パラメーターの種類 | Azure API for FHIR | Azure Health Data Services の FHIR サービス | コメント |
|---|---|---|---|
| 数値 | はい | はい | |
| 日付 | はい | あり | |
| string | はい | はい | |
| token | はい | はい | |
| reference | はい | はい | |
| 複合 | 部分的 | Partial | サポートされている複合型の一覧については、この記事の後半で説明します。 |
| quantity | はい | はい | |
| uri | はい | はい | |
| スペシャル | いいえ | いいえ |
一般的な検索パラメーター
すべてのリソースに適用される一般的な検索パラメーターがあります。 これらは、Azure API for FHIR 内でのサポートと共に、次の一覧にあります。
| 一般的な検索パラメーター | Azure API for FHIR | Azure Health Data Services の FHIR サービス | コメント |
|---|---|---|---|
| _id | はい | はい | |
| _lastUpdated | はい | はい | |
| _tag | はい | はい | |
| _type | はい | はい | |
| _security | はい | はい | |
| _profile | はい | はい | |
| _has | 部分的 | はい | _hasのサポートは、Azure API for FHIR の MVP と、Azure Cosmos DB によってサポートされる OSS バージョンにあります。 詳細については、次のチェーン セクションを参照してください。 |
| _query | いいえ | いいえ | |
| _filter | いいえ | いいえ | |
| _list | いいえ | いいえ | |
| _text | いいえ | いいえ | |
| _content | いいえ | いいえ |
リソース固有のパラメーター
Azure API for FHIR では、FHIR 仕様で定義されているほぼすべてのリソース固有の検索パラメーターがサポートされています。 サポートされていない唯一の検索パラメーターは、次のリンクから入手できます。
FHIR Capability Statement で、次の要求を使用して、検索パラメーターの現在のサポートを確認することもできます。
GET {{FHIR_URL}}/metadata
capability ステートメントで検索パラメーターを表示するには、 CapabilityStatement.rest.resource.searchParam に移動して各リソースの検索パラメーターを確認し、 CapabilityStatement.rest.searchParam してすべてのリソースの検索パラメーターを検索します。
Note
Azure API for FHIR では、FHIR 仕様で定義されていない検索パラメーターを自動的に作成またはインデックス付けしません。 ただし、独自の 検索パラメーターを定義するためのサポートが提供されています。
複合検索パラメーター
複合検索を使用すると、値ペアに対して検索できます。 たとえば、人物が身長 60 インチという測定値を検索する場合は、測定の 1 つのコンポーネントに高さのコードおよび 60 の値が含まれている必要があります。 観察結果には、値 60 と身長のコードに該当するエントリが、異なるコンポーネント セクションに含まれている可能性がありますが、体重 60 と身長 48 が格納された測定結果を取得したくはありません。
Azure API for FHIR では、次の検索パラメーターの種類のペアリングがサポートされています。
- 参照、トークン
- トークン、日付
- トークン、数字、数字
- トークン、数量
- トークン、文字列
- トークン、トークン
詳細については、HL7 複合検索パラメーターに関するページを参照してください。
Note
複合検索パラメーターでは、FHIR 仕様に基づく修飾子はサポートされていません。
修飾子とプレフィックス
修飾子を使用すると、検索パラメーターを変更できます。 次の表は、Azure API for FHIR のすべての FHIR 修飾子とそのサポートの概要を示しています。
| 修飾子 | Azure API for FHIR | Azure Health Data Services の FHIR サービス | コメント |
|---|---|---|---|
| :missing | はい | はい | |
| :exact | はい | はい | |
| :contains | はい | はい | |
| text: | はい | はい | |
| :type (reference) | はい | はい | |
| :not | はい | はい | |
| :below (uri) | はい | はい | |
| :above (uri) | はい | はい | |
| :in (token) | いいえ | いいえ | |
| :below (token) | いいえ | いいえ | |
| :above (token) | いいえ | いいえ | |
| :not-in (token) | いいえ | いいえ |
特定の順序 (数値、日付、数量) を持つ検索パラメーターの場合は、パラメーターのプレフィックスを使用すると、一致を見つけるのに役立ちます。 Azure API for FHIR では、すべてのプレフィックスがサポートされています。
検索結果のパラメーター
返されるリソースを管理するために、使用できる検索結果パラメーターがあります。 各検索結果パラメーターの使い方の詳細については HL7 の Web サイトを参照してください。
| 検索結果のパラメーター | Azure API for FHIR | Azure Health Data Services の FHIR サービス | コメント |
|---|---|---|---|
| _elements | はい | はい | |
| _count | はい | はい | _count は 1,000 リソースに制限されています。 1000 より大きい値を設定すると、1000 のみが返され、バンドルで警告が返されます。 |
| _include | はい | はい | 含まれる項目は 100 に制限されています。 Azure Cosmos DB の PaaS および OSS の _include には、:iterate サポート (#2137) は含まれていません。 |
| _revinclude | はい | はい | 含まれる項目は 100 に制限されています。 Azure Cosmos DB の PaaS と OSS の_revincludeには、:iterate のサポート (#2137) が含まれていません。 また、不適切な要求 #1319 に対する正しくない状態コードがあります |
| _summary | はい | はい | |
| _total | 部分的 | Partial | _total=none および _total=accurate |
| _sort | 部分的 | Partial | sort=_lastUpdated は、Azure API for FHIR と FHIR サービスでサポートされています。 2021 年 4 月 20 日以降に作成された Azure API for FHIR および OSS Azure Cosmos DB データベースでは、姓、生年月日、臨床日で並べ替えがサポートされています。 |
| _contained | いいえ | いいえ | |
| _containedType | いいえ | いいえ | |
| _score | いいえ | 無効 |
Note
既定 _sort では、コードは昇順で並べ替えられます。 プレフィックス '-' を使用して、降順で並べ替えることができます。 さらに、FHIR サービスと Azure API for FHIR では、一度に 1 つのフィールドでのみ並べ替えることができます。
既定では、Azure API for FHIR は厳密な処理に設定されています。 これは、不明なパラメーターまたはサポートされていないパラメーターがサーバーによって無視されることを意味します。 厳密な処理を使用する場合は、Prefer ヘッダーを使用して handling=strict を設定できます。
チェーンおよびリバース チェーン検索
チェーン検索を使用すると、別のリソースによって参照されるリソースの検索パラメーターを使用して検索できます。 たとえば、患者の名前が Jane である結果を探す場合は、次のコマンドを使用します。
GET {{FHIR_URL}}/Encounter?subject:Patient.name=Jane.
同様に、リバース チェーン検索を実行できます。 これにより、リソースを参照する他のリソースの条件を指定して、リソースを取得できます。 チェーン検索とリバース チェーン検索のその他の例については、FHIR 検索の例に関するページを参照してください。
Note
Azure API for FHIR と Azure Cosmos DB によってサポートされるオープン ソースでは、チェーン検索とリバース チェーン検索に必要な各サブクエリで返される項目が 1000 項目のみになるという制限があります。 見つかった項目が 1000 を超える場合は、次のエラー メッセージが表示されます。"チェーンされた式のサブクエリでは 1000 を超える結果を返すことができません。より限定的な条件を使用してください。" クエリを正常に実行するには、探している情報についてより具体的にする必要があります。
改ページ位置の自動修正
前述のように、検索の結果はページングされたバンドルです。 既定では、検索は 1 ページあたり 10 件の結果を返しますが、 _countを指定することで、これを増減できます。 バンドル内には、検索の現在の結果を含む自己リンクがあります。 追加の一致がある場合、バンドルには次へのリンクが含まれます。 次へのリンクを引き続き使用して、結果の後続のページを取得できます。 _count は 1,000 アイテム以下に制限されています。
バンドル内の次のリンクには、継続トークンのサイズ制限が 3 KB です。 ヘッダー x-ms-documentdb-responsecontinuationtokenlimitinkbを使用して、継続トークンのサイズを 1 KB から 3 KB に柔軟に調整できます。
現時点では、Azure API for FHIR はバンドル内の次へのリンクのみをサポートし、最初、最後、または前へのリンクはサポートされていません。
次のステップ
検索の基本について学習しました。さまざまな検索パラメーター、修飾子、およびその他の FHIR 検索シナリオを使用して検索する方法の詳細については、検索サンプル ページを参照してください。
Note
FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。