Operation $terminology-reindex
In FHIR Search Parameters are dynamic. That means that in addition to the standard Search Parameters custom ones can be added. To support this functionality Kodjin uses index tables. After the new Search Parameter is added, the indexes should be rebuilt.
The $terminology-reindex operation rebuilds the indexes for terminology resources like CodeSystem, ValueSet, ConceptMap, and NamingSystem.
This method requires the following TerminologyReindex scopes:
- system/kodjin/$terminology-reindex
- user/kodjin/$terminology-reindex
You can read more about smart-on-FHIR scopes on SMART on FHIR Authorization page
$terminology-reindex operation is a resource-consuming operation that might affect the performance of Kodjin. Therefore you should take this fact into account while starting the reindex operation.
Endpoints
POST [fhir_base]/fhir/$terminology-reindex
GET [fhir_base]/fhir/terminology-reindex/[id]
Query parameters
| In Parameters: | |||
|---|---|---|---|
| Name | Cardinality | Type | Documentation |
| resourceType | 0..* | string | Type of the terminology resource (CodeSystem, ValueSet, NamingSystem, ConceptMap) |
| resourceId | 0..* | string | ID of the terminology resource |
| Response: | |||
|---|---|---|---|
| Name | Cardinality | Type | Documentation |
| id | 1..1 | string | ID of the terminology-reindex. By this ID it is possible to get terminology-reindex to check the status of the reindex process. |
| workerId | 0..1 | string | is a technical id of the worker, that could help during debug process |
| insertedAt | 1..1 | valueDateTime | a timestamp when terminology-reindex was inserted to the DB |
| updatedAt | 1..1 | valueDateTime | a timestamp when terminology-reindex was updated. During the reindex process this resource is continiously updating, so that the owner of the process could know the status, state of reindex and see the number of updated resources |
| status | 1..1 | valueCode | Status of the reindex process. new, processing, failed, completed |
| request | backboneElement | the whole request which created current reindex process | |
| request.resourceType | 0..* | string | resourceType from the request |
| request.resourceId | 0..* | string | resourceID from the request |
| state | backboneElement | the state of reindexing parameters | |
| state.stateByResourceType.resourceType | 1..* | string | the terminology resource type (CodeSystem, NamingSystem, ValueSet, ConceptMap). |
| state.stateByResourceType.resourceId | 1..* | string | the terminology resource ID |
| state.stateByResourceType.count | 1..1 | valueInteger | the number of reindexed resources in DB type. |
| state.stateByResourceType.error | 0..1 | string | error in reindexing process |
POST interaction starts the reindex process. Reindexing is asynchronous, and the response will include the process ID. You can use this ID to check the status of the process.
GET interaction retrieves the status and all additional information of the reindex process using its ID. The response for both POST and GET interactions are the same.
Statuses of terminology-reindex operation:
| Status | Description |
|---|---|
| new | Reindex is just created and is waiting to be processed. |
| processing | Reindex is being processed. During this status state of reindex is being updated continiously. If reindex process failed it will be automatically restarted by the service from the failed point. |
| completed | Reindex was completed. The count shows the total number of reindexed resources, error shows if there were errors during reindex, id is for reindex resources by ID |
| error | In case reindex process is failed and will not be started again, then status will be set to Error. In the "state" there will be an error message(s) and number of reindexed resources if any were reindexed. Depending on error message(s) you should fix an error or repeat reindex process |
After $terminology-reindex is finished and has status completed it could require some time for Terminology service to update it's search parameters cache before responding with an appropriate search result.
Examples
You can choose resources for reindexing by next filters:
- By resource type
- By resource logical ID
Each parameter is processed independently. The most common case is to reindex all collections of terminology resources, but if you don't need all of them to be reindexed right now or you want to check how your newly created SearchParameter works, you could reindex resources by ID.
Here are some examples of running reindex and result of this process:
- Example to reindex all ValueSets in Kodjin DB.
As a result of this example all ValueSet resources will be reindexed
Example - reindex all ValueSets
{
"resourceType": "Parameters",
"parameter": [
{
"name": "id",
"valueString": "961b4674-666d-4994-a50a-7fa244635484"
},
{
"name": "workerId",
"valueString": "24682034-98b5-44b5-bf08-f8230827a8da"
},
{
"name": "insertedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "updatedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "status",
"valueCode": "new"
},
{
"name": "request",
"part": [
{
"name": "resourceType",
"valueString": "ValueSet"
}
]
},
{
"name": "state",
"part": [
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "ValueSet"
},
{
"name": "count",
"valueInteger": 0
}
]
}
]
}
]
}
{
"resourceType": "Parameters",
"parameter": [
{
"name": "id",
"valueString": "961b4674-666d-4994-a50a-7fa244635484"
},
{
"name": "workerId",
"valueString": "24682034-98b5-44b5-bf08-f8230827a8da"
}
{
"name": "insertedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "updatedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "status",
"valueCode": "completed"
},
{
"name": "request",
"part": [
{
"name": "resourceType",
"valueString": "ValueSet"
}
]
},
{
"name": "state",
"part": [
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "ValueSet"
},
{
"name": "count",
"valueInteger": 1097
}
]
}
]
}
]
}
- Example for parameters with name resourceType and resourceId.
All parameters are processed independently. So if you add CodeSystem to parameter with name resourceType there is no need to add CodeSystem to parameter with name resourceId.
As a result of this example all CodeSystems and NamingSystem resources will be reindexed and additionally CodeSystem with id="123" will be reindexed for the second time.
Example - reindex CodeSystem
curl --location 'https://demo.kodjin.com/fhir/$terminology-reindex' \
--header 'Content-Type: application/json' \
--data '{
"resourceType": "Parameters",
"parameter": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "resourceType",
"valueString": "NamingSystem"
},
{
"name": "resourceId",
"valueString": "CodeSystem/123"
}
]
}'
{
"resourceType": "Parameters",
"parameter": [
{
"name": "id",
"valueString": "961b4674-666d-4994-a50a-7fa244635484"
},
{
"name": "workerId",
"valueString": "24682034-98b5-44b5-bf08-f8230827a8da"
},
{
"name": "insertedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "updatedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "status",
"valueCode": "new"
},
{
"name": "request",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "resourceType",
"valueString": "NamingSystem"
},
{
"name": "resourceId",
"valueString": "CodeSystem/123"
}
]
},
{
"name": "state",
"part": [
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "count",
"valueInteger": 0
}
]
},
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "NamingSystem"
},
{
"name": "count",
"valueInteger": 0
}
]
},
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "resourceId",
"valueString": "123"
}
{
"name": "count",
"valueInteger": 0
}
]
}
]
}
]
}
{
"resourceType": "Parameters",
"parameter": [
{
"name": "id",
"valueString": "961b4674-666d-4994-a50a-7fa244635484"
},
{
"name": "workerId",
"valueString": "24682034-98b5-44b5-bf08-f8230827a8da"
},
{
"name": "insertedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "updatedAt",
"valueDateTime": "2024-07-03T14:46:45.107453265Z"
},
{
"name": "status",
"valueCode": "processing"
},
{
"name": "request",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "resourceType",
"valueString": "NamingSystem"
},
{
"name": "resourceId",
"valueString": "CodeSystem/123"
}
]
},
{
"name": "state",
"part": [
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "count",
"valueInteger": 798
}
]
},
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "NamingSystem"
},
{
"name": "count",
"valueInteger": 18
}
]
},
{
"name": "stateByResourceType",
"part": [
{
"name": "resourceType",
"valueString": "CodeSystem"
},
{
"name": "resourceId",
"valueString": "123"
}
{
"name": "count",
"valueInteger": 1
}
]
}
]
}
]
}