Let’s say you have created a “Dropdown” control to filter your charts by project ID. However, the people viewing your dashboard probably don’t know the IDs of the projects that they’re interested in. They may, for example, want to filter by project names instead.

This type of situation is likely a use case for the key-value pair. Key-value pairs are sets of two linked pieces of data. The key is the unique identifier in the data set, and the value is the data itself. For use with a “Dropdown” control, the key is a unique ID, and the value is the easy way for a user to identify the key.

Some potential use cases for using a key-value pair include when ID number information is not useful to the dashboard user. Often times a dashboard may be accessed by users that have little experience and no reason to know the numerical structure of the ID numbers for your client base. This would be a great time to use a key-value pair to identify the client by their name, email, or some other more useful identifying piece of information.

Here’s how to create a key-value “Dropdown” control:

1. Edit your “Dropdown” control and add the column containing more useful information to your query. Don’t remove the column containing the unique identifiers.

2. If you’re using visual mode, use the Group aggregation for both columns in the query.

3. If necessary, reorder the columns so the column containing the unique identifiers is the leftmost column in the result table.

4. Select Run query.

5. Select Save to dashboard.

The first column’s values are used to filter charts, and the second column's values are what’s displayed.

For this example, we use our data source containing Jira data. We want to display project names as the values in the “Dropdown” control and filter our charts by their associated project ID. To create this control, we add the Project ID column and the Name column from the Jira project table to the visual mode query of our “Dropdown” control.

Settings for a “Dropdown” control using key-value pairs

• For the Dropdown’s data type, select the data type of your key column. In our example, we’d select Text since our project IDs are text (strings).

• When setting default values or subscription values for “Dropdown” controls using key-value pairs, use values from the key column (first column), not the value column (second column).