Setting Up Parameters in Amazon QuickSight - Amazon QuickSight

Setting Up Parameters in Amazon QuickSight

Creating or Editing Parameters in Amazon QuickSight

Use the following procedure to create or edit a basic parameter.

  1. Choose an analysis to work with, and decide which field you want to parameterize.

  2. Choose the Parameters pane from the left side of the screen.

  3. Add a new parameter by choosing the add icon (+) near the top of the pane.

    Edit an existing parameter by first choosing the v-shaped icon near the parameter name and then choosing Edit parameter.

  4. The following screen appears.

    A parameter consists of the following parts, which you enter on this screen:

    Name

    Enter an alphanumeric value for the parameter Name. This name is used as a reference in the consumers of the parameters (for example, calculated field, filter, custom URL action, and so on). For ease of use, you can choose a name that reflects the data type and purpose of the parameter.

    Data type

    Choose a value for Data type. This data type can't be altered after you create the parameter. If you want to use the parameter for a text box or drop-down list, choose String.

    Values

    Choose one of the following:

    • Single value – for parameters that can contain only one value.

    • Multiple values – for parameters that can contain one or more values. Multivalue parameters can't be datetime data types. They also don't support dynamic default values.

    To switch an existing parameter between single and multiple values, delete and recreate the parameter.

    Static default value

    Choose a static default value for the parameter. This static value is used during the first page load, if a dynamic default value or URL parameter isn't provided.

    Dynamic default value

    Choose Set a dynamic default to create a default that is user-specific. A dynamic default is a per-user default value for the first page load of the dashboard. Using a dynamic default, you can create a personalized view for each user.

    Calculated fields can't be used as dynamic defaults.

    Dynamic defaults don't prevent someone from selecting a different value. If you want to also secure the data, you can add row-level locking. For more information, see Using Row-Level Security (RLS) to Restrict Access to a Dataset.

    This option only appears if you choose a single value parameter. Multivalue parameters can't have dynamic defaults.

    Note

    If you choose a multivalue parameter, the screen changes to remove the default options. Instead, you see a box with the text Enter values you want to use for this control. You can enter multiple values in this box, each on a single line. These values are used as the default selected values in the parameter control. The values here are unioned with what you choose to enter for the parameter control. For more information on parameter controls, see Parameter Controls.

    Show as blank by default

    Select this option to show the default value for multivalue lists as blank. This option only applies to multivalue parameters.

  5. Choose Create or Update to complete creating or updating the parameter.

After you create a parameter, you can use it in a variety of ways. You can create a control (such as a button) so that you can choose a value for your parameter. For more information, see the following sections.

Using a Control with a Parameter in Amazon QuickSight

In dashboards, parameter controls appear at the top of the data sheet, which contains a set of visuals. Providing a control allows users to choose a value to use in a predefined filter or URL action. Dashboard users can use controls to apply filtering across all visuals data sets on a dashboard, without having to create the filters themselves.

Use the following procedure to create or edit a control for an existing parameter. You need to have an existing parameter to create or edit a control for it.

  1. Choose an existing parameter's context menu, the v icon near the parameter name, and choose Add control.

  2. Enter a name to give the new control a label. This label displays at the top of the workspace, and later at the top of the sheet that a dashboard displays on.

  3. Choose a style for the control from the following:

    • Text box

      A text box lets a user type in their own value. A text box works with numbers and text (strings).

    • Drop-down (single-select or multiselect)

      A single select drop-down lets a user select one value from a list. A multiselect drop-down lets a user select multiple values. Both type of lists work with numbers and text (strings).

      Multiselect lists used by a control can work with the following:

      • Custom actions

      • Dashboard or analysis URLs

      • Custom filters (these must either equal or not equal the values provided; no other comparisons are supported)

    • Slider

      A slider lets a user select a numeric value by sliding the control from one end of the bar to another. A slider works with numbers.

    • Date-picker

      A date-picker lets a user select a date from a calendar control.

    The Style option displays only the style types that are appropriate for the parameter's data type and single or multivalue setting. If the style that you want to use isn't in the list, you can recreate your parameter with the appropriate settings and try again.

  4. (Optional) If you choose a drop-down control, the screen expands so you can choose the values to display. You can either specify a list of values, or use a field in a data set. Choose one of the following:

    • Specific values

      To create a list of specific values, type in one per line, with no separating spaces or commas, as shown in the following screenshot.

      In the control, the values display in the order you typed them, not alphabetically.

    • Link to a data set field

      To link to a field, choose the data set that contains your field, then choose the field from the list. It can't be a calculated field.

      The values display alphabetically in the control, unless there are more than 10,000 distinct values. Then the control displays a search box instead. Each time you search for the value you want to use, it initiates a new query. If the results contain more than 10,000 values, you can scroll through the values with pagination.

      If you change the default values in the parameter, choose Reset on the control to show the new values.

    The values that you choose here are unioned with the static default values in the parameter settings.

  5. (Optional) Enable the option Hide [ALL] option from the control if the parameter has a default configured. Doing this shows only the data values and removes the option to select all items in the control. If you don't configure a static default on the parameter, this option doesn't work. You can add a default after adding a control by choosing the parameter, and selecting Edit parameter.

  6. (Optional) You can limit the values displayed in the controls, so they only show values that are valid for what is selected in other controls. This is called a cascading control.

    To create one, choose Show relevant values only. Choose one or more controls that can change what displays in this control.

  7. When you finish choosing options for your control, choose Add.

