This document discusses using combo search index parameters in FHIR data modeling to improve search performance. It describes how transaction builder API constructs FHIR transaction bundles and how custom search index parameters can be used with it. A real-world example is provided where an organization's name, tax ID, and NPI are combined into a unique identifier to prevent duplicate resources from being created. The document stresses the importance of up-front data modeling, especially when ingesting data concurrently, to define identifiers and custom search parameters that leverage combo search indexes and ensure uniqueness.

1. Up-front Design Considerations in FHIR Data Modeling
Combo Search Index Parameters in Practice
2022-03-10

2. Welcome
Presenter:
Reza Abolhassani, MSc(eHealth), MSCA
FHIR Data Modeler and Standards Developer
Credit:
Laurie MacDougall Sookraj (Tech/Team Lead)
Dmitry Polyakov (Software Developer)
Kevin Dougan (Senior Software Developer)

3. Main Goal
To be specific:
● Not sharing a piece of software or tool BUT a technique of using:
○ TransactionBuilder API which is used to construct FHIR transaction bundles
○ Custom Search Index Parameters(CSIP) which is used to for better performance of search parameters
○ Both are Smile CDR features

4. TransactionBuilder API
It is part of JavaScript Execution Environment (JEE) in Smile CDR platform:
● TransactionBuilder API is used to construct FHIR transaction bundles
○ Useful for batching a group of related FHIR operations into a single atomic unit (e.g., capture patient
encounter data points using Patient, Encounter, Organization, Location, Practitioner, etc.)
○ updateConditional(resource).onToken(parameter, system, value)
○ createConditional(resource).onToken(parameter, system, value)

5. Example
● Create this patient unless a patient already exists

6. A Real Scenario (NALC)
● Organization Resource
○ Some organizations with the same TaxID or lack of NPI for many
○ Name+’-’+TaxId+’-’+NPI
● Practitioner Resource
○ Some practitioners with the same TaxID or lack of NPI for many
○ First Name+’-’+ Last Name+’-’+TaxId+‘-’+ NPI

7. A Real Scenario (NALC)
● Organization (CARIN BB)
● Added Name because some orgs are missing data for ids above
● Name+’-’+TaxId+’-’+NPI will end up with unique resources!

8. So What?
● When it comes to multi-threading and concurrency (e.g., data ingestion)
● Chances are to have several transactions including createConditional or
updateConditional executed at the same time !!! (from experience)
● It will end up with duplicate resources with the same identifier
● Duplicate resources for reference information:
○ Organization, Practitioner, Location
● It could be really challenging!!! (especially in PROD)
● Here is where using CSIP technique comes into play!
● It will accommodate the normal behavior of TransactionBuilder API
methods

9. Search Parameters
The important notes of Search Parameters:
● Used to search resources in a FHIR repository.
○ Resources filter by search parameters.
● Named paths (FHIR Path) within resources that are indexed by the system
○ Patient.gender
● Once defined, we can use them to find matching resources
○ GET [base]/Patient?gender=male

10. Default Search Parameters
The FHIR specification defines a set of built-in parameterst:

11. Managing Search Parameters
In a relational FHIR Storage module, each search parameter is represented by
a SearchParameter resource in the database
Using the FHIR Endpoint
1) GET http://localhost:8000/DEFAULT/SearchParameter?base=Patient
2) GET http://localhost:8000/DEFAULT/SearchParameter/individual-gender
3) …

12. Custom Search Parameters
We can create your own Search Parameters in Smile CDR in order to index
fields and extensions that are not indexed by default.

13. Combo Search Index Parameters
HAPI FHIR and Smile CDR define a special type of SearchParameter called a
Combo Search Index Parameter (CSIP) that is used to index a combination
of parameters together in a single database table
1) http://localhost:8000/Patient?family=smith&birthdate=2021-01-
01&gender=http://hl7.org/fhir/administrative-gender|male
2) This generally works well, but can lead to performance issues
3) Using a Combo Search Index Parameter avoids unnecessary database joining.
4) Optionally, Smile CDR can also enforce uniqueness for the values of the
parameters.

14. Example

15. Up-front Data Modeling Considerations!
● It is critical! for example when concurrency comes into play in Data
Ingestion with Channel Import!
● Profile the data that comes in to understand it first ( big chunk of real
data!)
● Design a specific simple or composite identifier to maintain uniqueness!
● Design a specific Custom Search Parameter and its associated Combo
Search Index Parameter (Take advantage of the optional extension)
● Then, we can use this specific identifier along with the system URL
○ updateConditional(resource).onToken(parameter, system, value)
○ createConditional(resource).onToken(parameter, system, value)

16. Q&A