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 custom data. CQL also supports basic arithmetic and utility functions to transform the data as you need.
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.
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, navigate to Tools > Query builder in the main nav.
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.
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:
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.
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.
Click the Saved tab to view a list of your saved queries, and queries that others have saved and shared across your organization.
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.
Click the Recent tab. This list shows all queries that have been run in the last 30 days.
The Query builder is even more powerful when you write CQL expressions directly, especially because it allows you to work with custom data in Cortex.
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.
In the side panel that opens, choose whether to run the query on all entities or select specific entities.
