Skip to main content

9. Using CQL reports

CQL reports offer a new level of visibility into your entities, extending the power of CQL and the Query Builder into reporting. CQL reports allow you to query all of the raw data in Cortex and build custom reports on top of it. Whereas Query Builder and Scorceards require expressions to evaluate to a boolean, CQL report expressions allow you to view any expression result, allowing you to to query, for example, the exact number of incidents services had in the last week.

You can find CQL reports under Tools in the main nav.

cql and query builder 1

Select Create CQL report next to the search bar to build your own CQL report.

When creating a CQL report, you have the option to use a CQL report template or Start from scratch. If you opt to work from a template, you’ll be able to select from any of your organization’s available templates — along with templates built into Cortex — making it easier to ensure all best practices are being followed.

cql and query builder 3

Regardless of which option you choose, you’ll be prompted to enter a name and description for your report, so you can tell at a glance what each report is querying.

cql and query builder 4

Select entity types to include or exclude under the Apply to specific entities section. You can also use Advanced options to further refine your selection.

From there, you’ll define the CQL expressions that will serve as your report columns. Select Add column to define a new expression, or use the pencil icon to edit an existing column.

cql and query builder 5

Once each expression is saved, Cortex will run the query to generate results for that column. Queries run asynchronously, so the report will generate cell by cell to pull the specific values for each entity.

Note

The same permissions that apply to the query builder apply to CQL reports. Only managers and admins have the ability to run reports that include third-party integrations.

Output cell values can be any type — they can be strings, numbers, booleans, or whatever else you want. Note that if the return value is too large (like a 5 MB JSON file) the cell will error out, so we recommend defining raw values for outputs. The maximum data size that can be the value of a cell is 2048 bytes.

As the queries run, you can access results and watch progress as it completes. Just like with the query builder, Cortex won’t automatically refresh queries, but you can manually refresh at any time.

caution

The maximum data size for output cells in 2048 bytes.

During the creation flow, you also have the option to make your CQL report Public by switching the toggle below Save CQL report.

If you choose to keep the CQL report private, you’ll be the only user able to see the report. Just like with the query builder, public CQL reports will be available to everyone in your organization, so you can easily share your insights with others.

You can return at any point to reconfigure your CQL report, including changing its public/private status.