Overview

Finding a specific concept is a fundamental requirement and a prerequisite for most other terminology service. To make practical use of SNOMED CT, users must be able search for concepts using using phrases, words or parts of words. The SNOMED CT Search and Data Entry Guide provides detailed descriptions of these essential search types. It also notes a range of important additional features that facilitate appropriate use of the terminology by constraining searches and appropriately ordering search results. This section does not repeat that detailed discussion of different search techniques. Instead, it focuses on technical and practical requirements for delivering and accessing services that meet those requirements.

Several services described earlier in the guide provide technical ways to constrain searches for concepts to meet particular requirements. 

This section indicates ways in which term searches can and should be combined with those constraints to enable effective searches for concepts relevant to a particular context of use.



Requirements and Options

Term Searches

High-performance term search services are essential for most practical applications of SNOMED CT. Search services also need to employ effective strategies for rationalizing, sorting and presenting search results in ways that facilitate selection of concepts most frequently used in a given context of use. Term searches are typically language or dialect specific. Therefore requests for searches should include appropriate language codes or language reference set identifiers.

Search Techniques and Search Strings

Section 4. Optimizing Searches in the Search and Data Entry Guide identifies a range of different search techniques that may be valuable. If a terminology server supports more than on search technique the service request will need to indicate the technique to be used.

In the simplest case a term search service should be able to take a term or phrase typed by a user and return matching results. For this purpose, the recommended default search technique is to search for words or parts of words in any order (see Search and Data Entry Guide 4.1.5. Search for Words within in Any Order). Searches using this technique should be to return concepts associated with terms that include words that match or begin with all the words or part words in the search string. The order of words need not be the same in the search string and the matched term and the search string need not include all the words in the term.

