2. Author’s Guide

The library declaration specifies both the name of the library and an optional version for the library. The library name is used as an identifier to reference the library from other CQL libraries, as well as eCQM and CDS artifacts. A library can have at most one library declaration.

The following example illustrates the library declaration:

The above declaration names the library with the identifier CMS153_CQM and specifies the version '2'.

A syntax diagram of the library declaration can be seen here.

A CQL library can reference zero or more data models with using declarations. These data models define the structures that can be used within retrieve expressions in the library.

For more information on how these data models are used, see the Retrieve section.

The following example illustrates the using declaration:

The above declaration specifies that the QUICK model will be used as the data model within the library. The QUICK data model will be used for the examples in this section unless specified otherwise.

If necessary, a version specifier can be provided to indicate which version of the data model should be used as shown below:

A syntax diagram of the using declaration can be seen here.

A CQL library can reference zero or more other CQL libraries with include declarations. Components defined within these included libraries can then be referenced within the library by name.

Components defined in the CMS153_Common library can now be referenced using the library name. For example:

This expression references ConditionsIndicatingSexualActivity and LaboratoryTestsIndicatingSexualActivity defined in the CMS153_Common library.

The syntax used to reference these expressions is a qualified identifier consisting of two parts. The qualifier, CMS153_Common, and the identifier, ConditionsIndicatingSexualActivity, separated by a dot (.).

For more information on libraries, refer to the Using Libraries to Share Logic section.

The include declaration may optionally specify a version, meaning that a specific version of the library must be used:

A more in-depth discussion of library versioning is provided in the Libraries section of the Developers guide.

In addition, the include declaration may optionally specify an assigned name using the called clause:

Components defined in the CMS153_Common library, version 2, can now be referenced using the assigned name of Common. For example:

A syntax diagram of the include declaration can be seen here.

A CQL library may contain zero or more named terminology declarations, including codesystems, valuesets, codes, and concepts, using the codesystem, valueset, code, and concept declarations.

These declarations specify a local name that represents a codesystem, valueset, code, or concept and can be used anywhere within the library where the terminology is expected.

The syntax diagrams of the codesystem definition,valueset definition, code definition and concept definition.

Consider the following valueset declaration:

This definition establishes the local name "Female Administrative Sex" as a reference to the external identifier for the valueset, more specifically, an Object Identifier (OID) in this particular case: 'urn:oid:2.16.840.1.113883.3.560.100.2'. The external identifier need not be an OID; instead, it may be a uniform resource identifier (URI), or any other identification system. CQL does not interpret the external id, it only specifies that the external identifier be a string that can be used to uniquely identify the valueset within the implementation environment.

This valueset definition can then be used within the library wherever a valueset can be used:

The above example defines the PatientIsFemale expression as true for patients whose gender is a code in the valueset identified by "Female Administrative Sex".

Note that the name of the valueset uses double quotes, unlike the string representation of the OID for the valueset, which uses single quotes. Single quotes are used to build arbitrary strings in CQL; double quotes are used to represent names of constructs such as valuesets and expression definitions.

Note also that the local name for a valueset is user-defined and not required to match the actual name of the valueset identified within the external valueset repository. However, when using external terminologies, authors should use the name of the terminology as defined externally to avoid introducing any potential confusion of meaning.

The following example illustrates a code system and a code declaration:

This codesystem declaration in this example establishes the local name "SNOMED" as a reference to the external identifier for the codesystem, the URI "http://snomed.info/sct". The code declaration in this example establishes the local name "Screening for Chlamydia trachomatis (procedure)" as a reference to the code '442487003' from the "SNOMED" code system already defined.

For more information about terminologies as values within CQL, refer to the Clinical Values section.

A CQL library can define zero or more parameters. Each parameter is defined with the elements listed in the following table:

Table 2‑B - Elements that define a parameter

A syntax diagram of the parameter can be seen here.

The parameters defined in a library may be referenced by name in any expression within the library. When expressions in a CQL library are evaluated, the values for parameters are provided by the environment. For example, a library that defines criteria for a quality measure may define a parameter to represent the measurement period:

Note the syntax for the default here is called an interval selector and will be discussed in more detail in the section on Interval Values.

This parameter definition can now be referenced anywhere within the CQL library:

The above example defines the Patient16To23 expression as patients whose age at the start of the MeasurementPeriod was at least 16 and less than 24.

The default value for a parameter is optional, but if no default is provided, the parameter must include a type specifier:

If a parameter definition does not indicate a default value, a parameter value may be supplied by the evaluation environment, typically as part of the evaluation request. If the evaluation environment does not supply a parameter value, the parameter will be null.

In addition, because parameter defaults are part of the declaration, the expressions used to define them have the following restrictions applied:

