Cortex Query Language (CQL)
Cortex Query Language (CQL) is a proprietary domain-specific language (DSL) you can use to query details in-depth about your Cortex entities. CQL is at the core of many Cortex features, from defining how Scorecards evaluate health and readiness to deciding which entities a plugin should appear on.
With CQL, you can:
Query your data immediately (including from third-party integrations or custom data), without having to move it, transform it, or wait for batch jobs
Cortex does not require you to configure custom processes for each new standard you want to track
Use basic arithmetic and utility functions to get the data you need
Customize Scorecard rules to query information needed to assess your processes quickly
For example, you can use CQL captures to display the cause of rule failures in a Scorecard.
Create reusable CQL reports to view any query result, such as the number of incidents your services had in the last week
CQL allows you to ask multi-source questions, such as, "Who's on call for services in our payment product?" or "Which services are still on the old secrets manager?"
It also provides a consistent way to write rules, regardless of the data source. For example, you can use git.fileExists()
to search across all of your Git repositories without needing to specify the Git provider.
CQL basics
See additional CQL instructions and examples in the CQL explorer in your workspace.
CQL format and data sources
CQL queries use the format data source
function
quantifier
, with the function
and quantifier
options differing depending on the data source and type.
The data sources for CQL are:
Entity metadata: Core entity details
Example query:
dependencies.in().length
Integrations: Data from third-party sources
Example query:
jira.numOfIssues()
Custom data: Data attached to the entity, sent via API or defined in the entity YAML
Example query:
custom("cloud-cost") .cost.compute.actual
Combining CQL expressions
You can combine CQL expressions in multiple ways:
Use
AND
to require multiple conditions to be trueExample:
entity.type() == "container" AND entity.tag() == "production"
Use
OR
to allow for multiple possibilitiesExample:
entity.type() == "container" OR entity.type() == "function"
Combine
AND
andOR
with parenthesesExample:
(entity.type() == "container" OR entity.type() == "function") AND entity.tag() == "production"
Use
!
to negate a conditionExample:
!entity.tag() == "production"
Captures
You can include entity or CQL evaluation data in a rule's description and failure message using captures. This will enable you to create a Scorecard rule description or failure message that reflects the rule’s score and affected entity descriptor information (including dependencies and custom data if set in the YAML). Captures allow you to update your rule expressions to “capture” certain pieces of an expression into variables.
CQL tools
The Query builder tool
The Query builder allows you to leverage all of CQL's power to investigate information about your entities without building an entire Scorecard.
The functionality of the Query builder depends on your permissions. Users who have the ability to edit Scorecards can run queries that talk to third-party integrations. Users without those permissions can run queries on custom data and anything else that exists within Cortex. Users classified as viewers are not able to run queries.
To see the Query builder, click Tools > Query builder in the main nav.

Using custom data in CQL queries
You can add custom data to any entity, and you can access custom data from any entity's details page. For example, if you run a security scanning tool that isn't in the list of existing integrations, you may run a vulnerability scan as part of your CI process and then send that data to Cortex.
With the Query builder, you can query against any of this custom data. Anything that can be evaluated with a Scorecard will display in the Query builder, which allows you to essentially use Cortex as a database. Because Cortex is able to pull data from many data sources, the Query builder can even provide more insight than GitHub search.
CQL explorer
CQL explorer contains instructions and examples for specific data types, entity metadata, custom data, and more.
You can access it via Query builder or as a standalone page:
On the Query builder page: On the right side of the Query builder, click the CQL explorer tab to view CQL instructions and examples for specific data types, entity metadata, custom data, and more.
CQL explorer is on the right side of the Query builder. As a standalone page:
Click the flag icon on the right side of your Cortex workspace.
In the Help & Docs side panel, click CQL explorer.
CQL reports
CQL reports allow you to query all of the raw data in Cortex and build a custom report on the data. Learn more in Using CQL reports.
Running and saving CQL queries
To learn about running queries and saving queries, see Running and saving CQL queries.
Last updated
Was this helpful?