Specific data storage and development environments also support specific solutions for searching text. These include boolean searches (which require some words to be present and other words to be absent, natural language searches which may include words with similar meanings. In addition to these there are more general pattern matching approaches including the use of wildcard character and searches using regular expressions. While these techniques can be useful, end users should be able to search SNOMED CT effectively without being required to understand a specific technical syntax.

Search Result Filtering and Ordering

Section 5. Optimize Display of Search Results in the Search and Data Entry Guide identifies a range of options for filtering and ordering the results of a search. Filtering options include avoiding displaying multiple matching terms that refer to the same concept as well as ensuring that by default descriptions associated with inactive concept are not displayed (though there should be an option to include inactive concepts as these may be relevant to historical data).  Ordering options include displaying the closest matches, shortest matching terms or most commonly used concepts at the top of the list of results.

Constrained Term Searches

Many practical use cases are best addressed by applying term searches to a constrained set of concepts. Searches that are appropriately constrained result in shorter lists of matching results and thus make it easier for a user to find the required concept. Constrained searches also reduce the risk of inadvertently selecting a concept in a hierarchy that is not appropriate to the data entry context. Thus this technique simplifies data entry and leads to improvements in data quality.

Searching the entire content of SNOMED CT when looking for a diagnosis or reason for admission is likely to include many concepts that are are not valid diagnoses or reasons for admission. This can make if difficult for the user to find the concept that they need and, in some case, may lead to recording of concepts that have terms that do not represent the intended meaning. Examples of errors arising from failing to constrain searches include recording the names of substances and morphological abnormality rather than the name of symptom or disorder. The results of such errors can result in errors in reporting, analysis and decision support even in cases where the selected term may appear to capture the required meaning.


The recommended approach to constrained searches is to use to specify the constraints. Ideally, the service should implement all the features of Expression Constraint Language (ECL). However, even if the service does not support some of the more advanced features, it should enable use of ECL to represent and combine and .

Services that do not support ECL should as a minimum support constraints based on  and the position of the concept in the . The recommended approach to testing the location of a concept in the hierarchy is the use of . However, if these tests are not supported, a more limited approach that filters search results by may be used.

All those involved in developing or procuring SNOMED CT terminology services are strongly advised to refer to the detailed guidance on this topic in the SNOMED CT Search and Data Entry Guide .



Essential and Recommended Functionality for Finding Concepts



Service Name and StatusInputOutput

Find concepts by term search


  • Edition and version

  • Language code(s)

  • Search string

  • Search technique option (if required )

  • Search filtering or sorting options (if supported )



A collection of matching terms each of which is linked to the appropriate concept.

Find concepts by constrained term search


  • Edition and version

  • Language code(s)

  • Search string

  • Search technique option (if required)

  • Search filtering or sorting options (if supported)
  • An expression constraint
A collection of matching terms that are applicable to concepts that conform to the specified constraints. Each term must be linked to the appropriate concept.

Interdependencies

Required By

Depends On

Service Examples

The Snowstorm and FHIR examples are presented in plain text and URL encoded versions. Always use the "Encoded URL" when testing the example service requests. The plain text version is included to aid readability but using this version in a service request may result in errors. These errors result from characters that have to be encoded as they are not permitted in a URL (see IETF RFC1738).


Snowstorm API


Service Name

API Call

Result

Find concepts by term search


GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&term=[search-string]


Example 1

GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=knee


Example 2.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol


Example 3.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=ren ston




Returns a JSON representation of data related to the concepts that have terms that match the search string.

The data returned for each concept includes:

  • All concept release file data
  • The preferred term and fully specified name.

Also returns the total number of concepts that match the search string.

As some searches are matched by large numbers of concepts, this service is paged. Requests parameters include:

  • limit to restrict the number of concepts returned (default 50).
  • offset to specify the start in the results (in multiples of the limit).

The results of the searches shown when applied to the 2020-01-31 International Edition were as follows:

  • Example 1 returns the first 50 concept that match the search term "knee". It also return a total value of 1387 indicating that there are 1337 more matches that could be shown. If the word "x-ray" is added to the search term, this reduces the number of matches to 8. This is an example of how an additional term can provide refinement for a particular context of use. However, this does not necessarily include all radiographic procedures on the knee - for example "Computed tomography of knee" will not match.
  • Example 2 returns the first 50 of 509 matches for the search term "alcohol". Of the first 50 concepts shown most related relate to the substance alcohol (26) and only 11 relate to disorders and findings.
  • Example 3 uses a search term with two partial words "ren ston". This finds only 7 matches but even in this case, the search results contain concepts from five different SNOMED CT hierarchies (substance, specimen, disorder, procedure and situation).

In all the above examples adding another word or two greatly reduces the results returned and reduces the distribution of the results across multiple hierarchies. However, when entering data for a given purpose it makes sense to limit the search results to concepts that can sensibly be applied to those contexts.

Find concepts by constrained term search


GET [snowstorm]/snomed-ct/[branchPath]/concepts?activeFilter=true&term=[search-string]&ecl=[expressionConstraint]

Example 4.

GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&ecl=<363680008|Radiographic imaging procedure|&term=knee
Example 5.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol&ecl=<64572001|Disease|
Example 6.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=alcohol&ecl=<64572001|Disease| and ^450970008| General Practice / Family Practice reference set|


Example 7.
GET [snowstorm]/MAIN/2020-01-31/concepts?activeFilter=true&term=ren ston&ecl=<64572001|Disease|




Constrained searches return JSON data for each of the matches in the same way as described above for the unconstrained searches.

Example 4 provides an example of how a search for x-ray procedures can be constrained so it is only necessary to enter the site and other related details. In this case the search term "knee" returns 40 matches. These include concepts such as "computed tomography of knee" which do not match "knee x-ray". The same constraint would simplifies all searches for radiology procedures and the constraint could also relaxed to include all imaging procedures.

Examples 5 and 6 provide an examples of how a search for a reason for admission might be constrained. In example 5 the constraint to disease restricts searches for alcohol or other drugs to concepts in the disorder hierarchy. This reduces the count of matches to 148. In example 6 a further constraint is added requiring the concept to be in the "General Practice / Family Practice reference set". The result of this is that only 21 matching concepts are returned. It is important to note that this is only an example, for practical in different clinical environments more specific reference sets should be considered.

Example 7 restricts the "ren ston" search to subtypes of disease and result in only 2 matches, which is a worryingly low number because there are certainly more SNOMED CT concepts that represent different disorders involving renal stones. The problem here is that many of the concepts do not have terms that match the search string. Instead, most related concepts use synonymous terms like "renal calculus" or "kidney stone".

A useful option to allow the user to deal with this situation is for the client application to provide users with the option to expand the results to include the subtype children or descendants of the matching concepts. In the case illustrated by example 7, this option would return 18 additional concepts (subtype descendants of 95570007|Kidney stone| that did not match the search term.






FHIR API


Service Name

API Call

Result

Find concepts by term search

In FHIR, the ValueSet/$expand operation may be used to search within a specified collection of codes.

A text filter may be applied to FHIR requests to restrict the codes that are returned. The interpretation of this is delegated to the server in order to allow to determine the most optimal search approach for the context.

Typical usage of this parameter includes functionality like:

  • using left matching e.g. "acut ast"
  • allowing for wild cards such as %, &, ?
  • searching on definition as well as display(s)
  • allowing for search conditions (and / or / exclusions)

For further details, see http://hl7.org/fhir/valueset-operation-expand.html


GET [fhir]/ValueSet/$expand?url=[versionURI]?fhir_vs&count=10&filter=[search-string]

Example 1

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs&filter=knee

Example 2

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs&filter=ren ston











Returns a JSON representation of data related to the concepts that have terms that match the search string.

The data returned for each concept includes:

  • The codesystem to which the returned concept belongs
  • The identifier (code) of the returned concept
  • A display term associated with the concept, e.g. the preferred term
  • All concept release file data
  • The preferred term and fully specified name.

Also returns the total number of concepts that match the search string.

As some searches are matched by large numbers of concepts, restrictions may be applied to limit the number of returned concepts. Parameters include:

  • count to restrict the number of concepts returned.
  • offset to specify the start in the results (in multiples of the limit).

Example 1 returns the first 10 concepts that match the search term "knee". As indicated by the first part of the url, the version requested is the January 2020 version of the International Edition. The total number of concepts returned is 1387.

Example 2 uses the a search term with two partial words "ren ston". This finds only 7 matches but even in this case, the search results contain concepts from five different SNOMED CT hierarchies (substance, specimen, disorder, procedure and situation). However, please note that when using this FHIR service, the semantic tag (or FSN) is not provided in the response.


Find concepts by constrained term search


GET [fhir]/ValueSet/$expand?url=[version]?fhir_vs=ecl/[expressionConstraint]&filter=[search-string]

Example 3


GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<363680008&count=10&filter=knee

Example 4

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<64572001|Disease|&filter=alcohol

Example 5

GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_vs=ecl/<64572001|Disease|and ^450970008| General Practice / Family Practice reference set|&filter=alcohol


Returns a JSON representation of data related to the concepts that have terms that match the search string.

The data returned for each concept includes:

  • The codesystem to which the returned concept belongs
  • The identifier (code) of the returned concept
  • A display term associated with the concept, e.g. the preferred term
  • All concept release file data
  • The preferred term and fully specified name.

Also returns the total number of concepts that match the search string.

As some searches are matched by large numbers of concepts, restrictions may be applied to limit the number of returned concepts. Parameters include:

  • count to restrict the number of concepts returned.
  • offset to specify the start in the results (in multiples of the limit).


Example 3 provides an example of how a search for x-ray procedures can be constrained so it is only necessary to enter the site and other related details. In this case the search term "knee" returns 40 matches. These include concepts such as "computed tomography of knee" which do not match "knee x-ray". The same constraint would simplifies all searches for radiology procedures and the constraint could also relaxed to include all imaging procedures.

Examples 4 and 5 provide an examples of how a search for a reason for admission might be constrained. In example 4, the constraint to disease restricts searches for alcohol or other drugs to concepts in the disorder hierarchy. This reduces the count of matches to 148. In example 5 a further constraint is added requiring the concept to be in the "General Practice / Family Practice reference set". The result of this is that only 21 matching concepts are returned. It is important to note that this is only an example, for practical in different clinical environments more specific reference sets should be considered.


MySQL Example Database


Service Name

SQL Query

Result

Find concepts by term search


SELECT s.conceptId 'id',s.term 'term',f.term 'FSN'
	FROM snap_term_search_active s 
	JOIN snap_fsn f on s.conceptId=f.conceptId 
	WHERE MATCH (s.term) AGAINST ('[search-string]' IN BOOLEAN MODE) 
	ORDER BY LENGTH(s.term)

for example

SELECT s.conceptId 'id',s.term 'term',f.term 'FSN'
	FROM snap_term_search_active s 
	JOIN snap_fsn f on s.conceptId=f.conceptId 
	WHERE MATCH (s.term) AGAINST ('knee' IN BOOLEAN MODE) 
	ORDER BY LENGTH(s.term)


SELECT s.conceptId 'id',s.term 'term',f.term 'FSN'
	FROM snap_term_search_active s 
	JOIN snap_fsn f on s.conceptId=f.conceptId 
	WHERE MATCH (s.term) AGAINST ('+renal +stone' IN BOOLEAN MODE) 
	ORDER BY LENGTH(s.term)



Returns the conceptId, term found and fully specified name. Ordering the results so that the closest matches (shortest matching terms) appear first in the list.

Find concepts by constrained term search


CALL snap_SearchPlus('[search-string]', '[simple-constraint]');

for example

CALL snap_SearchPlus('knee', '<363680008');


CALL snap_SearchPlus('+alcohol intoxication', '<64572001');


The searchPlus procedure allows a search string to be combined with a simple subtype constraint. This returns the conceptId and term for each match found.

This current searchPlus procedure in the example MySQL database does not support more complex constraint expressions.




  1. It should never be necessary for an end-user to enter a concept identifier. However, there are practical situations in which concept identifiers may be available to be used to find a specific concept or set of concepts. These situations include coded data in existing records or messages; templates, pick lists and other user interface controls that are bound to specific concept identifiers. If concept identifiers are available they provide a direct way to find data about specific concepts.
  2. One or more languages and/or dialects should be specified for searches. If more than one language or dialect is specified, the search should return matching terms that are acceptable in any specified language or dialect.
  3. The nature of the search string may vary according the search techniques supported and any options selected (see ).
  4. The search technique needs to be specified if the service supports different techniques (see ).
  5. If the service supports alternative ways of filtering or ordering results, these options chosen need to be specified (see ).
  6. As noted in , the use of expression constraints is recommended. However, other representations of constraints may be used if the service does not support .
  7. In the Snowstorm service requests [snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
  8. In the FHIR service requests [fhir] should be replaced by the URL to the FHIR terminology server endpoint. FHIR® is a registered trademarks of HL7 (www.hl7.org).
  9. The SNOMED CT MySQL example database is not designed as a terminology server and is not intended for use in a live system . It is referenced in this guide as an illustration that some readers may find helpful. For more information about the SNOMED CT example database see the SNOMED CT - SQL Practical Guide. For instructions on how to build the example database refer to Appendix A: Building the SNOMED CT Example Database.