The finished control appears at the top of the workspace. The context menu, shaped like a v, offers four options:

  • Reset restores the user's selection to its default state.

  • Refresh list applies only to drop-downs that are linked to a field in a data set. Choosing Refresh list queries the data to check for changes. Data used in the control is cached.

  • Edit reopens the control creation screen so that you can change your settings.

  • Delete removes the control. You can recreate it by choosing the parameter context menu.

In the workspace, you can also resize and rearrange your controls. The dashboard users see them as you do, except without being able to edit or delete them.

Creating Parameter Defaults in Amazon QuickSight

Use this section to learn more about the types of parameter defaults that are available, and how to set up each of them.

Each field can have a parameter and a control associated with it. When someone views a dashboard or email report, any sheet control that has a static default value configured uses the static default. The default value can change how data is filtered, how custom actions behave, and what text displays in a dynamic sheet title. Email reports don't support dynamic defaults.

The simplest default is a static (unchanging) default, which shows the same value to everyone. As the designer of the dashboard, you choose the default value. It can't be changed by the person using the dashboard. However, that person can choose any value from the controls. Setting a default doesn't change this. To restrict the values that a person can select, consider using row-level security. For more information, see Using Row-Level Security (RLS) to Restrict Access to a Dataset.

To create or edit a static default value that applies to everyone's dashboard view

  1. Choose the context menu (v) by the parameter that you want to edit, or create a new parameter by following the steps in Creating or Editing Parameters in Amazon QuickSight.

  2. Enter a value for Static default value to set a static default.

To display a different default depending on who is viewing the dashboard, you create a dynamic default parameter (DDP). Using dynamic defaults involves some preparation to map people to their assigned defaults. First, you need to create a database query or a data file that contains information about the people, the fields, and the default values to display. You add this to a dataset, then add the dataset to your analysis. Following, you can find procedures that you can use to gather information, create the dataset, and add the dynamic default to the parameter.

Use the following guidelines when creating a dataset for dynamic default values:

  • We recommend that you use a single dataset to contain all dynamic default definitions for a logical grouping of users or groups. If you can, maintain them in a single table or file.

  • We also recommend that the fields in your dataset have names that closely match the field names in the analysis. Not all dataset fields need to be part of the analysis, for example if you're using the same dataset for the defaults in multiple dashboards. The fields can be in any order.

  • We don't recommend that you combine both user and group names in the same column or even in the same dataset. This kind of configuration is more work to maintain and troubleshoot.

  • If you use a comma-delimited file to create your dataset, make sure to remove any space between values in the file. The following example shows the correct comma-separated value (CSV) format. Enclose text (strings) that include nonalphanumeric characters—like spaces, apostrophes, and so on—in single or double quotation marks. You can enclose fields that are dates or times in quotation marks, but it isn't required. You can enclose numeric fields in quotation marks, for example if the numbers contain special characters, as shown following.

    "Value includes spaces","Field contains ' other characters",12345.6789,"20200808" ValueWithoutSpaces,"1000,67","Value 3",2020-AUG-08
  • After you create the dataset, make sure to double-check the data types that QuickSight selects for the fields.

