Azure API for FHIR でのインデックス再作成ジョブの実行

[アーティクル]
10/04/2024

重要

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 です。

Azure API for FHIR® に検索パラメーターまたは並べ替えパラメーターがあり、まだインデックスが作成されていない場合があります。このシナリオは、独自の検索パラメーターを定義する場合に重要です。検索パラメーターは、インデックスが付けられるまでは検索で使用できません。この記事では、インデックス再作成ジョブを実行して、FHIR サービスデータベースの検索パラメーターにインデックスを付ける方法について説明します。

警告

作業を始める前に、この記事全体に目を通すことは重要です。インデックス再作成ジョブには、非常に高いパフォーマンスが要求される可能性があります。この記事では、インデックス再作成ジョブを調整および制御する方法に関するオプションを説明します。

インデックス再作成ジョブの実行方法

インデックス再作成ジョブは、FHIR サービスデータベース全体および特定のカスタム検索パラメーターに対して実行できます。

FHIR サービスデータベース全体でインデックス再作成ジョブを実行する

インデックス再作成ジョブを実行するには、要求本文で JSON 形式のParameters リソースを使用して、次のPOST呼び出しを使用します。

POST {{FHIR URL}}/$reindex 

{ 

“resourceType”: “Parameters”,  

“parameter”: [] 

}

インデックス再作成ジョブに割り当てられているリソースを調整する必要がない場合は、 "parameter": [] フィールドを空白のままにします (図参照)。

要求が成功した場合は、次の例に示すように、 201 Created 状態コードに加えて、応答の Parameters リソースを受け取ります。

HTTP/1.1 201 Created 
Content-Location: https://{{FHIR URL}}/_operations/reindex/560c7c61-2c70-4c54-b86d-c53a9d29495e 

{
  "resourceType": "Parameters",
  "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
  "meta": {
    "versionId": "\"4c0049cd-0000-0100-0000-607dc5a90000\""
  },
  "parameter": [
    {
      "name": "id",
      "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
    },
    {
       "name": "lastModified",
       "valueDateTime": "2023-06-08T04:52:44.0974408+00:00"
    },
    {
       "name": "queuedTime",
       "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
    },
    {
       "name": "totalResourcesToReindex",
       "valueDecimal": 0.0
    },
    {
       "name": "resourcesSuccessfullyReindexed",
       "valueDecimal": 0.0
    },
    {
       "name": "progress",
       "valueDecimal": 0.0
    },
    {
       "name": "status",
       "valueString": "Queued"
    },
    {
       "name": "maximumConcurrency",
       "valueDecimal": 3.0
    },
    {
        "name": "queryDelayIntervalInMilliseconds",
        "valueDecimal": 500.0
    },
    {
        "name": "maximumNumberOfResourcesPerQuery",
        "valueDecimal": 100.0
    }
  ]
}

特定のカスタム検索パラメーターに対してインデックス再作成ジョブを実行する

特定のカスタム検索パラメーターに対してインデックス再作成ジョブを実行するには、次の POST 呼び出しを使用し、要求本文で JSON 形式の Parameters リソースを使用します。

POST {{FHIR_URL}}/$reindex 
content-type: application/fhir+json
{ 

"resourceType": "Parameters",  

"parameter": [
    {
      "name": "targetSearchParameterTypes",
      "valueString": "{url of custom search parameter. In case of multiple custom search parameters, url list can be comma separated.}"
    }
] 

}

Note

インデックス再作成ジョブの状態を確認したり、ジョブを取り消したりするには、インデックス再作成 ID が必要です。これは、応答で返される"parameter"値に含まれる"id"です。前の例では、インデックス再作成ジョブの ID は 560c7c61-2c70-4c54-b86d-c53a9d29495e。

インデックス再作成ジョブを確認する方法

インデックス再作成ジョブを開始したら、次の呼び出しを使用してジョブの状態を確認できます。

