---
title: "Reference"
slug: "cql-reference"
updated: 2025-11-19T16:57:18Z
published: 2025-11-19T16:57:18Z
canonical: "docs.doc-know.com/cql-reference"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doc-know.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

### Clinical Expressions

Below is a list of supported **Clinical Query Language** (**CQL**) expressions:

| Category | Expression | Description |
| --- | --- | --- |
| Connections | **connect patient** {**x**} | Connects a patient (via SSN, MR#, UID) to a storyboard. Useful for testing. |
| Connections | **disconnect** | Clears all cached resources from a storyboard. Useful for testing. |
| Identifiers | **ssn** | Returns the patient's unique SSN. |
| Identifiers | **mrn** | Returns the patient's unique medical record #. |
| Identifiers | **uid** | Returns the patient's unique avatar identifier. |
| Demographics | **demos** | Returns the patient's core demographics. |
| Demographics | **full name** | Returns the patient's full name. |
| Demographics | **first name** | Returns the patient's first name. |
| Demographics | **last name** | Returns the patient's last name. |
| Demographics | **mi** | Returns the patient's middle initial. |
| Demographics | **tag** | Returns the patient's identification tag. |
| Demographics | **age** | Returns the patient's current age. |
| Demographics | **dob** | Returns the patient's date of birth. |
| Demographics | **dod** | Returns the patient's date of death. |
| Demographics | **cause of death** | Returns the patient's cause of death. |
| Demographics | **gender** | Returns the patient's gender. |
| Demographics | **gender short** | Returns the patient's gender, in short form (M, F, U). |
| Demographics | **gender identity** | Returns the patient's gender identity. |
| Demographics | **sexual orientation** | Returns the patient's sexual orientation. |
| Demographics | **pronouns** | Returns the patient's pronouns. |
| Demographics | **language** | Returns the patient's preferred language. |
| Demographics | **address** | Returns the patient's current mailing address. |
| Demographics | **line 1** | Returns line 1 of the patient's current mailing address. |
| Demographics | **line 2** | Returns line 2 of the patient's current mailing address. |
| Demographics | **city** | Returns the city of the patient's current mailing address. |
| Demographics | **state** | Returns the state of the patient's current mailing address. |
| Demographics | **zip** | Returns the zip code of the patient's current mailing address. |
| Demographics | **primary race** | Returns the patient's primary race. |
| Demographics | **secondary race** | Returns the patient's secondary race. |
| Demographics | **ethnicity** | Returns the patient's ethnicity. |
| Demographics | **phones** | Returns the patient's mobile, home, and work phone #s. |
| Demographics | **mobile phone** | Returns the patient's mobile phone #. |
| Demographics | **home phone** | Returns the patient's home phone #. |
| Demographics | **work phone** | Returns the patient's work phone #. |
| Demographics | **marriage status** | Returns the patient's marital status. |
| Care Team | **care team** [as csv] | Returns the patient's care team members. |
| Care Team | **pcp** | Returns the patient's primary care physician. |
| Care Team | **preferred provider** | Returns the patient's preferred provider. |
| Pharmacy | **pharmacy** | Returns the patient's preferred pharmacy name and phone #. |
| Pharmacy | **pharmacy name** | Returns the patient's preferred pharmacy name. |
| Pharmacy | **pharmacy phone** | Returns the patient's preferred pharmacy phone #. |
| Emergency | **er contact** | Returns the patient's emergency contact information. |
| Emergency | **er name** | Returns the patient's emergency contact name. |
| Emergency | **er relationship** | Returns the patient's emergency contact relationship. |
| Emergency | **er phones** | Returns the patient's emergency contact mobile, home, and work phone #s. |
| Emergency | **er mobile phone** | Returns the patient's emergency contact mobile phone #. |
| Emergency | **er home phone** | Returns the patient's emergency contact home phone #. |
| Emergency | **er work phone** | Returns the patient's emergency contact work phone #. |
| Medications | **meds** [with time] [as csv] | Returns a list of the patient's active medications. |
| Medications | **taking** {**x**} **med** | Returns whether or not the patient is actively taking the specified medication. |
| Vitals | **recent vitals** [with time] [as csv] | Returns the most recent value for each recorded vital sign. |
| Vitals | [take #] {**x**} **vitals** [with time] [as csv] | Returns a list of the specified vital sign's recorded values. |
| Vitals | {**x**} **vital** [with time] | Returns the most recent value of the specified vital sign. |
| Labs | **recent labs** [with time] [as csv] | Returns the most recent value for each recorded lab. |
| Labs | [take #] {**x**} **labs** [with time] [as csv] | Returns a list of the specified lab's recorded values. |
| Labs | {**x**} **lab** [with time] | Returns the most recent value of the specified lab. |
| Allergies | **allergies** [with time] [as csv] | Returns a list of the patient's known allergies. |
| Allergies | **has** {**x**} **allergy** | Returns whether or not the patient has the specified allergy. |
| Scheduling | {**all**, **upcoming**, **completed**, **cancelled**, **no-show**} [md, non-md] [telehealth] **appointments** [with providers] [with sites] [with time] [as csv] | Returns a list of the patient's appointments. |
| History | **diseases** [with time] [as csv] | Returns a list of the patient's known diseases. |
| History | **procedures** [with time] [as csv] | Returns a list of the patient's known procedures. |
| History | **family history** [with time] [as csv] | Returns a list of the patient's known family history. |
| History | **social history** [with time] [as csv] | Returns a list of the patient's known social history. |
| History | **history of** {**x**} | Returns whether or not the patient has a history of the specified item. |
| Physical Exam | **physical exam** [with time] [as csv] | Returns a list of all findings during the patient's latest physical examination. |
| Physical Exam | **observation of** {**x**} | Returns the value of the specified item during the patient's latest physical examination. |
| Physical Exam | **normal observation of** {**x**} | Returns whether or not the specified item was identified as normal during the patient's physical examination. |
| Physical Exam | **abnormal observation of** {**x**} | Returns whether or not the specified item was identified as abnormal during the patient's physical examination. |
| Problems | **problems** [with comments] [with time] [as csv] | Returns a list of the patient's current problems. |
| Problems | {**x**} **problem comments** [with time] | Returns the comments of the specified problem. |
| Problems | **has** {**x**} **problem** | Returns whether or not the patient has the specified problem. |
| Records | **recent records** [with comments] [with time] [as csv] | Returns a list of the patient's most recent records of each type. |
| Records | **recent** {**x**} **record comments** [with time] | Returns the comments of the most recent specified record title. Supports partial titles. |
| Records | [take #] {**x**} **records** [with comments] [with time] [as csv] | Returns a list of the patient's records with the specified title. Supports partial titles. |
| Records | [take #] {**x**} **record** {**body, bodies**} | Returns the **body(s)** of the specified report title. Supports partial titles. |
| Records | **search** [all, recent] **records with** {**criteria**} [with time] [as csv] [take #] | Returns records that contain the specified **criteria** in their title or comments. |
| Records | **select** [#] **[token1,token2,...]** **from** {**x**} **records** [with time] [as xml] [as json] | Returns one or more data point values identified by the specified tokens (**Needle ID**, **Object ID**, **Object Name**, and **Full ID** tokens are supported). When a single token is specified, its value is returned from the latest record. When multiple tokens are specified, an array of corresponding values is returned from the same latest record. When **#** is specified, a single token is required and an array of **#** values of the same token is returned, spanning multiple records of the same type. When **#** is positive (**+**), **recent** values are returned. When **#** is negative (**-**), **earliest** values are returned. {**x**} supports starting and ending wildcards using * syntax. |

          Input Spacing

          

> Input values (e.g. {**x**}) that contain **spaces** must replace these spaces with **underscores**. For example '**heart rate vital**' must be specified as '**heart_rate vital**'

          Escape Character

          

> When you have a storyboard input that includes a clinical expression that you **don't** want computed, simply add a '**\**' character before the start of your expression. For example, '**\gender**' will instruct the clinical language to ignore this expression and the output will simply display the word '**gender**'.

          Full IDs

          

> **Full IDs** are specified using **AppID.ObjectID** syntax. This syntax is useful when querying records composed of multiple apps (i.e. clinical notes).

### Filters

Some clinical expressions support **filters**, which are used to filter, or reduce, the subject.

Below is a description of supported expression filters:

| Filter | Description |
| --- | --- |
| [**take #**] | Specifies the # of results to return. When positive (**+**), **recent** values are returned. When negative (**-**), **earliest** values are returned. |
| [**using ai**] | Uses a generative AI image creation model. |
| [**using atlas**] | Uses the Dr. Know Atlas medical imaging library. |

### Decorators

Some clinical expressions support **decorators**, which modify the returned results.

Below is a description of supported expression decorators:

| Decorator | Description |
| --- | --- |
| [**with comments**] | Includes comments in the returned results. |
| [**with time**] | Includes dates and/or times in the returned results. |
| [**with providers**] | Includes provider information in the returned results. |
| [**with sites**] | Includes site information in the returned results. |
| [**as csv**] | Returns results as a comma-separated list. |
| [**as xml**] | Returns results as an XML document. |
| [**as json**] | Returns results as a JSON document. |

### Examples

Below are some example clinical language expressions:

```
Prompt: Hello, {{first name}}! You are {{age}} years old.
Output: 'Hello, John! You are 45 years old.'
```

```
Prompt: {{ take 3 heart_rate vitals }}
Output: The most recent 3 recorded heart rate values.
```

```
Prompt: {{ upcoming md appointments with time }}
Output: A numbered list of upcoming physician appointments, including dates and times.
```

```
Prompt: {{ plot bmi vitals }}
Output: A plot of all recorded BMI vital sign values.
```

```
Prompt: {{ select [token1] from echo* records }}
Output: The value of token1 from the latest record that starts with 'echo'.
```

```
Prompt: {{ select [token1,token2] from echo records }}
Output: An array containing [valueToken1,valueToken2] from the latest echo record.
```

```
Prompt: {{ select 3 [token1] from echo records with time }}
Output: An array of 3 token1 values from the latest 3 echo records, including timestamps.
```