In other words, the value for the default of a parameter must be able to be calculated at compile-time.

The context declaration defines the scope of data available to statements within the language. Models define the available contexts, including at least one context named Unfiltered that indicates that statements are not restricted to a particular context. Consider the following simplified information model:

Figure 2-A - Simplified patient/practitioner information model

A patient and practitioner may both have any number of encounters. From the perspective of a patient (i.e. in patient context), only encounters for that particular patient are accessible. Likewise, from the perspective of a practitioner (i.e. in practitioner context), only encounters for that particular practitioner are accessible.

The following table lists some typical contexts:

Table 2‑C - Typical contexts for CQL

A syntax diagram of the context declaration can be seen here.

Depending on different needs, models may define any context appropriate to their use case, but should identify a default context that is used when authors do not declare a specific context.

When no context is specified in the library, and the model has not declared a default context, the default context is Unfiltered.

Because the context has been established as Patient, the expression has access to patient-specific concepts such as the AgeInYearsAt() operator and the Patient.gender attribute. Note that the attributes available in the Patient context are defined by the data model in use.

A library may contain zero or more context statements, with each context statement establishing the context for subsequent statements in the library.

Effectively, the statement context Patient defines an expression named Patient that returns the patient data for the current patient, as well as restricts the information that will be returned from a retrieve to a single patient, as opposed to all patients.

As another example, consider a Practitioner context:

The above definition results in all the encounters for a particular practitioner. For more information on context, refer to the Retrieve Context discussion below.

A CQL Library can contain zero or more define statements describing named expressions that can be referenced either from other expressions within the same library or by containing quality and decision support artifacts.

The following example illustrates a simple define statement:

This example defines the InpatientEncounters expression as Encounter events whose code is in the "Inpatient" valueset, whose length is less than or equal to 120 days, and whose period ended (i.e. patient was discharged) during MeasurementPeriod.

Note that the use of terms like Encounter, length, and period, as well as which code attribute is used to compare with the valueset, are defined by the data model being used within the library; they are not defined by CQL.

For more information on the use of define statements, refer to the Using Define Statements section.

The retrieve expression is a reflection of the idea that clinical data in general can be viewed as clinical statements of some type as defined by the model. The type of the clinical statement determines the structure of the data that is returned by the retrieve, as well as the semantics of the data involved.

The type may be a general category, such as a Condition, Procedure, or Encounter, or a more specific instance such as an ImagingProcedure or a LaboratoryTest. The data model defines the available types that may be referenced by a retrieve.

In the simplest case, a retrieve specifies only the type of data to be retrieved. For example:

Assuming the default context of Patient, this example retrieves all Encounter statements for a patient.

In addition to describing the type of clinical statements, the retrieve expression allows the results to be filtered using terminology, including valuesets, code systems, or by specifying a single code. The use of codes within clinical data is ubiquitous, and most clinical statements have at least one code-valued attribute. In addition, there is typically a “primary” code-valued attribute for each type of clinical statement. This primary code is used to drive the terminology filter. For example:

This example requests only those Conditions whose primary code attribute is a code from the valueset identified by "Acute Pharyngitis". The attribute used as the primary code attribute is defined by the data model being used.

In addition, the retrieve expression allows the filtering attribute name to be specified:

This requests clinical statements that assert the presence of a condition with a severity in the "Acute Severity" valueset.

Note that the terminology reference "Acute Severity" in the above examples is a valueset, but it could also be a code system, a concept, or a specific code:

The "Get Condition from Code Declaration" expression returns conditions for the patient where the code is equivalent to the "Acute Pharyngitis Code" code. The "Get Condition from CodeSystem Declaration" expression returns conditions for the patient where the code is some code in the "SNOMED" code system.

When the primary code attribute is used (i.e. no filtering attribute name is specified in the retrieve), the retrieve uses the membership operator (in) if the terminology target is a valueset or code system, and the equivalent operator (~) otherwise. For more information about using the equivalent operator with terminology, refer to the Code section. For more information about using the membership oeprator with terminology, refer to the Terminology Operators section.

When the code path is specified, the code comparison operation can be specified as well:

