One of Snow Owl's powerful features is the ability to list concepts matching a user-specified query expression using SNOMED International's Expression Constraint Language (ECL) syntax. If you would like to know more about the language itself, visit the documentation on the official site.
In this example, we list the direct descendants of the root concept using the ECL expression <!138875005 (via the ecl query parameter), and also limit the result set to a single item using the limit query parameter:
As no query parameter in this request would make Snow Owl differentiate between "better" and "worse" results (eg. a search term to match), concepts in the response will be sorted by identifier.
The item returned is, indeed, one of the top-level concepts in SNOMED CT:
105590001 |Substance|
The number 19 in property total suggests that additional matches exist that were not included in the response this time.
This guide shows you how to quickly set up a Snow Owl deployment using docker to store, search, and edit any healthcare terminology data. Start here if you are interested in evaluating its core features.
Here is how to deploy Snow Owl in less than a minute:
The open-source version of Snow Owl can be downloaded as a docker image. The list of all published tags and additional details about the image can be found in Snow Owl's public Docker Hub repository.
To initiate a Snow Owl deployment, the only requirements are:
the Docker Engine (see install guide)
a terminal
git (optional, see install guide)
Setting up a fully operational Snow Owl server depends on which architecture is supported by the Docker Engine. Thankfully it has a wide variety of platforms such as Linux, Windows, and Mac.
There is a preassembled docker compose configuration in Snow Owl's GitHub repository. This set of files can be used to start up a Snow Owl terminology server and its corresponding data layer, an Elasticsearch instance.
To get ahold of the necessary files it is required to either download the repository content (see instructions here) or clone the git repository using the git command line tool:
Once the clone is finished find the directory containing the compose example:
While in this directory start the services using docker compose:
The example configuration will allocate 6 GB of memory for Elasticsearch and another 6 GB for Snow Owl. These settings are required if all features of Snow Owl are to be tested. To change these values see the instructions below.
The service snowowl listens on localhost:8080 while it talks to the elasticsearch service over an isolated Docker network.
To stop the application, type docker compose down. Data volumes/mounts will remain on disk, so it's possible to start the application again with the same data using docker compose up.
A default user is configured to experiment with features that would require authentication and authorization. The username is test and its password is the same.
Here is the full content of the compose file:
Reducing the memory settings of the docker stack is feasible when Snow Owl is assessed with limited terminologies and basic operations such as term searches. An applicable minimum value should be no less than 2 GB for each service.
The memory settings of Elasticsearch can be changed by adapting the following line in the docker-compose.yml file to e.g.:
The memory settings of Snow Owl can be changed by adapting the following line in the docker-compose.yml file to e.g.:
Snow Owl's status is exposed via a health REST API endpoint. To see if everything went well, run the following command:
The expected response is
The response contains the installed version along with a list of repositories, their overall health (eg. "snomed" with health "GREEN"), and their associated indices and status (eg. "snomed-relationship" with status "GREEN").
Let's import an RF2 archive using its SNAPSHOT content (see release types here) so that we can further explore the available SNOMED CT APIs. To start the import process, send the following request:
Curl will display the entire interaction between it and the server, including many request and response headers. We are interested in these two (response) rows in particular:
The first one indicates that the file was uploaded successfully and a resource has been created to track the progress of the import job, while the second row indicates the location of this resource.
Depending on the size and type of the RF2 package, hardware, and Snow Owl configuration, RF2 imports might take a few hours to complete (but usually less). Official SNAPSHOT distributions can be imported in less than 30 minutes by allocating 6 GB of heap size to Snow Owl and configuring it to use a solid-state disk for the data directory.
The process itself is asynchronous and its status can be checked by periodically sending a GET request to the location returned in the response header:
The expected response while the import is running:
Upon completion, you should receive a different response that lists component identifiers visited during the import as well as any defects encountered in uploaded release files:
Snow Owl is now running but does not contain any content whatsoever. To be able to import or author terminology data a resource has to be created beforehand. There are three major resource types in the system:
Code Systems (e.g. SNOMED CT, ATC, LOINC, ICD-10)
Value Sets
Concept Maps
For the sake of this quick start guide, we will follow along the path of how to create a SNOMED CT code system, import content and query concepts based on different criteria.
If we take a look at eg. the list of known code systems, we get an empty result set:
To import SNOMED CT content, we have to create a code system first using the following request:
Use of SNOMED CT is subject to additional conditions not listed here, and the full copyright notice has been shortened for brevity in the request above. Please see here for details.
The request body includes:
The code system identifier (SNOMEDCT)
Various pieces of metadata offering a human-readable title, status, contact information, URL and OID for identification, etc.
The tooling identifier snomed that points to the repository that will store content
Additional code system settings stored as key-value pairs
If the request succeeds the server returns a "204 No Content" response. We can verify that the code system has been registered correctly with the following request:
The expected response is:
In addition to the submitted values, you will find that additional administrative properties also appear in the output. One example is branchPath which specifies the working branch of the code system within the repository.
The code system now exists but is empty. To verify this claim, we can list concepts using either Snow Owl's native API tailored for SNOMED CT or the standardized FHIR API for a representation that is uniform across different kinds of code systems – for the sake of simplicity, we will use the former in this example.
The following request can be used to list all available concepts in a SNOMED CT code system:
The expected response is:
At this point, we can either import or create content in the SNOMED CT code system. Follow the instructions on the next page to import your SNOMED CT RF2 release into Snow Owl.
Now that we have our instance up and running, the next step is to understand how to communicate with it. Fortunately, Snow Owl provides very comprehensive and powerful APIs to interact with your instance.
Among the few things that can be done with the API are as follows:
Perform CRUD (Create, Read, Update, and Delete) and search operations against your terminology resources
Execute advanced search operations such as paging, sorting, filtering, scripting, aggregations, and many others
Administer your instance data
Check your instance health, status, and statistics
Snow Owl is both a simple and complex product. We’ve so far learned the basics of what it is, how to look inside of it, and how to work with it using some of the available APIs. Hopefully, this tutorial has given you a better understanding of what Snow Owl is and more importantly, inspired you to further experiment with the rest of its great features!
Now that SNOMED CT content is present in the code system (identified by the unique id SNOMEDCT) it is time to take a deeper dive. A frequent interaction is to retrieve properties of a concept identified by its SNOMED CT Identifier. To do so, execute the following command:
The response should look something like this:
We used the expand query parameter to include the concept's Preferred Term (PT) in the response. The concept in question is the root concept of the SNOMED CT hierarchy.
Snow Owl also allows users to retrieve concepts matching a specific search term or phrase. See what happens if we try to find the concepts associated with the condition "Méniere's disease":
This time more than one concept can be present in the response, so we receive a collection of items. Results are sorted by relevance, indicated by the field score:
The total number of matching concepts is shown in the property named total.