8. CQL and the Query builder
The CQL Builder exposes the power of Cortex Query Language (CQL), which was initially developed to present Scorecard information. The Query builder allows you to leverage all of CQL's power to investigate information about the catalog without building an entire Scorecard.
The functionality of the Query builder depends on 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.
You can access the Query builder under Tools in the main nav.
Using the CQL builder
The Query builder allows you to define your query with the same CQL builder available when defining Scorecard rules, so you can use the Query builder without needing to learn CQL upfront.
Selecting CQL builder within the CQL Search will open a modal window that guides you through building a query. First, Choose an integration you want to work with.
Next, choose a rule to evaluate. The rules available in the dropdown menu will depend on the integration you've selected.
The rule that you select will then determine the remaining fields for you to enter information.
Once you’ve built your query, select Save rule to generate a CQL translation.
If you want to run a query on more than one rule, type AND into the field and select CQL Builder again. Note that until you've added another rule, you'll get an error message under your query.
Repeat the process of building a rule through the CQL builder. When you click Save rule, your new rule will be appended to the existing query.
Even if you aren’t familiar with CQL, Cortex makes it easy to work with the Query builder. You can continue adding through the CQL Builder until you’re ready to run it.
Active, recent, and saved queries
Below the CQL Search, you can find Active Queries and Recent Queries.
Active Queries will display the ongoing progress of your submitted query. Once that query completes, it will move to Recent Queries. You can also view all queries conducted in the last 30 days by navigating to the Recent tab in the menu bar.
You can open any recent query to see which entities apply — these will appear under Matching entities. To save a query, click Save query in the top right corner.
From there, you’ll name the query and enter a description. You also have the option to Share across organization, and make the query visible to all users.
Only admins and managers have the ability to save and publish queries, so not all users will have access to this feature.
Just like with other features in Cortex, saved queries will display My Queries — those created by you — and Shared Queries — those that other Cortex users have opened.
Queries are not automatically updated, but you can refresh a query at any time by selecting Refresh query on a query's page.
Results will populate as a query runs, so you can watch the list of Matching entities grow. 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.
The Query builder gives you the precise information you need with unparalleled accuracy, and Cortex makes it incredibly easy to make sense of that information at a glance.
CQL and custom data
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.