Snowstorm Terminology Server

Snowstorm is an open source terminology server built on top of Elasticsearch, specifically designed for high performance and enterprise scalability with special support for SNOMED CT. It provides standardized interfaces for querying and managing medical code systems.

Key features include:

• Support for multiple code systems (SNOMED CT, LOINC, ICD-10, ICD-10-CM, etc.).
• ECL v2.0 compliance.
• Multi-lingual search and content retrieval.
• Support for hosting multiple extensions alongside the International Edition of SNOMED CT.
• Full history support (contingent on full RF2 import).

The concepts-lookup index follows specific management rules:

• Automatic Triggers: The index is automatically rebuilt during content saves, RF2 imports, and branch rebasing. The lookup list is also updated during content promotion.
• Storage Model: The full list of referenced concepts is stored only at the CodeSystem (top-level) branch.
• Branch Deltas: Project and task branches store only the delta (additions and removals) rather than the full list.
• Version Control: Unlike other Snowstorm components, concepts-lookup does not use the standard version control mechanism (the version is replaced in the branch metadata).

Snowstorm's term-based search uses multiple prefix, any order, matching.

Key behaviors:

• Prefix Matching: You can use the first part of one or many words to match concept descriptions.
• No Fuzzy Matching: Terms must exactly match all prefixes provided. If a description does not match all prefixes in your search term, it will be excluded.
• Sorting: Results are primarily sorted by the length of the term matched. This ensures that the simplest/most general concept (the shortest match) appears at the top. For example, searching "pneumonia" will prioritize the most general concept before more specific variations.
• Refinement: If the desired concept is not in the top results, refine the search term (e.g., instead of "pneumonia", use "pneum bac" to find "Bacterial pneumonia").

A Snowstorm deployment consists of the Snowstorm application and an Elasticsearch cluster. When planning for load balancing and scaling, observe these two critical constraints:

1. Authoring Constraint: You can only have one Snowstorm instance for authoring SNOMED CT content. This is because asynchronous processes (such as classification and branch merge review) rely on in-memory state that cannot be shared across multiple instances.
2. Elasticsearch Scaling Constraint: You must adjust Elasticsearch index shards and replicas to match your node count. The default configuration (1 shard, 0 replicas) restricts each index to a single node. To utilize multiple nodes, you must increase these values.

The Snowstorm FHIR API returns either JSON or XML based on the Accept header in your request:

• If an Accept header is specified, the server respects it.
• If no Accept header is specified, the server defaults to JSON.
• When using a web browser (which often sends headers requesting both HTML and XML), the server detects the browser and defaults to JSON unless a format parameter is explicitly provided in the URL.

By default, a code system (like an extension) depends on a specific version of SNOMEDCT (International). Multiple code system dependencies allow an extension to additionally depend on one or more other code systems (e.g., LOINC) at specific releases.

This is used to:

• Author/translate content belonging to another dependent code system within the same environment by using a holding module to separate changes from the extension's core module.
• Ensure upgrade/version alignment by computing compatibility across the extension and additional code systems.
• Formally materialize relationships using the Module Dependency Reference Set (MDRS).

Warning: Reverting multiple dependencies is complex and involves re-homing content and re-running validations. Treat this as a deliberate design decision.

Snowstorm exposes two distinct API surfaces depending on your use case:

1. HL7 FHIR API (Recommended for implementers):

   • Implements the FHIR Terminology Module.
   • Designed for loose coupling between applications and the terminology service.
   • Supports SNOMED CT, LOINC, ICD-10, ICD-10-CM, and other code systems.
   • Provides a read-only mode for querying.

2. Specialist SNOMED CT API:

   • Used for management tasks of SNOMED CT code systems.
   • Powers the SNOMED International Browser.
   • Supports authoring SNOMED CT editions.

Snowstorm implements language-dependent character folding to handle diacritics (e.g., converting 'é' to 'e'). This behavior is tailored to the linguistic expectations of different languages:

• English: Diacritics are folded (e.g., searching for "deja" matches "Déjà vu").
• Danish: Diacritics are treated as distinct characters (e.g., searching for "Ångstrom" will not match "Ångstrøm").
• Swedish: Certain characters are not considered additional letters in the alphabet (e.g., searching for "Bronsted" will match "Brønsted-Lowrys syra").

This behavior is handled automatically via the Snowstorm API during concept searches.

Snowstorm uses a hierarchical branching system to segregate terminology content. This allows for parallel development projects, holding multiple release versions of SNOMED CT, or managing multiple versions of extensions within a single server.

• Root Branch: The top-level branch is always named MAIN.
• Hierarchy: Branches can have multiple children, and those children can have their own children (unlimited depth and breadth).
• Accessing Content: Content on a specific branch is accessed using its unique branch path (e.g., MAIN/ProjectA/Task1).

MAIN
  - 2019-01-31
  - 2018-07-31
  - ProjectA
    - Task1
    - Task2
  - ProjectB
    - Task1
    - Task2

To ensure Snowstorm can import Snapshots and perform ECL queries, follow these memory guidelines:

• Snowstorm: Minimum 2GB RAM.
• Elasticsearch: Minimum 4GB RAM.
• OS Caching: It is recommended to leave an additional 4GB of free memory on the server for OS-level disk caching.

When starting Snowstorm via the JAR, use JVM options to set the heap size (e.g., -Xms2g -Xmx4g).