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.