Before you begin, you need a list of the user or group names for the people who are going to have dynamic defaults. To generate a list of users or groups, you can use the AWS CLI to get the information. To run CLI commands, make sure that you have the AWS CLI installed and configured. For more information, see Installing the AWS CLI in the AWS CLI User Guide.

This is just one example of how to get a list of user or group names. Use whatever method works best for you.

To identify people for a dynamic default parameter (DDP)

  • List either individual user names or group names:

    • To list individual user names, include a column that identifies the people for your DDP. This column should contain each person's system user name that they use to connect from your identity provider to QuickSight. This user name is often the same as a person's email alias before the @ sign, but not always.

      To get a list of users, use the ListUsers QuickSight API operation or AWS CLI command. The CLI command is shown in the following example. Specify the AWS Region for your identity provider, for example us-east-1.

      awsacct1="111111111111" namespace="default" region="us-east-1" aws quicksight list-users --aws-account-id $awsacct1 --namespace $namespace --region $region

      The following example alters the previous command by adding a query that limits the results to active users.

      awsacct1="111111111111" namespace="default" region="us-east-1" aws quicksight list-users --aws-account-id $awsacct1 --namespace $namespace --region $region --query 'UserList[?Active==`true`]'

      The result set looks similar to the following sample. This example is an excerpt from JSON output (--output json). People who have federated user names have principal IDs that start with the word federated.

      [ { "Arn": "arn:aws:quicksight:us-east-1:111111111111:user/default/anacasilva", "UserName": "anacarolinasilva", "Email": "anacasilva@example.com", "Role": "ADMIN", "Active": true, "PrincipalId": "federated/iam/AIDAJ64EIEIOPX5CEIEIO" }, { "Arn": "arn:aws:quicksight:us-east-1:111111111111:user/default/Reader/liujie-stargate", "UserName": "Reader/liujie-stargate", "Role": "READER", "Active": true, "PrincipalId": "federated/iam/AROAIJSEIEIOMXTZEIEIO:liujie-stargate" }, { "Arn": "arn:aws:quicksight:us-east-1:111111111111:user/default/embedding/cxoportal", "UserName": "embedding/cxoportal", "Email": "saanvisarkar@example.com", "Role": "AUTHOR", "Active": true, "PrincipalId": "federated/iam/AROAJTGEIEIOWB6BEIEIO:cxoportal" }, { "Arn": "arn:aws:quicksight:us-east-1:111111111111:user/default/zhangwei@example.com", "UserName": "zhangwei@example.com", "Email": "zhangwei@example.com", "Role": "AUTHOR", "Active": true, "PrincipalId": "user/d-96123-example-id-1123" } ]
    • To list group names, include a column that identifies the groups containing the user names for your DDP. This column should contain the system group names that are used to connect from your identity provider to QuickSight. To identify groups that you can add to the dataset, use one or more of the following QuickSight API operations or CLI commands:

      • ListGroups – Lists QuickSight groups by AWS account ID and namespace for the AWS Region that contains your identity provider.

      • ListGroupMemberships – Lists the users in the specified QuickSight group.

      • ListUserGroups – Lists the QuickSight groups that a QuickSight user is a member of.

      Or you can ask your network administrator to query your identity provider to get this information.

The next two procedures provide instructions on how to finish creating a dataset for dynamic default values. The first procedure is for creating a dataset for a single-value DDP. The second one is for creating a dataset for a multivalue DDP.

To create a dataset for a single-value DDP

  1. Create dataset columns with single-value parameters. The first column in the query or file should be for the people using the dashboard. This field can contain user names or group names. However, support for groups is only available in QuickSight Enterprise edition.

  2. For each field that displays a dynamic default for a single-value parameter, add a column to the dataset. The name of the column doesn't matter—you can use the same name as the field or parameter.

    Single-value parameters only work as specified if the combination of user entity and dynamic default is unique for that parameter's field. If there are multiple values a default field for a user entity, the single-value control for that field displays the static default instead. If no static default is defined, the control doesn't display a default value. Be careful if you use group names, because some user names can be members of multiple groups. If those groups have different default values, then this type of user name functions as a duplicate entry.

    The following example shows a table that appears to contain two single-value parameters. We make this assumption because no user name is paired with multiple default values. To make this table easier to understand, we add the word 'default' in front of the field names from the analysis. Thus, you can read the table by making the following statement, changing the values for each row: When viewed by anacarolinasilva, the controls display a default region NorthEast and a default segment SMB.

    viewed-by default-region default-segment
    anacarolinasilva NorthEast SMB
    liujie SouthEast SMB
    saanvisarkar NorthCentral SMB
    zhangwei SouthCentral SMB
  3. Import this data into QuickSight, and save it as a new dataset.

  4. In your analysis, add the dataset that you created. The analysis needs to use at least one other dataset that matches the columns you defined for the defaults. For more information, see Adding a Data Set to an Analysis.

