Stored Procedures

General Characteristics of Stored Procedures

As noted in Enabling Versioned Views, database views allow useful queries to be saved and reused as though they were database tables. The SQL queries used in a view can be complex and can include data from other views such as those described in Composite Views. However, the definition of each view is defined by a single SQL query.

Stored procedures and functions provide an another way to define reusable resources in a database. The key difference between these database views, stored procedures and functions are summarized in . From a practical perspective these differences enable stored procedures to facilitate some types of access to a SNOMED CT data that cannot be supported by using database views. The following subsections describe a few examples of stored procedures that are included in the SNOMED CT example database.

Table 1: Features of Views, Stored Procedures and Functions (in MySQL)

Feature

Database View

Stored Procedure

Stored Function

Enable definition of reusable resources that facilitate commonly required processes that access data without

Defined by a single query

Produce output that can queried in the same way as a database table

Can be defined to output the results of a single SQL query

Can be defined to output the results of one or more SQL queries

Can be defined with input parameters to be set when invoked with values that affect the results

Can be defined to set values the values of one or more output parameters

Can be defined to return a single value of a specified datatype

Configuration Procedures

The SNOMED CT example database, has includes configuration settings that control configurable aspects of versioned table views (see Versioned Database Table Views). The configuration settings also affect queries, composite views and procedures that refer to configurable versioned table views.

The configuration settings are represented by a database table called config_settings and each of the procedures described in this section either selects data from that table or updates data in the table. The details and default settings of the config_settings table are shown in Table 2.

Table 2: Configuration Table Specification and initial settings

Column

Description

Datatype

Permitted Values

Default Values

Identifies the configuration setting and links to directly to view name prefixes

id=0 refers to snap and delta views (the time values are fixed for these views)
id=1 refers to snap1 and delta1 views
id=2 refers to snap2 and delta2 views

TINYINT

Integer in range 0-255

0, 1, 2

languageId

The refsetId of a language reference set.

BIGINT

Any language refsetId (e.g. 900000000000509007, 900000000000508004)

900000000000509007

languageName

The name of the language represented by the language reference set identified by languageId.

VARCHAR(255)

The name of any language or dialect represented by a language refset (e.g. US English, GB English).

US English

snapshotTime

DATETIME

Id=0: Release date (fixed)
Id>1: Any valid date.

Id=0: Release date
Id=1: Six months before release date
Id=2: One year before release date.

deltaStartTime

DATETIME

Id=0: Six months before release date (fixed)
Id>1: Any valid date before the release date.

Id=0: Six months before release date
Id=1: One year before release date
Id=2: Eighteen months before release date.

deltaEndTime

DATETIME

Id=0: Release date (fixed)
Id>1: Any valid date after the deltaStartTime.

Release DateTime (fixed)
Id=1: Six months before release date
Id=2: One year before release date.

Show Configuration Procedure

The showConfig procedure selects and displays the configuration files data.

Example 1: Using the showConfig Procedure

SQL Call to Procedure

call showConfig();

languageId

languageName

snapshotTime

deltaStartTime

deltaEndTime

900000000000509007

US English

United States of America English language reference set (foundation metadata concept)

2019-07-31

2019-01-31

2019-07-31

900000000000509007

US English

United States of America English language reference set (foundation metadata concept)

2019-01-31

2018-07-31

2019-01-31

900000000000509007

US English

United States of America English language reference set (foundation metadata concept)

2018-07-31

2018-01-31

2018-07-31

Set Language

The setLanguage procedure sets the languageId and languageName for a configuration row specified by its identifier value.

Languages can only be set if the following conditions apply.

The concept identifying the language reference set is available in the database.
The language abbreviation, language name and the identifier of the language reference set are in the config_language table.
The identified language reference set is available in the snap_refset_language reference set table or view.

SQL Call to Procedure

call setDeltaRange(p_id,p_deltaStartTime,p_deltaEndTime);

Parameter

Description

Data type

Valid values

Example

p_id

The identifier of the configuration table view (also the number of the snapshot or delta view number to which the setting applies).

TINYINT

0, 1 or 2

The language setting can be changed for the id=0 row.

p_lang_code

The date after which changes will be included in the delta view.

VARCHAR(5)

Any value that MySQL recognizes as a date or date-time.

'en-GB'

Example Procedure Call

call setLanguage(1,'en-GB');

Result