Note the last example here is using the equality operator ([.sym#=#]) to indicate the terminology match should be exact (meaning that it will consider code system version and display as well as the code and system). Equality, equivalence, and membership are the only allowed terminology comparison operators within a retrieve.

Within the Patient context, the results of any given retrieve will always be scoped to a single patient, as determined by the environment. For example, in a quality measure evaluation environment, the Patient context may be the current patient being considered. In a clinical decision support environment, the Patient context would be the patient for which guidance is being sought.

By contrast, if the Unfiltered context is used, the results of any given retrieve will not be limited to a particular context. For example:

When evaluated within the Patient context, the above example returns "Acute Pharyngitis" conditions that onset during MeasurementPeriod for the current patient only. In the Unfiltered context, this example returns all "Acute Pharyngitis" conditions that onset during MeasurementPeriod, regardless of patient.

As another example, consider the set of encounters:

Depending on the context the retrieve above will return:

Consider the figure below:

Figure 2‑B - Unfiltered vs Patient context

Because context is associated with each declaration, it is possible for expressions defined in a particular context to reference expressions defined in the Unfiltered context and vice versa. Best practice is for each library to have expressions in only one context, and for that context declaration to be the first declaration in the library.

Note that it is not legal for an expression in one specified context to reference an expression in another specified context. This is because there must be a way to relate cross-context queries, which is only possible in the Unfiltered context, or through the use of a cross-context retrieve.

In an Unfiltered context, a reference to a specified context expression (such as Patient) results in the execution of that expression for each patient in the unfiltered context, and the implementation environment combines the results.

If the result type of an expression in a specific context is not a list, the result of accessing it from an Unfiltered context will be a list with elements of the type of the expression. For example:

In the above example, the InitialPopulationCount expression returns the number of patients for which the InInitialPopulation expression evaluated to true.

If the result type of the Patient context expression is a list, the result will be a list of the same type, but with the results of the evaluation for each patient in the unfiltered context flattened into a single list.

In a specific context (such as Patient), a reference to an Unfiltered context expression results in the evaluation of the Unfiltered context expression, and the result type is unaffected.

The where clause allows the results of the query to be filtered by a condition that is evaluated for each element of the query being filtered. If the condition evaluates to true for the element being tested, that element is included in the result. Otherwise, the element is excluded from the resulting list.

A syntax diagram of a where clause can be seen here.

For example:

The alias E is used to access the period attribute of each encounter in the primary source. The filter condition tests whether the duration of that range is at least 120 days.

The condition of a where clause is allowed to contain any arbitrary combination of operations of CQL, so long as the overall result of the condition is boolean-valued. For example, the following where clause includes multiple conditions on different attributes of the source:

Note that because CQL uses three-valued logic, the result of evaluating any given boolean-valued condition may be unknown (null). For example, if the list of inpatient encounters from the first example contains some elements whose period attribute is null, the result of the condition for that element will not be false, but null, indicating that it is not known whether or not the duration of the encounter was at least 120 days. For the purposes of evaluating a filter, only elements where the condition evaluates to true are included in the result, effectively ignoring the entries for which the logical expression evaluates to null. For more discussion on three-valued logic, see the section on Missing Information in the Author’s Guide, as well as the section on Nullological Operators in the Developer’s guide.

The return clause of a CQL query allows the results of the query to be shaped. In most cases, the results of a query will be of the same type as the primary source of the query. However, some scenarios require only specific elements be extracted, or computations on the data involved in each element be performed. The return clause enables this type of query.

A syntax diagram of a return clause can be seen here.

For example:

This example returns a list of tuples (structured values), one for each inpatient encounter performed, where each tuple consists of the id of the encounter as well as a lengthOfStay element, whose value is calculated by taking the duration of the period for the encounter. Tuples are discussed in detail in later sections. For more information on Tuples, see Structured Values (Tuples).

By default, a query returns a list of distinct results, suppressing duplicates. To include duplicates, use the all keyword in the return clause. For example, the following will return a list of the lengths of stay for each Encounter:

If two encounters have the same value for lengthOfStay, that value will only appear once in the result unless the all keyword is used:

CQL queries can sort results in any order using the sort by clause.

A syntax diagram of a sort clause can be seen here.

For example:

This example returns inpatient encounters, sorted by the start of the encounter period.

Results can be sorted ascending or descending using the asc (ascending) or desc (descending) keywords:

If no ascending or descending specifier is provided, the order is ascending.

Calculated values can also be used to determine the sort:

Note that the properties that can be specified within the sort clause are determined by the result type of the query. In the above example, lengthOfStay can be referenced because it is introduced in the return clause. Because the sort applies after the query results have been determined, alias references are neither required nor allowed in the sort.

If no sort clause is provided, the order of the result is unprescribed and is implementation specific.

The sort clause may include multiple attributes, each with their own sort order:

Sorting is performed in the order in which the attributes are defined in the sort clause, so this example sorts by period descending, then by identifier ascending.

When the sort elements do not provide a unique ordering (i.e. there is a possibility of duplicate sort values in the result), the order of duplicates is unspecified.

A query may only contain a single sort clause, and it must always appear last in the query.

When the data being sorted includes nulls, they are considered lower than any non-null value, meaning they will appear at the beginning of the list when the data is sorted ascending, and at the end of the list when the data is sorted descending.

In addition to filtering by conditions, some scenarios need to be able to filter based on relationships to other sources. The CQL with and without clauses provide this capability. For the examples in this section, consider the following simple information model:

Figure 2‑C - Simple patient information model

This query returns "Ambulatory/ED Visit" encounters performed where the patient also has a condition of "Acute Pharyngitis" that overlaps after the period of the encounter.

The without clause returns only those elements from the primary source that do not have a specific relationship to another source. For example:

This query is the same as the previous example, except that only encounters that do not have overlapping conditions of "Acute Pharyngitis" are returned. In other words, if the such that condition evaluates to true (if the Encounter has an overlapping Condition of Acute Pharyngitis in this case), then that Encounter is not included in the result.

A syntax diagram of a with clause and without clause.

A given query may include any number of with and without clauses in any order, but they must all come before any where, return, or sort clauses.

The such that conditions in the examples above used Timing Relationships (e.g. during, after end of), but any expression may be used, so long as the overall result is boolean-valued. For example:

This example retrieves all dispense records for active prescriptions of Warfarin.

When multiple with or without clauses appear in a single query, the result will only include elements that meet the such that conditions for all the relationship clauses. For example:

This example retrieves all the elements returned by the expression MeasurementPeriodEncounters that have both a related Pharyngitis and Antibiotics result.

The clauses described in the previous section must appear in the correct order in order to specify a valid CQL query. The general order of clauses is:

A query must contain an aliased primary source, but this is the only required clause.

A query may contain zero or more with or without clauses, but they must all appear before any where, return, or sort clauses.

A query may contain at most one where clause, and it must appear after any with or without clauses, and before any return or sort clauses.

A query may contain at most one return clause, and it must appear after any with or without or where clauses, and before any sort clause.

A query may contain at most one sort clause, and it must be the last clause in the query.

For example:

This query returns all "Inpatient" encounter events that have an overlapping condition of "Acute Pharyngitis" and a duration of at least 120 days. For each such event, the result will include the id of the event and the duration in days, and the results will be ordered by that duration descending.

As another example, consider a query with multiple without clauses:

Even though this example has multiple without clauses, there is still only a single where clause for the query.

Note that the query construct in CQL supports other clauses that are not discussed here. For more information on these, refer to Introducing Scoped Definitions In Queries and Multi-Source Queries.

CQL supports several types of simple values:

Table 2‑E - Types of simple values that CQL supports

In addition to simple values, CQL supports some types of values that are specific to the clinical quality domain. For example, CQL supports codes, concepts, quantities, ratios, and valuesets.

Structured values, or tuples, are values that contain named elements, each having a value of some type. Clinical information such as a Medication, a Condition, or an Encounter is represented using tuples.

For example, the following expression retrieves the first Condition with a code in the "Acute Pharyngitis" valueset for a patient:

The values of the elements of a tuple can be accessed using a dot qualifier (.) followed by the name of the element:

Tuples can also be constructed directly using a tuple selector.

A syntax diagram of a tuple selector can be seen here.

For example:

If the tuple is of a specific type, the name of the type can be used instead of the Tuple keyword:

If the name of the type is specified, the tuple selector may only contain elements that are defined on the type, and the expressions for each element must evaluate to a value of the defined type for the element. Any elements defined in the class but not present in the selector will be null.

Note that tuples can contain other tuples, as well as lists:

Accordingly, element access can nest as deeply as necessary:

This accesses the City element of the Address element of Info. Lists can be traversed within element accessors using the list indexer ([]):

This accesses the Number element of the first element of the Phones list within Info.

In addition, to simplify path traversal for models that make extensive use of list-valued attributes, the indexer can be omitted:

The result of this invocation is a list containing the Number elements of all the Phones within Info.

CQL supports the representation of lists of any type of value (including other lists). Although some operations may result in lists containing mixed types, in normal use cases, lists contain items that are all of the same type.

Lists can be constructed directly, as in:

But more commonly, lists of tuples are the result of retrieve expressions. For example:

This expression results in a list of tuples, where each tuple’s elements are determined by the data model in use.

Lists in CQL use zero-based indexes, meaning that the first element in a list has index 0. For example, given the list of integers:

The first element is 6 and has index 0, the second element is 7 and has index 1, and so on.

Note that in general, clinical data may be expected to contain various types of collections such as sets, bags, lists, and arrays. For simplicity, CQL deals with all collections using the same collection type, the list, and provides operations to enable dealing with different collection types. For example, a set is a list where each element is unique, and any given list can be converted to a set using the distinct operator.

For a description of the distinct operator, as well as other operations that can be performed with lists, refer to the List Operators section.

CQL supports the representation of intervals, or ranges, of values of various types. In particular, intervals of date and time values, and ranges of integers and reals.

Intervals in CQL are represented by specifying the low and high points of the Interval and whether the boundary is inclusive (meaning the boundary point is part of the interval) or exclusive (meaning the boundary point is excluded from the interval). Following standard mathematics notation, inclusive (closed) boundaries are indicated with square brackets, and exclusive (open) boundaries are indicated with parentheses.

A syntax diagram of an Interval construct can be seen here.

For example:

This expression results in an Interval that contains the integers 3 and 4, but not 5.

This expression results in an Interval that contains all the real numbers >= 3.0 and < 5.0.

Intervals can be constructed based on any type that supports unique and ordered comparison. For example:

This expression results in an Interval that begins at midnight on January 1, 2014, ends just before midnight on December 31, 2014 and is equivalent to the following interval:

Furthermore, take the following example:

This expression results in an Interval that begins on January 1, 2014 at an undefined time, ends at an undefined time on December 31, 2014 and is equivalent to the following interval:

Note that the ending boundary must be greater than or equal to the starting boundary to construct a valid interval. Attempting to specify an invalid Interval will result in a run-time error. For example:

It is valid to construct an Interval with the same start and end boundary, so long as the boundaries are inclusive:

Such an Interval contains only a single point and can be called a unit interval. For unit intervals, the point from operator can be used to extract the single point from the interval. Attempting to use point from on a non-unit-interval will result in a run-time error.

For all the comparison operators, the result type of the operation is Boolean, meaning they may result in true, false, or null (meaning unknown). In general, if either or both of the values being compared is null, the result of the comparison is null.

The most basic operation in CQL involves comparison of two values. This is accomplished with the built-in comparison operators:

Table 2‑H - The built-in comparison operators that CQL provides

In general, the equality and inequality operators can be used on any type of value within CQL, but both arguments must be the same type. For example, the following equality comparison is legal, and returns true:

However, the following equality comparison is invalid because numbers and strings cannot be meaningfully compared:

Attempting to compare numbers and strings as in this example will result in an error message indicating that there is no equality (=) operator available to compare numbers and strings.

For Decimal values, equality is defined to ignore trailing zeroes.

For Date and Time values, equality is defined to account for the possibility that the Date and Time values involved are specified to varying levels of precision. For a complete discussion of this behavior, refer to Comparing Dates and Times.

For structured values, equality returns true if the values being compared are the same type (meaning they have the same types of elements) and the values for each element are the same value. For example, the following comparison returns true:

For lists, equality returns true if the lists contain the same elements in the same order. For example, the following lists are equal:

And the following lists are not equal:

Note that in the above example, if the second list was sorted ascending prior to the comparison, the result would be true.

For intervals, equality returns true if the intervals use the same point type and cover the same range. For example:

This returns true because the intervals cover the same set of points, 1 through 5.

The relative comparison operators (>, >=, <, <=) can be used on types of values that have a natural ordering such as numbers, strings, and dates.

The between operator is shorthand for comparison of an expression against an upper and lower bound. For example:

This expression is equivalent to:

For all the comparison operators, the result type of the operation is Boolean. Note that because CQL uses three-valued logic, if either or both of the arguments is null, the result of the comparison is null (meaning unknown). This is true for all the comparison operators except equivalent (~) and not equivalent (!~). The equivalent operator is generally the same as equality, except that it returns true if both of the arguments are null, and false if one argument is null and the other is not:

The expression NullEqualityTest results in null, whereas the expression NullEquivalenceTest results in false.

In addition, equivalence is defined more loosely than equality for some types:

For more detail, see the definitions of Equal and Equivalent in the CQL reference.

Combining the results of comparisons and other boolean-valued expressions is essential and is performed in CQL using the following logical operations:

Table 2‑I - Logical operations that CQL provides

The following examples illustrate some common uses of logical operators:

Note that all these operators are defined using three-valued logic, which is defined specifically to ensure that certain well-established relationships that hold in standard Boolean (two-valued) logic also hold. The complete semantics for each operator are described in the Logical Operators section of Appendix B – CQL Reference.

The expression of clinical logic often involves numeric computation, and CQL provides a complete set of arithmetic operations for expressing computational logic. In general, these operators have the standard semantics for arithmetic operators, with the general caveat that unless otherwise stated in the documentation for a specific operation, if any argument to an operation is null, the result is null. In addition, calculations that cause arithmetic overflow or underflow, or otherwise cannot be performed (such as division by 0) will result in null, rather than a run-time error.

The following table lists the arithmetic operations available in CQL:

Table 2‑J - Arithmetic operations that CQL provides

Operations on date and time data are an essential component of expressing clinical knowledge, and CQL provides a complete set of date and time operators. These operators broadly fall into five categories:

Clinical information often contains not only date and time information as timestamps (points in time), but intervals of time, such as the effective time for an encounter or condition. Moreover, clinical logic involving this information often requires the ability to relate this temporal information. For example, a clinical quality measure might look for “patients with an inpatient encounter during which a condition started”. CQL provides an exhaustive set of operators for describing these types of temporal relationships between clinical information.

These interval operations can be broadly categorized as follows:

Clinical information is almost always stored, collected, and presented in terms of lists of information. As a result, the expression of clinical knowledge almost always involves dealing with lists of information in some way. The query construct already discussed provides a powerful mechanism for dealing with lists, but CQL also provides a comprehensive set of operations for dealing with lists in other ways. These operations can be broadly categorized into three groups:

Summaries and statistical calculations are a critical aspect of being able to represent clinical knowledge, especially in the quality measurement domain. Thus, CQL includes a comprehensive set of aggregate operators.

Aggregate operators are defined to work on lists of values. For example, the Count operator works on any list:

This expression returns the number of Encounter events.

The Sum operator, however, works only on lists of numbers or lists of quantities:

This example results in the sum 15. To sum the results of a list of Observation values, for example, a query is used to extract the values to be summed:

In general, nulls encountered during aggregation are ignored, and with the exception of Count, AllTrue, and AnyTrue, the result of the invocation of an aggregate on an empty list is null. Count is defined to return 0 for an empty list. AllTrue is defined to return true for an empty list, and AnyTrue is defined to return false for an empty list. In addition, operations that cause arithmetic overflow or underflow, or otherwise cannot be performed (such as division by 0) will result in null, rather than a run-time error.

The following table lists the aggregate operators available in CQL:

Table 2‑T - The aggregate operators available in CQL

CQL supports several operators for use with the various clinical types in the language.

The running example for this walkthrough is a simplification of CMS153, version 2, Chlamydia Screening for Women. The original QDM for this measure was simplified by including only references to the following QDM data elements:

This results in the following QDM:

Note that these simplifications result in a measure that is not clinically relevant, and the result of this walkthrough is in no way intended to be used in a production scenario. The walkthrough is intended only to demonstrate how CQL can be used to construct shareable clinical logic.

As an aside, one of the simplifications made to the QDM presented above is the removal of the notion of occurrencing. Readers familiar with that concept as defined in QDM should be aware that CQL by design does not include this notion. CQL queries are expressive enough that the correlation accomplished by occurrencing in QDM is not required in CQL.

The following table lists the QDM data elements involved and their mappings to the QUICK data structures:

Table 2‑V - QDM Data elements and their mapping to QUICK data structures

Note that the specific mapping to the QUICK data structures is beyond the scope of this walkthrough; it is only provided here to demonstrate the link back to the original QDM.

Note also that the use of the QDM as a starting point was deliberately chosen to provide familiarity and is not a general requirement for building CQL. Artifact development could also begin directly from clinical guidelines expressed in other formats or directly from relevant clinical domain expertise. Using the QDM provides a familiar way to establish the starting requirements.

For clinical quality measures, the CQL library simply provides a repository for definitions of the populations involved. CQL is intended to support both CQM and CDS applications, so it does not contain quality measure specific constructs. Rather, the containing artifact definition, such as an HQMF document, would reference the appropriate criteria expression by name within the CQL document.

With that in mind, a CQL library intended to represent the logic for a CQM must expose at least the population definitions needed for the measure. In this case, we have criteria definitions for:

Looking at the Initial Population, we have the demographic criteria:

For the age criteria, CQL defines an AgeInYearsAt operator that returns the age of the patient as of a given date or datetime. Using this operator, and assuming a measurement period of the year 2013, we can express the patient age criteria as:

In order to use the AgeInYearsAt operator, we must be in the Patient context:

In addition, to allow this criteria to be referenced both within the CQL library by other expressions, as well as potentially externally, we need to assign an identifier:

Because the quality measure is defined over a measurement period, and many, if not all, of the criteria we build will have some relationship to this measurement period, it is useful to define the measurement period directly:

This establishes MeasurementPeriod as the interval beginning precisely at midnight on January 1^st, 2013, and ending immediately before midnight on January 1^st, 2014. We can now use this in the age criteria:

Even more useful would be to define MeasurementPeriod as a parameter that can be provided when the quality measure is evaluated. This allows us to use the same logic to evaluate the quality measure for different years. So instead of using a define statement, we have:

The InInitialPopulation expression remains the same, but it now accesses the value of the parameter instead of the define statement.

Since we are in the Patient context and have access to the attributes of the Patient (as defined by the data model in use), the gender criteria can be expressed as follows:

This criteria requires that the gender attribute of a Patient be a code that is in the valueset identified by "Female Administrative Sex". Of course, this requires the valueset definition:

Putting it all together, we now have:

The next step is to capture the rest of the initial population criteria, beginning with this QDM statement:

This criteria has three main components:

Using the mapping to QUICK, the equivalent retrieve in CQL is:

This query retrieves all Condition events for the patient with a code in the "Other Female Reproductive Conditions" valueset that overlap the measurement period. Note that in order to use the overlaps operator, we had to construct an interval from the onsetDateTime and abatementDate elements. If the model had an interval-valued “effective time” element, we could have used that directly, rather than having to construct an interval.

The result of the query is a list of conditions. However, this isn’t quite what the QDM statement is actually saying. In QDM, the statement can be read loosely as “include patients in the initial population that have at least one active diagnosis from the Other Female Reproductive Conditions valueset.” To express this in CQL, what we really need to ask is whether the equivalent retrieve above returns any results, which is accomplished with the exists operator:

Incorporating the next QDM statement:

OR: "Diagnosis: Genital Herpes" overlaps with "Measurement Period"

We have:

Which we can repeat for each Diagnosis, Active statement. Note here that even though we are using the same alias, C, for each query, they do not clash because they are only declared within their respective queries (or scopes).

Next, we get to the Laboratory Test statements:

We use the same approach. The equivalent retrieve for the first criteria is:

This query is retrieving pregnancy tests that were completed within the measurement period. Because diagnostic orders do not have a top-level completion date, the date must be retrieved with a nested query on the events associated with the diagnostic orders. The nested query returns the set of completed events ordered by their completion date, the Last invocation returns the most recent of those events, and the .date accessor retrieves the value of the date element of that event.

And finally, translating the rest of the statements allows us to express the entire initial population as:

Because CQL allows any number of define statements with any identifiers, we can structure the logic of the measure to communicate more meaning to readers of the logic. For example, if we look at the description of the quality measure:

it becomes clear that the intent of the Diagnosis, Active and Laboratory Test, Order QDM criteria is to attempt to determine whether or not the patient is sexually active. Of course, we’re dealing with a simplified measure and so much of the nuance of the original measure is lost; the intent here is not to determine whether this is in fact a good way in practice to determine whether or not a patient is sexually active, but rather to show how CQL can be used to help communicate aspects of the meaning of quality logic that would otherwise be lost or obscured.

With this in mind, rather than expressing the entire initial population as a single define, we can break it up into several more understandable and more meaningful expressions:

Restructuring the logic in this way not only simplifies the expressions involved and makes them more understandable, but it clearly communicates the intent of each group of criteria.

Note that the InInitialPopulation expression is returning a boolean value indicating whether or not the patient should be included in the initial population.

The next population to define is the denominator, which in our simplified expression of the measure is the same as the initial population. Because the intent of the CQL library for a quality measure is only to define the logic involved in defining the populations, it is assumed that the larger context (such as an HQMF artifact definition) is providing the overall structure, including the meaning of the various populations involved. As such, each population definition with the CQL library should include only those aspects that are unique to that population.

For example, the actual criteria for the denominator is that the patient is in the initial population. But because that notion is already implied by the definition of a population measure (that the denominator is a subset of the initial population), the CQL for the denominator should simply be:

This approach to defining the criteria is more flexible from the perspective of actually evaluating a quality measure, but it may be somewhat confusing when looking at the CQL in isolation.

Note that the approach to defining population criteria is established by quality measure-specific guidance outside the scope of this specification. We follow this approach here just for simplicity.

Following this approach then, we express the numerator as:

Note that the R.result is not null condition is required because the original QDM statement involves a test for the presence of an attribute:

The (result) syntax indicates that the item should only be included if there is some value present for the result attribute. The equivalent expression in CQL is the null test.

Finally, putting it all together, we have a complete, albeit simplified, definition of the logic involved in defining the population criteria for a measure:

Using the same simplified measure expression as a basis, we will now build a complementary clinical decision support rule that can provide guidance at the point-of-care. In general, when choosing what decision support artifacts will be most complementary to a given quality measure, several factors must be considered including EHR and practitioner workflows, data availability, the potential impacts of the guidance, and many others.

Though these are all important considerations and should not be ignored, they are beyond the scope of this document, and for the purposes of this walkthrough, we will assume that a point-of-care decision support intervention has been selected as the most appropriate artifact.

When building a point-of-care intervention based on a quality measure, several specific factors must be considered.

First, quality measures typically contain logic designed to identify a specific setting in which a particular aspect of health quality is to be measured. This usually involves identifying various types of encounters. By contrast, a point-of-care decision support artifact is typically written to be evaluated in a specific context, so the criteria around establishing the setting can typically be ignored. For the simplified measure we are dealing with, the encounter setting criteria were removed as part of the simplification.

Second, quality measures are designed to measure quality within a specific timeframe, whereas point-of-care measures don’t necessarily have those same restrictions. For example, the diagnoses in the current example are restricted to the measurement period. There may be some clinically relevant limit on the amount of time that should be used to search for diagnoses, but it does not necessarily align with the measurement period. For the purposes of this walkthrough, we will make the simplifying assumption that any past history of the relevant diagnoses is a potential indicator of sexual activity.

Third, quality measures are written retrospectively, that is, they are always dealing with events that occurred in the past. By contrast, decision support artifacts usually involve prospective, as well as retrospective data. As such, different types of clinical events may be involved, such as planned or proposed events.

Fourth, quality measures, especially proportion measures, typically express the numerator criteria as a positive result, whereas the complementary logic for a decision support rule would be looking for the absence of the criteria. For example, the criteria for membership in the numerator of the measure we are using is that the patient has had a Chlamydia screening within the measurement period. For the point-of-care intervention, that logic becomes a test for patients that have not had a Chlamydia screening.

And finally, although present in some quality measures, many do not include criteria to determine whether or not there is some practitioner- or patient-provided reason for not taking some course of action. This is often due to the lack of a standardized mechanism for describing this criteria and is usually handled on a measure-by-measure basis as part of actually evaluating measures. Regardless of the reason, because a point-of-care intervention has the potential to interrupt a practitioner workflow, the ability to determine whether or not a course of action being proposed has already been considered and rejected is critical.

With these factors in mind, and using the CQL for the measure we have already built, deriving a point-of-care intervention is fairly straightforward.

To begin with, we are using the same data model, QUICK, the same valueset declarations, and the same context:

Note that we are not using the MeasurementPeriod parameter. There are other potential uses for parameters within the point-of-care intervention (for example, to specify a threshold for how far back to look for a Chlamydia screening), but we are ignoring those aspects for the purposes of this walkthrough.

For the Patient16To23AndFemale criteria, we are then simply concerned with female patients between the ages of 16 and 24, so we change the criteria to use the AgeInYears, rather than the AgeInYearsAt operator, to determine the patient’s age as of today:

Similarly for the SexuallyActive criteria, we remove the relationship to the measurement period:

For the numerator, we need to invert the logic, so that we are looking for patients that have not had a Chlamydia screening, and rather than the measurement period, we are looking for the test within the last year:

In addition, we need a test to ensure that the patient does not have a planned Chlamydia screening:

And to ensure that there is not a reason for not performing a Chlamydia screening:

We combine those into a NoScreening criteria:

And finally, we provide an overall condition that indicates whether or not this intervention should be triggered:

Now, this library can be referenced by a CDS knowledge artifact, and the condition can reference the NeedScreening expression, which loosely reads: the patient needs screening if they are in the appropriate demographic, have indicators of sexual activity, and do not have screening.

In addition, this library should include the proposal aspect of the intervention. In general, the overall artifact definition (such as a CDS KAS artifact) would define what actions should be performed when the condition is satisfied. Portions of that action definition may reference other expressions within a CQL library, just as the HQMF for a quality measure may reference multiple expressions within CQL to identify the various populations in the measure. In this case, the intervention may construct a proposal for a Chlamydia Screening:

The containing artifact would then use this expression as the target of an action, evaluating the expression if the condition of the decision support rule is met, and returning the result as the proposal to the calling environment.

The previous examples of building a quality measure and a decision support artifact have so far demonstrated the ability to describe the logic involved using the same underlying data model, as well as the same expression language. Now we can take that one step further and look at the use of CQL libraries to actually express the artifacts using the same logic, rather than just the same data model and language.

We start by identifying the aspects that are identical between the two:

With these in mind, we can create a new library, CMS153_Common, that will contain the common elements:

Using this library, we can then rewrite the CQM to reference the common elements from the library:

Note: The keyword called was chosen to avoid confusion with the keyword as, which is used for type-casting. We also don’t use as for aliasing like many SQL dialects do, for the same reason. We mean called here in the sense that the library is "called a name" within this context, not that we intend to "call it by this name".

And similarly for the CDS artifact:

In addition to sharing between quality measures and clinical decision support artifacts, the use of common libraries will allow the same logic to be shared by multiple quality measures or decision support artifacts. For example, a set of artifacts for measurement and improvement of the treatment of diabetes could all use a common library that provides base definitions for determining when a patient is part of the population of interest.