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 true

  • Example: entity.type() == "container" AND entity.tag() == "production"

• Use OR to allow for multiple possibilities

  • Example: entity.type() == "container" OR entity.type() == "function"

• Combine AND and OR with parentheses

  • Example: (entity.type() == "container" OR entity.type() == "function") AND entity.tag() == "production"

• Use ! to negate a condition

  • Example: !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.

Learn more about captures

• See additional instructions on using captures in Cortex's CQL explorer.
• Read about a capture use case in Scorecard examples: Using CQL captures to display the cause of rule failures.

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.

Click Tools > Query builder from 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:

  1. Click the flag icon on the right side of your Cortex workspace.

     
  2. 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.