Reference
- 24 Jul 2024
- 7 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Reference
- Updated on 24 Jul 2024
- 7 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
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.