Create custom XQL widgets - You can create custom XQL widgets based on a Cortex Query Language (XQL) query, and add parameters that you can configure as fixed filters or dashboard drilldowns. - Administrator Guide - Cortex XDR - Cortex

Create custom XQL widgets - You can create custom XQL widgets based on a Cortex Query Language (XQL) query, and add parameters that you can configure as fixed filters or dashboard drilldowns. - Administrator Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR 5.x Documentation

Product

Cortex XDR

License

XDR + Cloud

Creation date

2025-07-13

Last date published

2026-06-04

Notice

Requires a Data Collection add-on.

With custom Cortex Query Language (XQL) widgets you can personalize the information that you display on your custom dashboards and reports. You can build widgets that query specific information that is unique to your workflow, and define the graphical format you require, such as table, line graph, or pie chart.

All of your predefined and custom XQL widgets are available in the Widget Library. From the Widget Library, you can browse all widgets by category, create new XQL widgets, and edit and delete existing XQL widgets.

Role permissions: Your visibility and access to these widgets are set by your administrator through your user role. For more information, see Manage access to custom dashboards.
Visibility settings: By default, custom XQL widgets are Restricted. They are visible to you in the Widget Library and on any dashboards you have shared. If you want other users to be able to find and reuse your widget from the Widget Library, you must set it to Public.
Inherited access and reuse:
- Dashboards: If you add a Restricted XQL widget to a dashboard and share that dashboard, authorized viewers and editors of that dashboard can see the widget data even if they cannot see the widget in their own Widget Library.

Select Dashboards & Reports → Widget Library, click Create custom XQL widget, and select XQL.
Enter a widget name and an optional description.
Set the visibility for the widget.
Use the Public widget toggle to determine how the widget appears in the Widget Library. Leave it unselected (default) to keep the widget Restricted (visible only to you) or select it to make the widget Public (visible to all users with Widget Library access).
Define an XQL query that searches for the data you require.
Select XQL Helper to view commonly used commands with example syntax. For more information, see How to build XQL queries.
Tip
You can create a generic dashboard for multiple views of the same dataset by using an asterisk (*) when defining the dataset in the XQL widget as dataset = <dataset_name>*. The placement of the asterisk in the dataset name ensures that any view containing this prefix text is displayed in the results.
Example 94.
The dataset in a query is defined as:
```
dataset = amazon_aws_raw*
```
If there are multiple datasets that begin with amazon_aws_raw in their name, such as amazon_aws_raw_eu_view and amazon_aws_raw_us1_view, these views will be included.
Select Preview to review the search results.
Note
Cortex Query Language (XQL) queries generated from the Widget Library do not appear in the Query Center. The results are used only for creating the custom widget.
(Optional) Add parameters to the query to enable dashboard filters or drilldowns.
You can use parameters to filter widget data on a dashboard or report, and create drilldowns on dashboards. Base your filters on fields and values in the query results.
1. In the search results, identify a field by which you want to filter.
2. Using the filter stage, define parameters prefixed with $.
3. To specify parameters with a single predefined value, use the = operator. To specify parameters with multiple values (predefined or dynamic), use the IN operator.
  Example of a single value parameter
  Example 95. Single value parameters
  The following query defines the $domain parameter for filtering dashboard data by domain, based on the domain field in the agent_auditing dataset.
  Single value parameters are based on static predefined values. In this example, the dashboard user will be able to select a domain from a list of predefined domains.
  dataset = agent_auditing | filter domain = $domain
  Example of a multiple value parameter
  Example 96. Multiple value parameters
  The following query defines the $endpointname parameter for filtering dashboard data by one or more endpoint names, based on the endpoint_name field in the agent_auditing dataset.
  You can configure this parameter with static predefined values, or dynamic values that are pulled from an XQL query.
  dataset = agent_auditing | filter endpoint_name IN ($endpointname)
4. (Optional) Under Assign Parameters (default values), define default values for the parameters. When you add the widget to a dashboard or report, the data will be automatically populated. Alternatively, you can configure all input values when you set up a dashboard or report.
(Optional) Change the default time period against which to run your query from the time picker at the top right of the window. You can select the required Time frame from any of the following options available:
- Preset time ranges easily available to select from, such as 24 hours and 30 days.
- Recently used selections from your previous queries.
- Relative time: Define the time frame as the last <number> minutes, days, or hours by setting the number.
- Calendar: Create a customized time period by selecting the date range from the calendar and the specific Start Time and End Time.
Note
- Whenever the time period is changed in the query window, the config timeframe is automatically set to the time period defined, but this won't be visible as part of the query. Only if you manually type in the config timeframe will this be seen in the query.
- These time picker options are available in XQL queries when using the Query Builder, XQL Widgets, and when defining XQL Widgets in Reports and Dashboards.
In the Query Results section, to graph the results either:
Use Chart Editor
Under Query Results → Chart Editor (), manually build and view the graph using the selected graph parameters:
Main
Graph Type: Type of graphs and output options available: Area, Bubble, Column, Funnel, Gauge, Line, Map, Pie, Scatter, Single Value, or Word Cloud.
Note
To display the result of as a time duration, choose the graph type Single Value and enable Show as Time. You can then select the Time Unit (millisecond, second, minute, or hour) and the Display format.
Subtype and Layout: Depending on the selected type of graph, choose from the available display options.
Header: Title your graph.
Show Callouts: Display numeric values on graph.
Data
X-axis: Select a field with a string value.
Y-axis: Select a field with a numeric value.
(Optional) Series: For an area, bubble, column, line, map, or scatter chart, you can specify a field (column) to group chart results based on y-axis values. This option is only displayed when one of the supported graph types are selected, and a single y-axis value is selected.
Depending on the selected type of graph, customize the Color, Font, and Legend.
Use XQL query
Enter the visualization parameters in the XQL query section.
You can express any chart preferences in XQL. This is helpful when you want to save your chart preferences in a query and generate a chart every time that you run it. To define the parameters, either:
Define the following query:
Example 97.
view graph type = column subtype = grouped header = “Test 1” xaxis = _time yaxis = _product,action_total_upload series = _vendor

Select ADD TO QUERY to insert your chart preferences into the query itself.
Save the widget.
The custom widget appears in the list of existing widgets.

Notice

Tip

Note

Note

Note