LogoLogo
Login to CortexBook a DemoCortex Academycortex.io
  • Cortex Docs
  • Cortex Quick Start
  • Ingesting data into Cortex
    • Managing Entities
      • Adding entities
        • Add services
        • Add domains
        • Add teams
        • Add custom entity types
        • Defining dependencies
      • Entity details page
      • Defining ownership
      • Defining relationship types
      • Grouping entities
      • Adding external documentation
      • Adding Deploy data
      • Adding custom data
      • Viewing discovered entities
      • Archiving entities
      • Relationship graph
      • Using On-call Assistant for incidents
      • Managing Terraform infra in Cortex
    • Managing Catalogs
    • Integrations
      • Internally hosted integrations
      • ArgoCD
      • AWS
      • Azure DevOps
      • Azure Resources
      • BambooHR
      • Bitbucket
      • BugSnag
      • Buildkite
      • Checkmarx
      • CircleCI
      • ClickUp
      • Codecov
      • Coralogix
      • Custom webhook integrations
      • Datadog
      • Dynatrace
      • Entra ID (Azure AD)
      • FireHydrant
      • GitHub
      • GitLab
      • Google
      • Grafana
      • incident.io
      • Instana
      • Jenkins
      • Jira
      • Kubernetes
      • LaunchDarkly
      • Lightstep
      • Mend
      • Microsoft Teams
      • New Relic
      • Okta
      • Opsgenie
      • PagerDuty
      • Prometheus
      • Rollbar
      • Rootly
      • Sentry
      • ServiceNow
      • Slack
      • Snyk
      • SonarQube
      • Splunk Observability Cloud (SignalFx)
      • Splunk On-Call (VictorOps)
      • Sumo Logic
      • Veracode
      • Wiz
      • Workday
      • xMatters
  • Scorecards
    • Initiatives and Action items
      • Creating issues based on Initiatives
    • Scorecard rule exemptions
    • Scorecard rule filters
    • Scorecard examples
    • Scorecards as code
  • Reports
    • Executive report
    • All Scorecards report
    • Bird's eye report
    • Progress report
    • Report card
  • Eng Intelligence
    • Custom Metrics
    • Jira Metrics
    • Metrics Explorer (Beta)
  • Cortex Query Language (CQL)
    • Using CQL reports
    • Using JQ in Cortex
  • Workflows
    • Creating a Workflow
      • Workflows as code
    • Blocks
    • Running a Workflow
    • Registering a Scaffolder template
      • Scaffolder advanced usage
    • Using a Workflow to sync in ArgoCD
    • Kicking off a Jenkins pipeline in a Workflow
    • Calling internal service endpoints in a Workflow
  • Plugins
    • Creating a plugin
      • Creating a plugin proxy
    • Migrating Backstage plugins to Cortex
  • Engineering homepage
  • Workspace Settings
    • Using GitOps for Cortex
      • GitOps logs
    • Managing users
      • Roles and permissions
        • Custom roles
        • Team ownership entity editing
      • Configuring SSO
        • Microsoft Entra ID
        • Google
        • Other OIDC providers
        • Okta
          • Okta SCIM
      • Configuring identity mappings
      • Onboarding management
    • API keys, secrets, and tokens
      • Secrets
      • Personal tokens
    • Audit logs
    • Entity settings
      • Data verification
      • Auto archiving entities
    • IP allowlist
    • Notifications
      • Notification logs
    • Customizing your workspace
    • Using search in Cortex
  • Cortex API
    • REST API operations
      • API Keys
      • Audit Logs
      • Catalog Entities
      • Custom Data
        • Custom Data (Advanced)
      • Custom Events
      • Custom Metrics
      • Dependencies
      • Deploys
      • Discovery Audit
      • Docs
      • Eng Intel: User Labels
      • Entity Relationship Types (Beta)
      • Entity Relationships (Beta)
      • Entity Types
      • GitOps Logs
      • Groups
      • Initiatives
      • Integrations APIs
        • Azure Active Directory (Entra ID) API
        • Azure Resources API
        • AWS API
        • Azure DevOps API
        • CircleCI API
        • Coralogix API
        • Datadog API
        • GitHub API
        • GitLab API
        • incident.io API
        • LaunchDarkly API
        • New Relic API
        • PagerDuty API
        • Prometheus API
        • SonarQube API
      • IP Allowlist
      • Notification Logs
      • On call
      • Packages
      • Plugins
      • Queries
      • SCIM
      • Scorecards
      • Secrets
      • Team Hierarchies
      • Teams
      • Workflows
