Skip to content

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/TerminologyReindex.read
- system/TerminologyReindex.write
- user/TerminologyReindex.read
- user/TerminologyReindex.write
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

alt text

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

curl --location 'https://demo.kodjin.com/fhir/$terminology-reindex' \
--header 'Content-Type: application/json' \
--data '{
    "resourceType": "Parameters",
    "parameter": [
        {
            "name": "resourceType",
            "valueString": "ValueSet"
        }
    ]
}'

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