Create dashboards with filters

This page explains how to create dashboards with filters that let you choose the data you want to display.

Filters let you choose the data you want to display in your dashboard. This page explains how to create and configure dashboards with filters.

Try out all the examples explained on this page in the HTTP logs dashboard of the Axiom Playground.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Send data to the dataset.
• Create an empty dashboard.

Filter types

You can use two types of filter in your dashboards:

• Search filters let you enter any text, filter for data that matches the text input, and then narrow down the results displayed by the charts in the dashboard. For example, you enter Mac OS, filter for results that contain this string in the user agent field, and then only display the corresponding results in the charts.
• Select filters let you choose one option from a list of options, filter for data that matches the chosen option, and then narrow down the results displayed by the charts in the dashboard. For example, you choose France from the list of countries, filter for results that match the chosen geographical origin, and then only display the corresponding results in the charts.

Use dashboards with filters

To see different filters in action, check out the HTTP logs dashboard of the Axiom Playground. The search filter on the top right lets you search for a specific phrase in the user agent field to only display HTTP requests from a specific user agent. The select filters on the top left let you choose country and city to only display HTTP requests from a specific geographical origin.

In each chart on your dashboard, you can use all, some, or none of the filters to narrow down the data displayed in the chart. For example, in the HTTP logs dashboard of the Axiom Playground, the charts Popular data centers and Popular countries aren’t affected by your choices in the select filters. You choose to use a filter in a chart by referencing the unique ID of the filter in the chart query as explained later on this page.

Filters can be interdependent. For example, in the HTTP logs dashboard of the Axiom Playground, the values you can choose in the city filter depend on your choice in the country filter. You make a filter dependent on another by referencing the unique ID of the filter as explained later on this page.

For each filter, you define a unique ID when you create the filter. When you create multiple filters, all of them must have a different ID. You can later use this ID to reference the filter in dashboard charts and other filters.

Filters are visually displayed in your dashboard in a filter bar that you can create and move as any other chart. You can add different types of filter to a single filter bar. A filter bar can contain maximum one search filter and any number of select filters.

Create search filters

1. In the empty dashboard, click Add chart.
2. Click Advanced query language.
3. In Chart type, select Filter bar.
4. In Filter type, select Search.
5. In Filter name, enter the placeholder text you want to display in your search filter.
6. Specify a unique filter ID that you later use to reference the filter. For example, user_agent_filter.

Try out this filter in the HTTP logs dashboard of the Axiom Playground.

Create select filters

1. In the empty dashboard, click Add chart.

2. Click Advanced query language.

3. In Chart type, select Filter bar.

4. In Filter type, select Select.

5. In Filter name, enter the text you want to display above the select filter.

6. Specify a unique filter ID that you later use to reference the filter. For example, country_filter.

7. In the Value section, define the list of options to choose from in the select filter as key-value pairs. Axiom displays the key in the list of options in the filter dropdown, and uses the value to filter your data. For example, the key France is displayed in the list of options, and the value FR is used to filter data in your charts. Define the key-value pairs in one of the following ways:

   • Choose List to manually define a static list of options. Enter the options as a list of key-value pairs.
   • Choose Query to define a dynamic list of options. In this case, Axiom determines the list of options displayed in the filter dynamically based on an APL query. The results of the APL query must contain two fields which Axiom interprets as key-value pairs. Use the project command to create key-value fields from any output.
   The value in the key-value pairs must be a string. To use number or Boolean fields, convert their values to strings using tostring().

The example APL query below uses the distinct values in the geo.country field to populate the list of options. It projects these values as both the key and the value and sorts them in alphabetical order.

['sample-http-logs'] 
| distinct ['geo.country']
| project key=['geo.country'] , value=['geo.country']
| sort by key asc

See this filter in action in the HTTP logs dashboard of the Axiom Playground.

Create dependent select filters