Powered by GitBook
On this page
  • CQL basics
  • CQL format and data sources
  • Combining CQL expressions
  • CQL tools
  • The Query builder tool
  • CQL explorer
  • Running a CQL query
  • Step 1: Build a query
  • Step 2: Run the query
  • View and share results
  • Running rules on multiple queries
  • CQL errors
  • Save a query
  • View active, recent, and saved queries
  • Saved queries
  • Recent queries

Was this helpful?

Export as PDF

Cortex Query Language (CQL)

Last updated 19 days ago

Was this helpful?

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 evaluate health and readiness to deciding which entities a should appear on.

With CQL, you can:

  • Query your data immediately (including from third-party integrations or ), 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

  • Create reusable 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

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

    • Example query: jira.numOfIssues()

  • Custom data: Data attached to the entity, or defined in the

    • 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"

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.

To see the Query builder, click Tools > Query builder in the main nav.

Using custom data in CQL queries

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

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.

  • As a standalone page: Click ? at the bottom of your Cortex workspace, then in the Cortex Resource Center side panel, click CQL explorer.

Running a CQL query

The Query builder allows you to define your query without needing to learn CQL upfront.

You will need the Run query builder permission. If you are running queries on third-party integrations, you will also need the Run query builder with third-party integrations permission.

Step 1: Build a query

  1. On the right side of the Query builder page, click the CQL builder tab.

  2. In the CQL builder, choose and integration and a rule to evaluate.

    • The rules available in the dropdown menu will depend on the integration you've selected.

    • Depending on the rule you choose, you may need to configure additional fields.

  3. Click Use query. The query will automatically populate into the CQL search field on the left side of the page:

Step 2: Run the query

  1. Below the CQL search box, click Run query.

  2. At the bottom of the side panel, click Run query.

  3. In the confirmation modal that appears, click Yes, run query.

View and share results

After running the query, the page displays a list of all entities matching the criteria. In the upper right corner of the list, you can sort and filter the list. As you apply filters to your list, Cortex will also update the number of matching entities, so you can easily see at a glance how many entities match your requirements.

You can share the results in two ways:

  • Send a link: Click Share in the upper right corner of the results list to copy the URL to your clipboard. You can share the link with anyone who has access in your Cortex workspace.

  • Export as CSV: In the upper right corner of the page, click Export CSV to download a CSV file of the data.

Running rules on multiple queries

If you want to run a query on more than one rule, you can join multiple queries together with AND and OR.

For example:

git.commits().length == 2 AND azureDevops.workItems().length > 4

CQL errors

The following errors may occur when running a CQL query:

  • 400: This typically indicates a misconfiguration with an integration. For example, you may be missing an entity registration required for an integration.

  • 429: This occurs when hitting the rate limit for an integration. Cortex will retry 5 times before responding with this error. To prevent rate limit issues, we have built a self-throttling system that proactively throttles before hitting a rate limit from the vendor.

  • 500: This indicates that the integration itself returned an error.

Save a query

While viewing the results of a query you ran, you can save the query to use again in the future:

  1. In the upper right corner of the results page, click Save query.

  2. In the side panel, configure the query details:

    • Enter a name and description for your query.

    • To allow other users in your Cortex workspace to see the query, enable the toggle next to Share across organization.

  3. Click Save.

View active, recent, and saved queries

Below the CQL search text box, you can see active queries. This section displays the ongoing process of your submitted query. When the query is complete, it will appear under Recent.

Saved queries

Click the Saved tab to view a list of your saved queries, and queries that others have saved and shared across your organization.

Recent queries

Click the Recent tab. This list shows all queries that have been run in the last 30 days.

See additional CQL instructions and examples in the .

The functionality of the Query builder depends on your . 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.

You can add to any entity, and you can access custom data from any . 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.

contains instructions and examples for specific data types, entity metadata, custom data, and more.

In the side panel that opens, choose whether to run the query on all entities or select specific entities.

403: This occurs if there are missing or improper .

Along the top of the query builder, you can click into tabs to view Saved and Recent queries. Click into any of the queries in these lists to view the results of the query.

Query results are not automatically updated, but you can refresh a query manually: While viewing the results page, click the 3 dots icon, then click Refresh.

When configuring a , it is possible to enable automatic refresh.

permissions
custom data
entity's details page
CQL explorer
permissions
CQL explorer
Scorecards
plugin
custom data
CQL reports
third-party sources
sent via API
CQL report
entity YAML
Click Tools > Query builder from the main nav.
CQL explorer is on the right side of the Query builder.
Click ?, then click CQL explorer.
CQL builder is on the right side of the Query builder page.
Click "Use query" in CQL builder, then the query populates the CQL search field.
Click "Save query" in the upper right.