Query Timeline Chart

The Query Timeline supports single and multiple queries, displaying the number of results as a trend line over the selected date range.

You can select to display results for a date relative to today or a fixed date range.

In addition to viewing results from the defined number of selected time periods, you can also select 'complete' periods and 'complete' periods 'to date'. Complete periods of time show data only for periods that are a whole unit. Complete periods to date, show data for whole units of time plus the time that elapsed in the current period.

For example, the 2 'complete weeks', displays data from the past two whole weeks. 2 'complete weeks to date' displays data for the past two whole weeks, plus the days that have elapsed in the current week so far.

To configure a Query Timeline chart:

1. In the Chart title text box, enter a title for the chart.

2. In the Description text box, you can add an optional description.

3. From the Widget dropdown, select Query Timeline Chart.

4. Select the chart mode:

   • Comparison - Compare up to six queries. Queries may be existing queries or new ones. Learn more about creating a query.
   • Intersection - Intersect a base query and one additional query that intersects with it. When selected, all queries must be from the same asset module, e.g. Users, Devices, Software or Vulnerabilities. Once the asset module is selected for the first query, the module selection list for subsequent queries is automatically matched to the first query.

5. Under Calculate by, select the method of calculation:

   • Count - Select to show the actual asset count. The y-axis shows asset count values. When you hover over the value points of the chart lines, the count is displayed in a tooltip.

     

   • Percent - Select to show the percent of the total asset count of all configured queries. The y-axis shows percentage values. When you hover over the value points of the chart lines, the count is displayed in a tooltip. The top line lists the asset count along with the percentage of the total in parentheses. The second line shows the total number of assets from which the percentage is taken.

     

6. Select an asset module and query for up to 6 queries that can be included in the comparison.

7. In Aggregate by, select an aggregation time period: Day, Week, Month Quarter, or Year. Query results for weekly, monthly, quarterly, and yearly time periods are aggregated based on the average values for the selected time period. Each data point for weekly aggregation is the average of all daily values since the last weekly period. And each data point for the monthly aggregation is the average of all daily values since the last monthly period. You can choose to exclude date ranges from the displayed range. The legend reflects the time period selected.

   Note

   On the daily aggregation chart, you can click through to the asset list. See Selecting a Table View for more on what data is displayed when you click a chart segment.

   
   

8. Specify the dynamic time period or a date range to be included in the timeline chart. The resulting date range is displayed on the chart that is created.

   To show one day of each period instead of the period average, enable Use one day of each period. See Using One Day of Each Period.

   As you configure the chart, a preview is created in the left pane.

   

9. (Optional) To exclude dates from the displayed range, click the Exclude Dates slider and select the date range you want to exclude. You can click to exclude multiple date ranges. The preview changes as you select the ranges.

10. In the Y-axis settings section, do the following:

    • To set a minimum value, toggle Axis minimum and enter a value in the text box.
    • To set a maximum value, toggle Axis maximum and enter a value in the text box.

Learn more about setting y-axis values.

11. (Optional) To show the trend of each line, enable Show trendline. See Showing a Trendline.

12. Click Save.

• When the chart is created, you can hover over data points to see information about them.
• Click on any data point to open the chart in the relevant assets page (depending on the module you chose). See Chart Click-Through to understand what data is shown in the table.

To export the query timeline to a matrix of date and values in a CSV file, select Export to CSV from the chart menu.

Using One Day of Each Period

Use Use one day of each period to show the value from one specific day of each period, instead of the period average.

Permissions: To add or edit a chart, you need the Dashboards > Charts > Add or Dashboards > Charts > Edit permission. Users who can only view the dashboard see the option read-only in View Configuration.

To use one day of each period:

1. On a dashboard, click Add Chart, or edit a Query Timeline chart.
2. Select the queries.
3. In Aggregate by, select Week, Month, or Quarter.
4. Enable Use one day of each period.
5. Enter a day number (starting at 1).
6. Click Save.

• By default, this option is disabled and each point shows the period average.
• Use one day of each period is not available when Aggregate by is set to Day.
• The valid day range is 1–7 for a week, 1–31 for a month, and 1–92 for a quarter. Enter whole numbers only.
• If that day has no data, the point uses the nearest day in that period that has data.
• A period with no data at all stays empty.
• The week start follows the Dashboard Timeline charts - Week start day setting, which defaults to Sunday.

Example: A chart shows "Devices missing an agent", aggregated by Month, with day 1. Each data point reflects the count from the first day of that month.

Showing a Trendline

Use Show trendline to add a straight line that shows whether each query line goes up or down, and by how much per day.

Permissions: To add or edit a chart, you need the Dashboards > Charts > Add or Dashboards > Charts > Edit permission. Users who can only view the dashboard see the trendlines, but they can't change the option.

To show a trendline:

1. On a dashboard, click Add Chart, or edit a Query Timeline chart.
2. Select the queries and the date range as usual.
3. Keep the grouping at Day.
4. In Presentation, make sure that Y-axis scale is Linear, if the option appears.
5. Enable Show trendline.
6. Click Save.

• By default, this option is disabled. Existing charts have no trendline.
• Each line gets its own trendline, a dashed straight line in the same color as the line.
• The trendline is the best-fit straight line over the points of the line in the chart date range. The calculation doesn't use points that the chart fills in for missing dates.
• A line needs 2 or more points on different dates to get a trendline.
• The legend and the tooltip show the trendline as "
• When Y-axis scale is Logarithmic, the option is disabled and its label is "Show trendline (not on a logarithmic axis)". No trendline appears.
• The trendline appears only when the grouping is Day. With Week, Month, or another grouping, no trendline appears.
• The trendline has no data points, and a click on it does nothing. A click on the line itself still opens the assets.
• The option changes only the display. The chart data doesn't change.

Example: A Query Timeline shows "Devices without EDR" for the last 30 days. Enable Show trendline. The legend shows "Devices without EDR trend (-3 per day)". This means that the count goes down by about 3 devices each day.

Setting Timeline Chart y-axis Min/Max Values