# Get Data from a Reference Set

## Overview

Reference set files provide a standard format for maintaining and distributing a set of references to SNOMED CT components.

#### Notes

* A *reference set* can be used to represent a subset of components (concepts, descriptions or relationships).
* A *reference set* may also associate referenced components with additional information such as:
  * Ordered lists of components
  * Sets of associations between components
  * Mapping between SNOMED CT concepts and other systems codes, classifications, or knowledge resources.

The services required to identify the members of a reference set are described in Section [Get and Test Reference Set Membership](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.6-get-and-test-reference-set-membership). This section describes general requirements for services that are able to access additional data stored in reference sets.

The following services, described in earlier sections, require access to a single data value from each reference set row:

* [Get Terms for a Concept](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.3-get-terms-for-a-concept) requires access to the acceptabilityId in a [language reference set](https://confluence.ihtsdotools.org/display/DOCGLOSS/language+reference+set) to determine the preferred and acceptable terms for a concept in a specified language or dialect.
* [Get Definition of a Concept](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.4-get-definition-of-a-concept) requires access to the owlExpression in the [OWL axiom reference set](https://confluence.ihtsdotools.org/display/DOCGLOSS/OWL+axiom+reference+set) to get the stated view of a concept definition.

The following services described in the next few sections, require access to one or more data values from each reference set row:

* [Get History Data](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.11-get-history-data) uses historical reference set data to determine the reason for inactivation and to identify related active concepts.
* [Get Mapping Data](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.12-get-mapping-data) uses mapping reference set data to access maps to or from SNOMED CT concepts or expressions.
* [Get Concept Model Rules](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.13-get-concept-model-rules) uses MRCM reference set data to access concept model domain, attribute and range related rules.

Other reference set types that are not specifically documented in this section of the guide also contain additional data to which a client application may require access. Furthermore when new reference sets are introduced, there will be requirements to access additional data items in those reference sets. The service described in this section provides a general solution by providing access to all additional data associated with a reference set member in any type of reference set.

## Requirements and Options

<table data-full-width="true"><thead><tr><th>Service Name and Status</th><th>Input</th><th>Output</th></tr></thead><tbody><tr><td>Get data from a reference set for a specific referenced component<br><br><strong>REQUIRED</strong></td><td><ul><li>Edition and version</li><li><p>refsetId for the reference set from which data is to be extracted.</p><ul><li>Optional alternatives: a set of refsetIds or an expression constraint for a group of related reference sets.</li></ul></li><li>Optional: referencedComponentId</li><li><p>Optional parameters to select items within a particular type of reference set for example:</p><ul><li>mapTarget (in a mapping reference set)</li><li>targetComponentId (in an association or ordered association reference set)</li></ul></li></ul></td><td><p>Data from specified rows in the identified reference set(s).</p><ul><li>Note that the available data depends on the reference set type</li></ul></td></tr></tbody></table>

## Interdependencies

### Required By

* Other Services
  * Get Terms for a Concept
  * Get Definition of a Concept
  * Get History Data
  * Get Mapping Data
  * Get Concept Model Rules

### Depends On

* Select Edition and Version
* Get and Test Reference Set Membership

## Service Examples

{% hint style="info" %}
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](https://www.ietf.org/rfc/rfc1738.txt)).
{% endhint %}

### Snowstorm API

<table data-full-width="true"><thead><tr><th width="172.00390625">Service Name</th><th>API Call 2</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get data from a reference set for a specific referenced component</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branchPath]/members?active=true&#x26;referenceSet=[refsetId-or-ecl][&#x26;refsetComponentId=[componentId][&#x26;other-refsetType-specific-parameters]
</code></pre><p>Example 1</p><pre data-overflow="wrap" data-full-width="true"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=900000000000523009|POSSIBLY EQUIVALENT TO association reference set|&#x26;referencedComponentId=203004
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;amp;referenceSet=900000000000523009%7CPOSSIBLY+EQUIVALENT+TO+association+reference+set%7C&#x26;amp;referencedComponentId=203004
</code></pre><p><br>Example 2</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=&#x3C;900000000000522004|Historical association reference set|
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C
</code></pre><p>Example 3</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=&#x3C;900000000000522004|Historical association reference set|&#x26;targetComponent=140004
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN%2F2020-01-31/members?active=true&#x26;amp;amp;referenceSet=%3C900000000000522004%7CHistorical+association+reference+set%7C&#x26;amp;targetComponent=140004
</code></pre></td><td><p>Returns a JSON representation of data from members of the specified reference set that match the specified criteria.</p><p>The data returned for each matching reference set row includes:</p><ul><li>Data from the common columns present in all reference sets.</li><li><p>The referencedComponentId</p><ul><li>If the referencedComponentId refers to a concept, details of the concept including its fully specified name and preferred term are also included.</li></ul></li><li>An additionalFields object containing specific data fields associated with the particular reference set type.</li></ul><p>Also returns the <strong>total</strong> number of reference set row that match the constraint.</p><p>As some requests for reference set members return a large numbers of row, this service is paged. Requests parameters include:</p><ul><li><strong>limit</strong> to restrict the number of concepts returned (default 50).</li><li><strong>offset</strong> to specify the start in the results (in multiples of the limit).</li></ul><p><strong>Example 1</strong> shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.</p><p><br><strong>Example 2</strong> provides an example in which rows from all the historical association reference sets are returned.<br></p><p><strong>Example 3</strong> demonstrates that it is also possible to specify a targetComponentId value when searching for members of reference sets that contains this data item. Similar options are also supported for searches using some other data items specific to certain types of reference set (e.g. mapTarget, owlExpression.conceptId).</p></td></tr></tbody></table>

### FHIR API

<table data-full-width="true"><thead><tr><th width="196.21875">Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get data from a reference set for a specific referenced component</strong></td><td><p>The FHIR TS API supports the retrieval of targets for specific SNOMED CT reference sets. Please refer to this document for detailed guidance: <a href="https://www.hl7.org/fhir/snomedct.html">https://www.hl7.org/fhir/snomedct.html</a>. Thus, the ConceptMap/$translate operation enables the retrieval of targets for a specific referenced component.</p><pre data-overflow="wrap"><code>GET [fhir]/ConceptMap/$translate?code=[componentId] &#x26;system=http://snomed.info/sct &#x26;source=http://snomed.info/sct?fhir_vs &#x26;target=http://snomed.info/sct?fhir_vs &#x26;url=[version]?fhir_cm=[refesetId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [fhir]/ConceptMap/$translate?code=203004 &#x26;system=http://snomed.info/sct &#x26;source=http://snomed.info/sct?fhir_vs &#x26;target=http://snomed.info/sct?fhir_vs &#x26;url=http://snomed.info/sct/900000000000207008/version/20200131?fhir_cm=900000000000523009
</code></pre></td><td><p>Returns a JSON representation of data about each of the target components.</p><p>The data returned for each concept includes:</p><ul><li><strong>boolean:</strong> True if the concept could be translated successfully. The value can only be true if at least one returned match</li><li><strong>match:</strong> Each match represents data for the map or associated target. Note that there may be multiple matches, where each element represents a mapTarget. For each mapTarget, following data is provided</li><li><strong>system</strong>: the codesystem of the mapTarget</li><li><strong>code:</strong> The identifier of the mapTarget</li></ul><p><strong>Example 1</strong> shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.</p></td></tr></tbody></table>

### MySQL Example Database

<table data-full-width="true"><thead><tr><th width="207.3984375">Service Name</th><th>SQL Query</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get data from a reference set for a specific referenced component</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT * FROM snap_refset_[refsetType] WHERE refsetId=[refsetId]    [AND other-refset-type-specific-criteria];
</code></pre><p>Example 1</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT * FROM snap_refset_association    WHERE refsetId=900000000000523009    AND active=1 AND referencedComponentId=203004;
</code></pre><p>Example 2</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT * FROM snap_refset_association
    WHERE refsetId IN (900000000000523009)
    AND active=1 AND referencedComponentId=203004
UNION 
SELECT * FROM snap_refset_attributevalue
    WHERE refsetId IN (900000000000489007)
    AND active=1 AND referencedComponentId=203004;
</code></pre><p>Example 1</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">
SELECT * FROM snap_refset_association
WHERE refsetId IN (900000000000523009,900000000000489007)
    AND active=1 AND targetComponentId=140004;
SELECT * FROM snap_refset_association WHERE refsetId IN (900000000000523009, 900000000000524003, 900000000000525002, 900000000000526001, 900000000000527005, 900000000000528000, 900000000000529008, 900000000000530003, 900000000000531004)
    AND active=1 AND targetComponentId=140004;
</code></pre></td><td><p>Returns rows of data from the relevant reference set determined by the specified criteria.</p><p>The data returned for each matching reference set row includes:</p><ul><li>Data in the common columns present in all reference sets.</li><li>Additional data columns associated with the particular reference set type.</li></ul><p>Also returns the <strong>total</strong> number of reference set row that match the constraint.<br></p><p><strong>Example 1</strong> shows a search for data about a specific inactive component in a specific association reference set. This returns two rows each of which includes a targetComponentId referring to an active concept that represents a possible meaning of the inactive concept.</p><p><br><strong>Example 2</strong> provides an example in which rows from two an historical association reference sets and the concept inactivation attribute value reference set are returned for a specified referencedComponentId</p></td></tr></tbody></table>

<a href="https://docs.google.com/forms/d/e/1FAIpQLScTmbZIf0UEQwYDkY27EEWBkaiYkHSbR0_9DmFrMLXoQLyL7Q/viewform?usp=pp_url&#x26;entry.1767247133=SNOMED+Terminology+Services+Guide&#x26;entry.670899847=Get%20Data%20from%20a%20Reference%20Set" class="button primary">Provide Feedback</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.10-get-data-from-a-reference-set.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.