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

[アーティクル]
06/08/2023

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

警告

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

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

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

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

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

POST {{FHIR URL}}/$reindex 

{ 

“resourceType”: “Parameters”,  

“parameter”: [] 

}

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

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

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
    }
  ]
}

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

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

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 seperated.}"
    }
] 

}

Note

インデックス再作成ジョブの状態をチェックしたり、ジョブを取り消したりするには、インデックス再作成 ID が必要です。これは、 "id" 応答で "parameter" 返される値に含まれるです。上記の例では、インデックス再作成ジョブの 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}

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

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

注意

大規模なデータセットでは、インデックス再作成ジョブが数日にわたって実行されることも珍しくありません。リソース数 3,000 万のデータベースで、データベース全体のインデックス再作成に 10 万 RU で 4 ～ 5 日を要することが確認されています。

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

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

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

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

次のステップ

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

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

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

Share via

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

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

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

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

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

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

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

次のステップ

その他のリソース

Share via

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

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

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

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

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

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

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

次のステップ

その他のリソース

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