Skip to main content

Upgrading a Legacy Repository to JSON Advanced SQL

Mappings

Although it is recommended to use the JSON Advanced SQL strategy when possible, the legacy strategy is still supported. This appendix provides details comparing the legacy strategy to the advanced strategy, and includes upgrade instructions for those currently using the legacy strategy who wish to take advantage of the additional features available with the advanced strategy.

Resource Repository Classes

The Resource Repository consists of the following architectural classes:

General Search Limitations

The JSON Advanced SQL strategy supports searching across multiple resource types within a compartment, as described in General Limitations.

The legacy strategy does not support searching across multiple resource types within a compartment.

Search Parameter Types

Date, Number, and Quantity

For searches using the date, number, or quantity search parameters, the JSON Advanced SQL strategy interprets the parameter value as an implicit range. In other words, a search for a quantity parameter with a value of 100 matches any values in the range [99.5, 100.5). This is in full conformance with the HL7® FHIR® specification for these search types (for example, http://hl7.org/fhir/search.html#dateOpens in a new tab).

The legacy strategy does not interpret values for these search parameter types as implicit ranges.

Reference

For searches that use a reference parameter to search for canonical references, the JSON Advanced SQL strategy supports the use of versions within the search, as described by the FHIR specification (https://hl7.org/fhir/search.html#versionsOpens in a new tab).

The legacy strategy does not support versioned searches for canonical references.

Search Modifiers

Modifier Legacy Strategy Support JSON Advanced SQL Support
:above Supported for uri Supported for URI
:below Supported for uri Supported for URI
:code-text Not supported Not supported
:contains Supported for strings Full support (string and URI)
:exact Supported for strings except for accented characters. For example, ?given:exact=Nino returns Patient with given name Niño Full support
:identifier Not supported Full support
:in Not supported Not supported
:iterate Limited to _include Full support
:missing Not supported Not supported
:not Not supported Not supported
:not-in Not supported Not supported
:of-type Not supported Full support
:text Not supported Supported for reference and token, not supported for string
:text-advanced Not supported Not supported
:[type] Full support Full support

Prefixes

Prefix Legacy Strategy Support JSON Advanced SQL Support
eq Full support Full Support
ne Full support Full support
gt Full support Full support
lt Full support Full support
ge Full support Full support
le Full support Full support
sa Not supported Full support
eb Not supported Full support
ap Not supported Full support

Search Result Parameters

Parameter Legacy Strategy Support JSON Advanced SQL Support
_contained Not supported Not supported
_count Full support as described in the official specificationOpens in a new tab Full support as described in the official specificationOpens in a new tab
_elements Full support as described in the official specificationOpens in a new tab Full support as described in the official specificationOpens in a new tab
_graph Not supported Not supported
_include Full support as described in the official specificationOpens in a new tab Full support as described in the official specificationOpens in a new tab
_maxresults Not supported Not supported
_revinclude Full support as described in the official specificationOpens in a new tab Full support as described in the official specificationOpens in a new tab
_score Not supported Not supported
_sort Full support as described in the official specificationOpens in a new tab Full support as described in the official specificationOpens in a new tab
_summary Support for _summary=count, _summary=data, and _summary=text. For details, see the official specificationOpens in a new tab. Support for _summary=count, _summary=data, and _summary=text. For details, see the official specificationOpens in a new tab.
_total Not supported Not supported

Migrating to JSON Advanced SQL

Follow these instructions to migrate from the legacy strategy to the JSON Advanced SQL strategy with no down time:

  1. Before you begin migrating from the legacy strategy to the JSON Advanced SQL strategy, perform these pre-migration steps:

    1. Evaluate your customizations of the existing repository that extends the legacy JSON strategy.

    2. Create a new strategy by extending these classes:

      • HS.FHIRServer.Storage.JsonAdvSQL.InteractionsStrategy

      • HS.FHIRServer.Storage.JsonAdvSQL.RepoManager

      • HS.FHIRServer.Storage.JsonAdvSQL.Interactions

    3. Migrate the relevant customizations from your legacy strategy to the new extended classes in your JSON Advanced SQL strategy.

    4. Validate that the new customizations work, and make needed fixes.

  2. Begin migration by creating a new repository. To do so, execute the following command in the terminal:

    set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Start(<endpoint_to_be_converted>, <new_strategy_key>)
    

    <new_strategy_key> is the strategy key associated with your extended JSON Advanced SQL classes. For more information about strategy keys, see Subclass Parameters. For information about additional optional parameters such as pNumWorkers and pWait, see HS.FHIRServer.Storage.JsonAdvSQL.ConvertJsonOpens in a new tab in the class reference.

    This command creates a new repository that uses existing Resource and Version tables as well as most other settings from the old repository. It creates new search tables and maps them to the Resource database if needed. It runs indexing of the new search tables in a background job.

  3. Wait for the background job indexing the new search tables to finish. Progress and completion of this job are logged in the interoperability event log.

  4. When the background job is complete, cut over from the old Json-based repository to the new one based on JsonAdvSQL, by executing the following command:

    set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Cutover(<endpoint_to_be_converted>,<service_id_of_new_endpoint>)
    

    The exact arguments to use in this command are included in the background job completion message in the interoperability event log.

    This command assocates the cspUrl with the new repository and disables the old one. Once this is complete, all new requests to that URL will be handled by the new JsonAdvSQL-based code and data structures. The search tables associated with the old repository will no longer be maintained.

  5. Optional. You can clean up unnecessary parts of the old Json-based endpoint by executing the following command:

    set status = ##class(HS.FHIRServer.Storage.JsonAdvSQL.ConvertJson).Cleanup(<old_repo_service_id>)
    

    The old repository service ID is included in the terminal output from the cut-over process.

    The following entities are cleaned up:

    • All HSFHIR search tables associated with the old endpoint

    • All HS_FHIRServer_Storage_JSON.SearchColumn rows associated with the old service key

    • The cached CapabilityStatement for the old endpoint

    • The ComparmentsIdx index from the resource table

    • The HS_FHIRServer.Repo where ID = <old_repo_service_id>

FeedbackOpens in a new tab