GET {{FHIR URL}}/_operations/reindex/{{reindexJobId}

次が応答の例です。

{
    "resourceType": "Parameters",
    "id": "560c7c61-2c70-4c54-b86d-c53a9d29495e",
    "meta": {
        "versionId": "138087"
    },
    "parameter": [
        {
            "name": "id",
            "valueString": "560c7c61-2c70-4c54-b86d-c53a9d29495e"
        },
        {
            "name": "startTime",
            "valueDateTime": "2023-06-08T04:54:53.2943069+00:00"
        },
        {
            "name": "endTime",
            "valueDateTime": "2023-06-08T04:54:54.4052272+00:00"
        },
        {
            "name": "lastModified",
            "valueDateTime": "2023-06-08T04:54:54.4053002+00:00"
        },
        {
            "name": "queuedTime",
            "valueDateTime": "2023-06-08T04:52:44.0974406+00:00"
        },
        {
            "name": "totalResourcesToReindex",
            "valueDecimal": 2.0
        },
        {
            "name": "resourcesSuccessfullyReindexed",
            "valueDecimal": 2.0
        },
        {
            "name": "progress",
            "valueDecimal": 100.0
        },
        {
            "name": "status",
            "valueString": "Completed"
        },
        {
            "name": "maximumConcurrency",
            "valueDecimal": 3.0
        },
        {
            "name": "resources",
            "valueString": "{{LIST_OF_IMPACTED_RESOURCES}}"
        },
        {
            "name": "resourceReindexProgressByResource (CountReindexed of Count)",
            "valueString": "{{RESOURCE_TYPE:REINDEXED_COUNT OF TOTAL_COUNT}}"
        },
        {
            "name": "searchParams",
            "valueString": "{{LIST_OF_SEARCHPARAM_URLS}}h"
        },
        {
            "name": "queryDelayIntervalInMilliseconds",
            "valueDecimal": 500.0
        },
        {
            "name": "maximumNumberOfResourcesPerQuery",
            "valueDecimal": 100.0
        }
    ]
}

応答に次の情報が表示されます。

totalResourcesToReindex: このジョブでインデックスを再作成するリソースの合計数が含まれます。
resourcesSuccessfullyReindexed: このジョブで既にインデックスが再作成されているリソースの合計数。
progress: ジョブの完了率のインデックスを再作成します。 resourcesSuccessfullyReindexed/totalResourcesToReindex x 100 として計算されます。
status: インデックス再作成ジョブがキューに登録、実行中、完了、失敗、または取り消された場合の状態。
resources: インデックス再作成ジョブの影響を受けたすべてのリソースの種類を一覧表示します。
resourceReindexProgressByResource (CountReindexed of Count): リソースの種類ごとに、合計カウントのインデックスを再作成したカウントを提供します。特定のリソースの種類のインデックス再作成がキューに登録されている場合は、Count のみが提供されます。
searchParams: インデックス再作成ジョブの影響を受けた検索パラメーターの URL を一覧表示します。

インデックス再作成ジョブの削除

インデックス再作成ジョブをキャンセルする必要がある場合は、削除呼び出しを使用して、インデックス再作成ジョブの ID を指定します。

Delete {{FHIR URL}}/_operations/reindex/{{reindexJobId}

パフォーマンスに関する考慮事項

インデックス再作成ジョブには、非常に高いパフォーマンスが要求される可能性があります。データベースでのインデックス再作成ジョブの実行方法を管理するのに役立つ調整コントロールがいくつか実装されています。

Note

大規模なデータセットでは、インデックス再作成ジョブが数日にわたって実行されることも珍しくありません。リソースが 30,000,000 個のデータベースの場合、データベース全体のインデックスを再作成するのに 100,000 要求ユニット (RU) で 4 ~ 5 日かかったことに気付きました。

使用可能なパラメーター、既定値、および推奨される範囲を示す表を次に示します。これらのパラメーターを使用して、プロセスを高速化する (コンピューティング使用量を増やす) か、低速化する (コンピューティング使用量を減らす) ことができます。たとえば、トラフィックの少ない時間にインデックス再作成ジョブを実行し、コンピューティングを増やして、より迅速に実行できます。また、この設定を使用して、コンピューティングの使用率を低くし、バックグラウンドで数日実行することもできます。

パラメーター	説明	既定値	使用可能な範囲
QueryDelayIntervalInMilliseconds	インデックス再作成ジョブの実行中に開始されるリソースの各バッチ間の遅延。数値を小さくするとジョブの速度が上がり、値が大きいほど遅くなります。	500 ミリ秒 (0.5 秒)	50 ～ 500000
MaximumResourcesPerQuery	インデックスを再作成するリソースのバッチに含めるリソース数の上限。	100	1 ～ 5000
MaximumConcurrency	一度に実行するバッチの数。	1	1 ～ 10
targetDataStoreUsagePercentage	インデックス再作成ジョブに使用するデータストアの比率を指定できます。たとえば、50% を指定すると、Azure Cosmos DB で使用可能な RU の最大 50% がインデックス再作成ジョブに使用されるようになります。	なし。つまり、最大 100% を使用できます。	0 ～ 100

上記のパラメーターのいずれかを使用する場合は、インデックス再作成ジョブを開始するときにパラメーターリソースに渡すことができます。

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "maximumConcurrency",
      "valueInteger": "3"
    },
    {
      "name": "targetDataStoreUsagePercentage",
      "valueInteger": "20"
    },
    {
      "name": "queryDelayIntervalInMilliseconds",
      "valueInteger": "1000"
    },
    {
      "name": "maximumNumberOfResourcesPerQuery",
      "valueInteger": "1"
    }
  ]
}

次のステップ

この記事では、インデックス再作成ジョブを開始する方法について説明しました。インデックス再作成ジョブを必要とする新しい検索パラメーターを定義する方法については、次の記事を参照してください。

カスタム検索パラメーターの定義

Note

FHIR® は HL7 の登録商標であり、HL7 の許可を得て使用しています。

次の方法で共有

Azure API for FHIR でのインデックス再作成ジョブの実行

インデックス再作成ジョブの実行方法

FHIR サービスデータベース全体でインデックス再作成ジョブを実行する

特定のカスタム検索パラメーターに対してインデックス再作成ジョブを実行する

インデックス再作成ジョブを確認する方法

インデックス再作成ジョブの削除

パフォーマンスに関する考慮事項

次のステップ

フィードバック

その他のリソース

次の方法で共有

Azure API for FHIR でのインデックス再作成ジョブの実行

インデックス再作成ジョブの実行方法

FHIR サービス データベース全体でインデックス再作成ジョブを実行する

特定のカスタム検索パラメーターに対してインデックス再作成ジョブを実行する

インデックス再作成ジョブを確認する方法

インデックス再作成ジョブの削除

パフォーマンスに関する考慮事項

次のステップ

フィードバック

その他のリソース

FHIR サービスデータベース全体でインデックス再作成ジョブを実行する