If p_lang_code does not refer to a language code in the config_language file or if no valid refset or refset members are found the procedure reports an error.

If the procedure succeeds, the language setting is changed but there is no output data. To check the result of the change, call showConfig() after resetConfig.

Set Snapshot Time

The setDeltaRange procedure sets the snapshotTime for a configuration row specified by its id value.

SQL Call to Procedure

call setDeltaRange(p_id,p_snapshotTime,p_deltaEndTime);

Parameter

Description

Data type

Valid values

Example

p_id

The identifier of the configuration table view (also the number of the snapshot or delta view number to which the setting applies).

TINYINT

1 or 2

(Note: Values less than 1 or greater than 2 will be treated as referring to row 2)

p_snapshotTime

The date for which the identified snapshot view will be computed.

DATETIME

Any value that MySQL recognizes as a date or date-time.

'2017-07-31'

Example Procedure Call

call setSnapshotTime(1,'2017-07-31');

Result

The snapshotTime setting is changed but there is no output data. To check the result of the change, call showConfig() after resetConfig.

Set Delta Range

The setDeltaRange procedure sets the deltaStartTime and deltaEndTime for a configuration row specified by its id value.

SQL Call to Procedure

call setDeltaRange(p_id,p_deltaStartTime,p_deltaEndTime);

Parameter

Description

Data type

Valid values

Example

p_id

The identifier of the configuration table view (also the number of the snapshot or delta view number to which the setting applies).

TINYINT

1 or 2

(Note: Values less than 1 or greater than 2 will be treated as referring to row 2)

p_deltaStartTime

The date after which changes will be included in the delta view.

DATETIME

Any value that MySQL recognizes as a date or date-time.

'2016-07-31'

p_deltaEndTime

The date on or before which changes with be included in the delta view.

DATETIME

Any value that MySQL recognizes as a date or date-time.

'2019-01-31'

Example Procedure Call

call setDeltaRange(1,'2016-07-31','2017-07-31');

Result

The deltaStartTime and deltaEndTime settings are changed but there is no output data. To check the result of the change, call showConfig() after resetConfig.

Reset Configuration

The resetConfig procedure resets all the configuration settings to the default values shown in the example below.

The reset depends on the date times config_settings on the row with id=0 being unchanged. In particular, if assumes the snapshotTime of that row as the releaseDate. The other procedures described in this section do not change those values. However, if those values are changed by update queries the resetConfig procedure will not correctly reset the snapshot and delta times.

Example : Reset Configuration

SQL Call to Procedure

call resetConfig();

Result

The reset is performed but there is no output data. To check the result of the reset, call showConfig() after resetConfig.

Language and Dialect Comparison Procedures

Terms in Languages

The termsInLanguages procedure displays the terms associated with a list of selected concepts in one or more specified languages or dialects. The concepts to be selected are specified by a comma-separated list of conceptIds and the languages in which they are to be displayed are specified by a comma-separated list of language codes.

Example: Example Use of termsInLanguages Procedure

SQL Call to Procedure

call snap_termsInLanguages(p_conceptids,p_langCodes);

Parameter

Description

Data type

Examples

p_conceptids

A string containing a comma separated list of concept identifiers.

text

'80146002,49438003'

p_langCodes

A string containing a comma separated list of language codes.

Only languages and dialects in the release files can be selected. With the International Release can be tested with p_langCode set to 'en-GB,en-US'. If other description files with terms in other languages are imported along with the relevant language refsets then these languages will also be accessible.

text

'en-GB,en-US'

Example Procedure Call

call snap_ShowLanguages('80146002,49438003','en-GB,en-US');

Result

conceptId

type_and_lang

term

80146002

FSN en-GB

Excision of appendix (procedure)

80146002

Preferred en-GB

Appendicectomy

80146002

Synonyms en-GB

Excision of appendix

80146002

FSN en-US

Excision of appendix (procedure)

80146002

Preferred en-US

Appendectomy

80146002

Synonyms en-US

Excision of appendix

49438003

FSN en-GB

Appendectomy with drainage (procedure)

49438003

Preferred en-GB

Appendicectomy with drainage

49438003

Synonyms en-GB

Appendicectomy and drainage

49438003

FSN en-US

Appendectomy with drainage (procedure)

49438003

Preferred en-US

Appendectomy with drainage

49438003

Synonyms en-US

Appendectomy and drainage

Search Procedures

Search Plus Procedures

