Cortex Query Language (CQL)
Last updated
Last updated
Cortex Query Language (CQL) is a proprietary domain-specific language (DSL) you can use to query details in-depth about your Cortex entities. With CQL, you can reach into third-party integrations or . CQL also supports basic arithmetic and utility functions to transform the data as you need.
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 is at the core of many Cortex features, from defining how evaluate health and readiness to deciding which entities a should appear on.
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
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"
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.
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.
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.
On the right side of the Query builder page, click the CQL builder tab.
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.
Click Use query. The query will automatically populate into the CQL search field on the left side of the page:
Below the CQL search box, click Run query.
At the bottom of the side panel, click Run query.
In the confirmation modal that appears, click Yes, run query.
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.
If you want to run a query on more than one rule, you can join multiple queries together with AND and OR.
For example:
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.
While viewing the results of a query you ran, you can save the query to use again in the future:
In the upper right corner of the results page, click Save query.
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.
Click Save.
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.
Click the Saved tab to view a list of your saved queries, and queries that others have saved and shared across your organization.
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.