To create a dataset for a multivalue DDP

  1. Create dataset columns with multivalue parameters. The first column in the query or file should be for the people using the dashboard. This field can contain user names or group names. However, support for groups is only available in QuickSight Enterprise edition.

  2. For each field that displays a dynamic default for a multivalue parameter, add a column to the dataset. The name of the column doesn't matter—you can use the same name as the field or parameter.

    Unlike single-value parameters, multivalue parameters allow multiple values in the field that's associated with the parameter.

    The following example shows a table that appears to contain a single-value parameter and a multivalue parameter. We can make this assumption because each user name has a unique value in one column, and some user names have multiple values in the other column. To make this table easier to understand, we add the word 'default' in front of the field names from the analysis. Thus, you can read the table by making the following statement, changing the values for each row: When viewed-by is liujie, the controls display a default-region value of SouthEast, and a default-city value of Atlanta. And if we read ahead one row, we see that liujie also has Raleigh in default-city.

    viewed-by default-region default-city
    anacarolinasilva NorthEast New York
    liujie SouthEast Atlanta
    liujie SouthEast Raleigh
    saanvisarkar NorthCentral Chicago
    zhangwei SouthCentral Dallas
    zhangwei SouthCentral Kansas City

    In this example, the parameter that we apply default-region to works correctly whether it's a single-value or multivalue parameter. If it's a single-value parameter, two entries work for one user because both entries are the same value, SouthEast. If it's a multivalue parameter, it still works, except that only one value is selected by default. However, if we change the parameter that's using default-city as its default from a multivalue to a single-value parameter, we don't see these defaults selected. Instead, the parameter uses the static default, if there is one defined. For example, if the static default is set to Atlanta, liujie has Atlanta selected in that control, but not Raleigh.

    In some cases, your static default value might also be used as a dynamic default. If so, make sure to test the control for a user name that doesn't use a default value that can be both.

    If a user name belongs to multiple groups, the named user sees a set of default values that is a union of the two groups' default values.

  3. Import this data into QuickSight, and save it as a new dataset.

  4. In your analysis, add the dataset that you created. The analysis needs to use at least one other dataset that matches the columns you defined for the defaults. For more information, see Adding a Data Set to an Analysis.

Use the following procedure to add a dynamic default parameter to your analysis. Before you begin, make sure that you have a dataset that contains the dynamic defaults for each user name or group name. Also make sure that your analysis is using this dataset. For help with these requirements, see the procedures preceding.

To add a DDP to your analysis

  1. In the QuickSight console, open the Parameters menu at left and choose an existing parameter. Choose Edit parameter from the parameter's menu. To add a new parameter, choose the plus (+) sign near Parameters.

  2. Choose Set a dynamic default.

  3. Configure the following options with your settings:

    • Dataset with default values and user information – Choose the dataset that you created and added to your analysis.

    • User name column – To create defaults that are based on user names, choose the column in the dataset that contains the user names.

    • Group name column – To create defaults that are based on group names, choose the column in the dataset that contains the group names.

    • Column for default value – Choose the column that contains default values for this parameter.

  4. Choose Apply to save your setting changes, and then choose Update to save the parameter changes. To exit without saving changes, choose Cancel instead.

  5. Add a filter for each field that contains dynamic defaults to make the defaults work. To learn more about using filters with parameters, see Using Filters with Parameters in Amazon QuickSight

    Amazon QuickSight uses the static default value for anyone whose user name doesn't exist in the dataset, doesn't have a default assigned, or doesn't have a unique default. Each person can have only one set of defaults. If you don't want to use dynamic defaults, you can set a static default instead.