# 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](https://docs.cortex.io/standardize/scorecards) evaluate health and readiness to deciding which entities a [plugin](https://docs.cortex.io/streamline/plugins) should appear on. With CQL, you can: * Query your data immediately (including from third-party integrations or [custom data](https://docs.cortex.io/ingesting-data-into-cortex/entities/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 * You can [utilize JQ in CQL](https://docs.cortex.io/standardize/cql/using-jq), allowing you to do arbitrary JSON manipulations (e.g., fetch nested fields, group by, sum over, etc.). Cortex can transition seamlessly between CQL and JQ data types. * Use basic arithmetic and utility functions to get the data you need * Customize [Scorecard](https://docs.cortex.io/standardize/scorecards) 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](https://docs.cortex.io/scorecards/scorecard-examples#using-cql-captures-to-display-the-cause-of-rule-failures). * Create reusable [CQL reports](https://docs.cortex.io/standardize/cql/cql-reports) to view any query result, such as the number of incidents your services had in the last week {% hint style="success" %} 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. {% endhint %} ## CQL basics See additional CQL instructions and examples in the [CQL explorer](https://app.getcortexapp.com/admin/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](https://docs.cortex.io/ingesting-data-into-cortex/integrations) * Example query: `jira.numOfIssues()` * **Custom data**: Data attached to the entity, [sent via API](https://app.gitbook.com/s/nPgS8L9MAPtoOtdWdeDp/readme/custom-data) or defined in the [entity YAML](https://docs.cortex.io/ingesting-data-into-cortex/entities/custom-data#editing-the-entity-descriptor) * Example query: `custom("cloud-cost") .cost.compute.actual` CQL expressions return different data types, and each type supports specific operations within queries. See the available data types and their supported operations in the [CQL explorer](https://app.getcortexapp.com/admin/cql-explorer?path=CQL+explorer,Data+types). ### 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. {% hint style="info" %} Learn more about captures * See additional instructions on using captures in [Cortex's CQL explorer](https://app.getcortexapp.com/admin/cql-explorer?path=CQL%20explorer\&path=Captures). * Read about a capture use case in [Scorecard examples: Using CQL captures to display the cause of rule failures](https://docs.cortex.io/scorecards/scorecard-examples#using-cql-captures-to-display-the-cause-of-rule-failures). {% endhint %} ### CQL testing Anywhere in Cortex where you use CQL, testing functionality allows you to quickly review and iterate on your queries. Below the CQL editor, select up to 10 entities to test against then click **Test**. Test results appear per entity below the editor.
Enter a CQL expression and click Test. Results will appear below the text editor.
You can test both boolean and non-boolean expressions anywhere in Cortex, but you can only save non-boolean expressions in [CQL Reports](#cql-reports). ## 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](https://docs.cortex.io/configure/settings/managing-users/permissioning). 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.
{% hint style="success" %} **Using custom data in CQL queries** You can add [custom data](https://docs.cortex.io/ingesting-data-into-cortex/entities/custom-data) to any entity, and you can access custom data from any [entity's details page](https://docs.cortex.io/ingesting-data-into-cortex/entities/details). 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. {% endhint %} ### CQL explorer [CQL explorer](https://app.getcortexapp.com/admin/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.\\
Click the purple flag icon on the right side of your workspace.
2. In the Help & Docs side panel, click **CQL explorer**. \\
Click the CQL explorer link in the "Help and docs" sidebar.
### 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](https://docs.cortex.io/standardize/cql/cql-reports). ## Running and saving CQL queries To learn about running queries and saving queries, see [Running and saving CQL queries](https://docs.cortex.io/standardize/cql/run).