The searchPlus procedure lists the conceptId and terms that match a search pattern. The search matches can also be filtered using a simple focus concept expression constraint or a regular expression pattern.

Note

This procedure is intended to demonstrate some of the search options available in MySQL and to illustrate the value of restricting searches to subtypes of concepts that in particular hierarchies or sub-hierarchies.

Additional work would be required to make a more user-friendly interface to these search facility and this is beyond the scope of the SNOMED CT example database.

Example Use of searchPlus Procedure

SQL Call to Procedure

call snap_searchPlus(p_search, p_filter);

Parameter

Description

Data type

Examples

p_search

A search term string.

These searches use MySQL's fulltext index employing one of the two supported search modes depending on the string supplied.

If p_search includes plus "+" or minus "-" symbols, the search is performed using boolean mode. This means matches are only returned if all words preceded by "+" are present and none of the words "-". Word not preceded by either plus or minus, are not required to match but will contribute to the search. The results of this search are sorted by with the shortest matching terms first.

If p_search does not include "+" or "-" symbols, the MySQL natural language search is used. It also orders the returned results by 'relevance' and is intended to assist contextual searching through literature. However, our testing indicate that the boolean mode is usually more effective for SNOMED CT searches.

For more information about full text searches in MySQL please see Full-Text Search Functions in the MySQL Reference Manual.

text

'+fundus +stomach'

'+lung +disease +chronic'

'appendix'

'hemoglobin'

'infection'

p_filter

A filter that will be applied to selectively include concepts that are subtype descendants of a specified concept:

a simple focus concept subtype constraint.
- Starting with a less than sign < followed either by either
  - a conceptId; or
  - a shortcut abbreviation for a commonly used concept. To see the current set of shortcuts run the following query "SELECT * FROM config_shortcutPlus;"

A regular expression pattern to be used to filter terms returned by the search string

a regular expression to exclude matching terms
- Starting this with an exclamation mark ! followed by the regular expression you want to exclude for the terms found by p_search.
a regular expression required for inclusion
- The text of the regular expression that must be matched for inclusion.

text

'<find'

'<proc'

'<123037004'

'!lung'

'heart'

Example Procedure Call

call snap_searchPlus('+viral +infection','< 19829001 |disorder of lung|');

Result

conceptId

term

75570004

Viral pneumonia

276692000

Congenital viral pneumonia

75570004

Viral pneumonia (disorder)

421508002

Viral pneumonia associated with AIDS

276692000

Congenital viral pneumonia (disorder)

421508002

Viral pneumonia associated with acquired immunodeficiency syndrome

421508002

Viral pneumonia associated with acquired immunodeficiency syndrome (disorder)

Expression Constraint Procedures

ECL Query Procedure

The eclQuery lists the conceptId and preferred term for each concept that conforms to a specified SNOMED CT expression constraint.

Notes

The expression constraints supported do not cover the full ECL specification but are restricted as described below.
This procedure will only run in MySQL version 8.0 or later. It uses some function which are not available in earlier versions (including the widely used MySQL version 5.7).

Example Use of eclQuery Procedure

SQL Call to Procedure

call snap_eclQuery(p_ecl);

Parameter

Description

Data type

Examples

p_ecl

The ECL query text

text

(< 19829001 |disorder of lung|) OR (< 301867009 |edema of trunk|)

'(< 19829001 |disorder of lung|) MINUS (< 301867009 |edema of trunk|)'

'>> 40541001 |Acute pulmonary edema|'

'>39057004 |pulmonary valve|'

'>!39057004 |pulmonary valve|'

Example Procedure Call

call snap_eclQuery('< 19829001 |disorder of lung|:116676008 |Associated morphology| = 40829002 |Acute edema|');

Result

conceptId

term

10519008

Acute pulmonary oedema due to fumes AND/OR vapours

40541001

Acute pulmonary oedema

61233003

Silo-fillers' disease

233706004

Drug-induced acute pulmonary oedema

233709006

Toxic pulmonary oedema

233710001

Chemical-induced pulmonary oedema

233711002

Oxygen-induced pulmonary oedema

360371003

Acute cardiac pulmonary oedema

10674871000119105

Pulmonary oedema caused by chemical fumes

Expression Constraint Feature Support and Limitations

The following notes provide a brief summary of the extent to which this procedure supports evaluation of expression constraints. For a full and detailed understanding of SNOMED CT expression constraints see the specification of the SNOMED CT Expression Constraint Language.

