Common issues using CQL

Boolean or Value

You can use CQL Reports to obtain actual values from CQL expressions, but Scorecards and the Query Builder are limited to boolean results. 
To see the number obtained by an entity for a rule, though, you can hover over the failing rule in both the Entity > Scorecards UI and the Scorecards > Entity UI.

Specificity with git.fileContents()

git.fileContents()

Using this command, we can't see if there's any type of file (e.g. YAML) — because of how Git works, we can only retrieve specific files.

As a workaround, use the tag variable and the service tag:

git.fileExists("myservice" + tag + "yaml")

Completing examples

Examples in the query builder may need completion to be utilized. On it's own, the first example below will return an error, as a qualifying side of the equation needs to be added, such as .count > 0 or .length > 0

Examples for git.codeSearch:

git.codeSearch(query = "icon", in_file = true, file_extension = "css")

git.codeSearch(query = "icon", in_file = true, file_extension = "css").length > 0

Custom Data and reserved keywords

In a scenario where you have a Service YAML with Custom Data, you should be aware of reserved keywords in CQL and how to work around them. An error message as below will appear if you are attempting to use a reserved keyword.

Excerpt of Custom Data in Service YAML

x-cortex-custom-metadata:
  contacts:
    oncall: foo

If you attempt to run a CQL expression using this oncall keyword, you will encounter a challenge as this keyword is reserved.

CQL expression example that will not function

custom("contacts")?.oncall != null

This will result in an error message: no viable alternative at input 'custom("contacts")?.oncall'

CQL expression to be used instead:

custom("contacts").oncall != null

Using .filter

CQL queries using "and" often provide results that match an "either" query, not "both."

We recommend using ".filter" on individual items to have both meet the criteria of the query.

Here's an example where the link name and URL must both match for the query to pass:

links("Monitoring").filter((link) => link.name == "Test Link" and link.url.matches("https://mytesturl.com+")).length > 0

Properties with a period in them

CQL queries targeting a property that has multiple periods in them will need to be surrounded in escaped quotes, for example, \"a.single.property\". If this is not done, each part of the property will be considered to be separate searchable properties and target incorrect part of your data.  An example of use in a query would be something like the following:

jq(git.fileContents("service/some.yaml"),".properties.\"a.single.property\"")