# Get and Test Reference Set Membership

## 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.

## Requirements and Options

A concept or description is a member of a reference set if that reference set contains an active row with a referencedComponentId matching the id of that concept or description.

Two services are specified in this section. One of these returns the list of members of a specified reference set. The other tests whether a candidate concept or description is a member of a specified reference set.

The union, intersection or complement of two or more reference sets can be determined using the [SNOMED CT Expression Constraint Language](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/sOJBD7YbxAy9bD1Ko9L9/) (ECL). Terminology service requirements for accessing expression constraints are described in [Validate and Apply Expression Constraints](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.7-validate-and-apply-expression-constraints).

The services listed in the table below can be used to determine whether a concept or description is a member of any identified reference set. These services are primarily applicable to simple reference sets that represent subsets of concepts or descriptions ([Simple Reference Set](https://app.gitbook.com/s/qOI2v58ZsXOoklmwBOk4/2-subsets-value-sets-and-reference-sets/2.1-subset)). Members of other types of reference set contain additional data and services that provide access to this additional data are described in [Get Data from a Reference Set](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) .

#### Services Required

<table><thead><tr><th width="218.0687255859375">Service Name and Status</th><th>Input</th><th>Output</th></tr></thead><tbody><tr><td><strong>Get all members of a specified reference set</strong></td><td><ul><li>A reference set specified by its refsetId</li></ul></td><td><ul><li>A list of concept or description ids</li><li>Option to include additional information about each concept or description</li></ul></td></tr><tr><td><strong>Test if a concept or description is a member of specified reference set</strong></td><td><ul><li>A reference set specified by its refsetId A candidate concept.id or description.id</li></ul></td><td><ul><li>If the candidate concept or description is a member of the reference set: TRUE</li><li>Otherwise: FALSE</li></ul></td></tr></tbody></table>

## Interdependencies

### Required By

* Other Services
  * [4.7-validate-and-apply-expression-constraints](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.7-validate-and-apply-expression-constraints "mention")
  * [4.8-find-concepts](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.8-find-concepts "mention")
* Use Cases
  * [support-ehr-data-entry](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/support-ehr-data-entry "mention")
  * [reference-set-editing](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/3-terminology-service-use-cases/reference-set-editing "mention")
  * [4.10-get-data-from-a-reference-set](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 "mention")

### Depends On

* [4.1-select-edition-and-version](https://docs.snomed.org/snomed-ct-practical-guides/snomed-ct-terminology-services-guide/4-terminology-service-types/4.1-select-edition-and-version "mention")

## Service Examples

{% hint style="success" %}
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><thead><tr><th width="161.3187255859375">Service Name</th><th>API Call</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get all members of a specified reference set</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branch]/members?active=true&#x26;referenceSet=[refsetId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referenceSet=723264001
</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=723264001
</code></pre></td><td><p>Returns a JSON representation of data about all the active members of the reference set.</p><p>It also returns the <strong>total</strong> number of members in the reference set.</p><p>As some reference sets contain a large numbers of members, this service is paged. Requests parameters include:</p><ul><li><strong>limit</strong> to restrict the number of reference set members returned (default 50).</li><li><strong>offset</strong> to specify the starting point in the results (in multiples of the limit).</li></ul><p>This example returns all active members of the <a href="http://snomed.info/id/723264001">723264001 | Lateralizable body structure reference set|</a> . This is large reference set with nearly 20,000 active members so although this call returns the count of members it only returns data on a limited number of members .</p></td></tr><tr><td><strong>Test if a concept or description is a member of specified reference set</strong></td><td><pre data-overflow="wrap"><code>GET [snowstorm]/[branch]/members?active=true&#x26;referencedComponentId=[candidateId]&#x26;referenceSet=[refsetId]
</code></pre><p>for example this call returns true</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referencedComponentId=53120007&#x26;referenceSet=723264001
</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;referencedComponentId=53120007&#x26;amp;referenceSet=723264001
</code></pre><p>while the next call returns false</p><pre data-overflow="wrap"><code>GET [snowstorm]/MAIN/2020-01-31/members?active=true&#x26;referencedComponentId=80891009&#x26;referenceSet=723264001
</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;referencedComponentId=80891009&#x26;amp;referenceSet=723264001
</code></pre></td><td><p>Returns a JSON representation of data including a count of matching member rows followed by data from the matching member rows. The result of the test can be determined by checking the <strong>total</strong> property of the returned object. Non-zero implies the candidate concept or description is a member of the reference set, zero implies it is not.</p><p>The two example calls both test membership of the <a href="http://snomed.info/id/723264001">723264001 | Lateralizable body structure reference set|</a> . The first one returns with a total value of 1 confirming that <a href="http://snomed.info/id/53120007">53120007 | Upper limb structure|</a> is a member of this reference set. The second example returns with a total value of 0 as <a href="http://snomed.info/id/80891009">80891009 | Heart structure|</a> is not a member of this reference set.</p><p><br></p></td></tr></tbody></table>

#### FHIR API

<table><thead><tr><th width="162.5562744140625">Service Name</th><th>API Call 5</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get all members of a specified reference set</strong></td><td><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007&#x26;amp;count=10
</code></pre><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E%5BrefsetId%5D&#x26;amp;count=10
</code></pre><p>An alternative solution is to use the expression constraint language, as shown here:</p><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Drefset%2F721144007&#x26;amp;count=10
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=refset/[refsetId]&#x26;count=10
</code></pre></td><td><p>Returns a JSON representation of data about each of the reference set member.</p><p>The data returned for each concept includes:</p><ul><li><strong>code:</strong> the conceptId of the reference set member</li><li><strong>display:</strong> the preferred term for the reference set member</li></ul><p>Also returns the <strong>total</strong> number of reference set members</p><p>As some reference sets have very large numbers of children, this service is paged. Requests parameters include:</p><ul><li><strong>count</strong> to restrict the number of members returned.</li><li><strong>offset</strong> to specify the start in the results (in multiples of the limit).</li></ul></td></tr><tr><td><strong>Test if a concept is a member of specified reference set</strong></td><td><p>FHIR does not provide a specific operation for this service, but the <a href="https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/sOJBD7YbxAy9bD1Ko9L9/">SNOMED CT Expression Constraint Language</a> supports testing for reference set membership, and can thus be used to enable this service through the ValueSet/$expand operation.</p><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^[refsetId] AND [predicateConceptId]
</code></pre><p>for example</p><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http://snomed.info/sct?fhir_vs=ecl/^721144007 AND 734009000
</code></pre><hr><p><em>Encoded URL</em></p><pre data-overflow="wrap"><code>GET [fhir]/ValueSet/$expand?url=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Decl%2F%5E721144007+AND+734009000
</code></pre><p>*Note that the ECL memberOf function needs to be url encoded. The URL encoding for ^ is %5E</p><p>If multiple predicate concepts should be tested in the same requests this can be done using the following expression constraint:</p><pre data-overflow="wrap"><code>^[refsetId] AND ([predicateConceptId_1] OR [predicateConceptId_2].... OR [predicateConceptId_n])
</code></pre></td><td><p>Returns a JSON representation of data about each of the predicate concepts that are members of the reference set.</p><p>The data returned for each concept includes:</p><ul><li><strong>code:</strong> the conceptId of the reference set member</li><li><strong>display:</strong> the preferred term for the reference set member</li></ul><p>Also returns the <strong>total</strong> number of concepts satisfying the expression constraint.</p><p><strong>Note:</strong> If none of the predicate concepts are which are tested for membership are included in the reference set, the service will return 0 results.</p></td></tr></tbody></table>

#### MySQL Example Database

<table><thead><tr><th width="159.65936279296875">Service Name</th><th width="354.8187255859375">SQL Query 6</th><th>Result</th></tr></thead><tbody><tr><td><strong>Get all members of a specified reference set</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=[refsetId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=723264001
</code></pre></td><td>Returns the ids of all the concepts or descriptions that are the members of the reference se</td></tr><tr><td><strong>Test if a concept or description is a member of specified reference set</strong></td><td><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">
SELECT count(referencedComponentId)
FROM snap_refset_simple
WHERE active=1 AND refsetId=[refsetId] AND referencedComponentId=[candidateComponentId]
</code></pre><p>for example</p><pre class="language-sql" data-overflow="wrap"><code class="lang-sql">SELECT referencedComponentId FROM snap_refset_simple
WHERE active=1 AND refsetId=723264001
</code></pre></td><td><p>Returns:</p><ul><li>0 : if the candidate component is not in the reference set.</li><li><p>1 : If the candidate component is a member of the reference set</p><ul><li>Some types or reference set can include the same component more than once, so any value greater than zero indicate the component is a member of the references set.</li></ul></li></ul></td></tr></tbody></table>

***

**Notes**

* The reference set specification should indicate which component types are permitted to be members. The members of some reference sets are concepts while the members of other reference sets are concepts. It is also possible, for some reference sets to contain both concepts and descriptions as members. Services that only return the referencedComponentId do not need to be aware of the types of component in the reference set. However, if a service returns terms or other additional data, the service must take account of the component type.
* The value TRUE may be represented in a variety of ways. For example: as a Boolean value, as a non-zero count of matching members or by a data object representation of the candidate component. Similarly the value FALSE may be represented by a Boolean, by a zero count, or by an empty or null returned object.
* In the Snowstorm service requests \[snowstorm] should be replaced by the URL to the Snowstorm server endpoint.
* The number of results returned defaults to 50 but can be set using a limit parameter in the call. Additionally the starting offset within a large set of results can be specified by an additional parameter.
* 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](http://www.hl7.org/) ( [www.hl7.org](http://www.hl7.org/) ).
* 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](https://app.gitbook.com/o/h8Z6qGxuQrzM9vbx5bPT/s/LnTo62BQeQSW6tBNKv0T/). For instructions on how to build the example database refer to [Appendix A: Building the SNOMED CT Example Database](https://app.gitbook.com/s/LnTo62BQeQSW6tBNKv0T/appendix-a-building-the-snomed-ct-example-database).

<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%20and%20Test%20Reference%20Set%20Membership" 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.6-get-and-test-reference-set-membership.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.