Sometimes it makes sense that filters depend on each other. For example, in one filter you select the country, and in the other filter the city. In this case, the list of options in the city filter depends on your choice in the country filter.

To create a filter that depends on another filter, follow these steps:

1. Create a filter. In this example, the ID of the independent filter is country_filter.
2. Create a dependent select filter. In this example, the ID of the dependent select filter is city_filter. The dependent filter must be a select filter.
3. In the dependent filter, use declare query_parameters at the beginning of your query to reference the independent filter’s ID. For example, declare query_parameters (country_filter:string = ""). This lets you use country_filter as a parameter in your query even though it doesn’t exist in your data. For more information, see Declare query parameters.
4. Use the country_filter parameter to filter results in the dependent filter’s query.

The example APL query below defines the dependent filter. It uses the value of the independent filter with the ID country_filter to determine the list of options in the dependent filter. Based on the selected country, the APL query uses the distinct values in the geo.city field to populate the list of options. It projects these values as both the key and the value and sorts them in alphabetical order.

declare query_parameters (country_filter:string = "");
['sample-http-logs'] 
| where isnotempty(['geo.country']) and isnotempty(['geo.city'])
| where ['geo.country'] == country_filter
| summarize count() by ['geo.city']
| project key = ['geo.city'], value = ['geo.city']
| sort by key asc

Check out this filter in the HTTP logs dashboard of the Axiom Playground.

Reference filters in chart queries

After creating a filter, specify how you want to use the value chosen in the filter. Include the filter in the APL query of each chart where you want to use the filter to narrow down results. To do so, use declare query_parameters at the beginning of the chart’s APL query to reference the filter’s ID. For example, declare query_parameters (country_filter:string = ""). This lets you use country_filter as a parameter in the chart’s query even though it doesn’t exist in your data. For more information, see Declare query parameters.

The APL query below defines a statistic chart where the data displayed depends on your choice in the filter with the ID country_filter. For example, if you choose France in the filter, the chart only displays the number of HTTP requests from this geographical origin.

declare query_parameters (country_filter:string = "");
['sample-http-logs']
| where isempty(country_filter) or ['geo.country'] == country_filter
| summarize count() by bin_auto(_time)

Combine filters

You can combine several filters of different types in a chart’s query. For example, the APL query below defines a statistic chart where the data displayed depends on three filters:

• A select filter that lists countries.
• A select filter that lists cities within the chosen country.
• A search filter that lets you search in the user_agent field.

declare query_parameters (country_filter:string = "",
                          city_filter:string = "",
                          user_agent_filter:string = "");
['sample-http-logs']
| where isempty(country_filter) or ['geo.country'] == country_filter
| where isempty(city_filter) or ['geo.city'] == city_filter
| where isempty(user_agent_filter) or user_agent contains user_agent_filter
| summarize count() by bin_auto(_time)

See this filter in action in the Total requests chart in the HTTP logs dashboard of the Axiom Playground.

Declare query parameters

Use declare query_parameters at the beginning of an APL query to reference a filter’s ID. For example, declare query_parameters (country_filter:string = ""). This lets you use country_filter as a parameter in the chart’s query even though it doesn’t exist in your data.

The declare query_parameters statement defines the data type of the parameter. In the case of filters, the data type is always string.

Choose default option in select filter

The default option of a select filter is the option chosen when the dashboard loads. In most cases, this means that no filter is applied. This option is added automatically as the first in the list of options when you create the filter with the key All and an empty value. To choose another default value, reorder the list of options.

Handle empty values

The examples on this page assume that you use the default setting where the All key means an empty value, and the empty value in a filter means that the data isn’t filtered in the chart. The example chart queries above handle this empty (null) value in the where clause. For example, where isempty(country_filter) or ['geo.country'] == country_filter means that if no option is chosen in the country filter, isempty(country_filter) is true and the data isn’t filtered. If any other option is chosen with a non-null value, the chart only displays data where the geo.country field’s value is the same as the value chosen in the filter.