ECL Operators and Examples

Descendant of

The set of all subtypes of the given concept

< 404684003 |Clinical finding|

Descendant or self of

The set of all subtypes of the given concept plus the concept itself

<< 73211009 |Diabetes mellitus|

Ancestor of

The set of all supertypes of the given concept

> 40541001 |Acute pulmonary edema|

Ancestor or self of

The set of all supertypes of the given concept plus the concept itself

>> 40541001 |Acute pulmonary edema|

Child of

The set of all children of the given concept

<! 195967001 |Asthma|

Parent of

The set of all parents of the given concept

>! 195967001 |Asthma|

Member of

The set of referenced components in the given reference set

^ 733990004 |Nursing activities reference set|

Any

Any concept in the given SNOMED CT edition

Refinement

Only those concepts whose defining relationships match the given attribute value pairs

< 404684003 |clinical finding|: 116676008 |associated morphology| = *

AND

Conjunction

Only those concepts in both sets

(< 19829001 |disorder of lung|) AND (< 301867009 |edema of trunk|)

Disjunction

Any concept that belongs to either set

(< 19829001 |disorder of lung|) OR (< 301867009 |edema of trunk|)

MINUS

Exclusion

Concepts in the first set that do not belong to the second set

(< 19829001 |disorder of lung|) MINUS (< 301867009 |edema of trunk|)

Additional Notes on Limitations of the ECL Query Procedure

The following notes outline the extent to which this procedure supports the SNOMED CT expression constraints and highlights some of the most significant limitations of this procedure.

One or more constraints can be specified.

Each constraint must start with a focus concept constraint expressed as one of the following:
- A single conceptId specifying that concept as the focus concept.
- A single conceptId preceded by < (specifying subtypes only) or << (specifying self or subtypes)
- A conceptId that identifies a reference set preceded by a ^ indicating members of that reference set.
- An asterisk * (indicating any concept)
In all cases a concept Id may be followed by a term surrounded by pipe characters.
- The term between pipes will be ignored for processing.
Spaces between any elements in the expression will be ignored
The focus constraint may optionally be followed by a refinement constraint separated from the focus constraint by a colon :

If present the refinement constraint must consist of one or more attribute-value-constraint pairs.

The pair consists of an attribute-constraint and a value-constraint:
- The attribute-constraint must be separated from the value constraint by an = (equals) sign
- Both the constraints may be specified using any of the forms permitted for the focus concept constraint (see 1)
Attribute attribute-value-constraint pairs must be separated by a comma from any following attribute-value-constraint pair
NOTE: The procedure does not support:
- Nested refinement constraints
- Role grouping constraints
- Cardinality constraints

If more than one constraint is specified:

Each constraint must be enclosed in brackets
One of the following logical operators must be present between adjacent constraints
- OR The resulting set is the set of concepts that conform to either the constraint to the left or the constraint to the right (or both constraint).
- AND The resulting set is the set of concepts that conform to both the constraint to the left and the constraint on the right.
- MINUS The resulting set is the set of concepts that both conform to the constraint to the left and do not conform to the constraint on the right.
NOTE: The procedure does not support the use of brackets to alter the order of evaluation of constraints in a set. The set of constraints is evaluated from left to right and, as illustrated below, this is likely to affect the results.
1. 1. (A) OR (B) AND (C) MINUS (D)
    Concepts in either (A) or (B) form temporary set (aT1)
    Concepts in (aT1) and also in (C) form temporary set (aT2)
    Concepts in (aT2) that are NOT in (D) form the final result set (aR)
    One outcome of this order is that concepts in (B) that are not in (C) or are in (D) will not appear in the result set.
  2. (A) MINUS (D) AND (C) OR (B)
    Concepts in (A) and NOT in (D) form temporary set (bT1)
    Concepts in (bT1) and also in (C) form temporary set (bT2)
    Concepts in either (bT2) or (B) for the final result set (bR)
    In this order all concepts that are in (B) with me in the result set.

Summary of Limitations of ECL Support for this Procedure

The Procedure does not support:

Nested constraints
Dotted attributes
Nested refinement constraints
Attribute group constraints
Cardinality constraints

The Procedure also requires that:

Even simple expression constraints must be enclosed by brackets when multiple constraints are combined.

PreviousComposite Views NextCreating and Populating a SNOMED CT Database

Last updated 20 days ago