CQL Error Messages

CQL Error Messages

As with any language, it is possible to construct statements in CQL that contain errors. The process of validating CQL finds these errors, and authoring environments return errors from this validation process to users to help build correct statements.

It's helpful to think of these messages in the same context as forming a correct sentence in any language. We can do this by considering the kinds of errors that are possible:

1. Typographical Errors
2. Grammatical Errors
3. Errors in Meaning

Typographical Errors

Typographical errors are things like misplaced punctuation, misspellings of key words, and similar errors. For example:

Thx ;qikc r3dd fawks jump#d ov8r th3 lazy; br"oiw d@huwg

In human communication, these types of errors obscure meaning, but humans can generally get through them. For a machine, however, this is a significant barrier. These types of errors (often called "lexical" errors) are handled by the first phase of validation, which ensures that all the pieces of a statement are well understood.

Grammatical Errors

Grammatical errors occur when sentences misuse categories of words like nouns and verbs, or place words in incorrect order. For example:

Quickly fox red the jumped lazy dog over brown.

The sentence is typographically correct, there are no misspellings or misuse of punctuation, but grammatically, the construction is invalid. In this simple example, the meaning probably still comes through for humans, but as with typographical errors, for a machine this represents a significant barrier. These types of errors (often called "syntax" errors) are handled by the second phase of validation, which ensures that statements are well formed according to the rules of CQL grammar.

Errors of Meaning

The third category of errors occur when sentences are typographically and grammatically correct, but construct sentences that have nonsensical meanings. For example:

Colorless green ideas sleep furiously.

The sentence is grammatically correct, it follows all the rules of the English language, but it is a nonsensical statement. These types of errors (often called "semantic" errors) are handled by the third phase of validation, which ensures, to the extent possible, that the CQL expression is valid. For example:

1 + 'John'

This is typographically and grammatically valid (often called "syntactically" valid) expression of CQL, but semantically, you cannot add numbers and strings together, because the + operator is not defined for the combination of numbers and strings.

CQL Validation Messages

When validating, CQL uses these categories of errors to help inform the author about things that have gone wrong during the process. These categories are referred to as:

1. Syntax Errors: Typographical or Grammatical errors
2. Semantic Errors: Errors of meaning

Syntax Errors

Typographical (Lexical) Errors

When the CQL validator cannot determine what pieces (tokens) a sentence is made up of, you'll receive a Syntax error with a pointer to the position in the expression that cannot be resolved. For example:

asdf;fjkla;oiwejf

Attempting to validate a random string of characters will typically result in an error like this:

Syntax error at asdf

More common errors in this category are things like missing a closing quote (\``) or parenthesis ()`) symbol:

define "Initial Population": ["Encounter, Performed: "XYZ"]
define "Combination": "Initial Population" and ("First Condition" or "Second Condition"

Would typically give something like:

Syntax error at XYZ
Syntax error at <EOF>

Note the second error, Syntax error at <EOF>. This is a special marker in the validation step that is used to indicate the End-Of-File, or the end of the input. It's typical of situations where the validator is looking for a closing mark but reaches the end of the input before it finds it.

Grammatical (Syntax) Errors

When the CQL validator encounters expressions of CQL that have no typographical errors, but do not conform to the rules of the language, it will return a Syntax error with information about where the error occurred, and what the validator expected to find. For example:

define "Encounters": ["Encounter, Performed": "XYZ"] where relevantPeriod during "Measurement Period"

This expression is typographically correct, but it is missing a key syntactic element, the alias that introduces the query context. Without the alias, the keyword where cannot be used, so the validator returns a message:

Syntax error at where

Errors of Meaning (Semantic) Errors

One of the key syntactic elements in CQL is the identifier. Identifiers are used throughout the language to refer to things like data types, value sets, code systems, functions, query sources (via aliases) and expression definitions. If the validator cannot determine what an identifier is referring to, it will return an error indicating what identifier cannot be resolved, and what kind of thing was expected. For example:

define "Encounters": ["Encounter Performed": "XYZ"] E where E.relevantPeriod during "Measurement Period"

This is a syntactically valid expression, but in attempting to validate it, we need to know what the result of the retrieve (["Encounter Performed": "XYZ"]) is. To do this, the translator looks for a type named Encounter Performed in the data model being used (Quality Data Model, or QDM, in this case). Note the missing , in the name of the data type. This results in the validator not being able to find the type by its appropriate label, and it returns the error:

Could not resolve type name Encounter Performed.

If we correct that:

define "Encounters": ["Encounter, Performed": "XYZ"] E where E.relevantPeriod during "Measurement Period"

The validator then knows what type of data is being returned, and next validates the terminology filter, a reference to XYZ in this case. For a retrieve to be meaningful, the identifier must be a reference to a terminology item, a value set, code system, or direct reference code, so the validator tries to look up the identifier XYZ in the list of things it knows about it. Because we haven't defined XYZ in this library, it returns the error:

Could not resolve identifier XYZ in the current library.

And providing a value set declaration with the name XYZ solves this problem:

valueset "XYZ": 'urn:oid:1.2.3.4'