Work with QuickSight Q topics using the Amazon QuickSight CLI - Amazon QuickSight
Work with QuickSight Q topics using the QuickSight CLIConfigure Q topic refresh schedules with the QuickSight CLICopy and migrate QuickSight Q topics within and between AWS accounts

Important: We've redesigned the Amazon QuickSight analysis workspace. You might encounter screenshots or procedural text that doesn't reflect the new look in the QuickSight console. We're in the process of updating screenshots and procedural text.

To find a feature or item, use the Quick search bar.

For more information on QuickSight's new look, see Introducing new analysis experience on Amazon QuickSight.

Work with QuickSight Q topics using the Amazon QuickSight CLI

 Applies to: Enterprise Edition 
   Intended audience: Amazon QuickSight developers 

Use this section to learn how to work with QuickSight Q topics using the Amazon QuickSight command line interface (CLI).

Prerequisites

Before you begin, make sure that you have an AWS Identity and Access Management (IAM) role that grants the CLI user access to call the QuickSight API operations. The following table shows which permissions must be added to the IAM policy to use specific API operations. To use all of the Q topic API operations, add all of the permissions listed in the table.

API operation IAM policy

CreateTopic

quicksight:CreateTopic

quicksight:PassDataSet

ListTopics

quicksight:ListTopics

DescribeTopic

quicksight:DescribeTopic

DescribeTopicPermissions

quicksight:DescribeTopicPermissions

DescribeTopicRefresh

quicksight:DescribeTopicRefresh

DeleteTopic

quicksight:DeleteTopic

UpdateTopic

quicksight:UpdateTopic

quicksight:PassDataSet

UpdateTopicPermissions

quicksight:UpdateTopicPermissions

CreateTopicRefreshSchedule

quicksight:CreateTopicRefreshSchedule

ListTopicRefreshSchedules

quicksight:ListTopicRefreshSchedules

DescribeTopicRefreshSchedule

quicksight:DescribeTopicRefreshSchedule

UpdateTopicRefreshSchedule

quicksight:UpdateTopicRefreshSchedule

DeleteTopicRefreshSchedule

quicksight:DeleteTopicRefreshSchedule

The following example shows an IAM policy that allows a user to use the ListTopics API operation.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "quicksight:ListTopics"
            ],
            "Resource": "*"
        }
    ]
}

Work with QuickSight Q topics using the QuickSight CLI

The following example creates a new Q topic.

aws quicksight create-topic
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--topic TOPIC

You can also create a new Q topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.

aws quicksight create-topic
--cli-input-json file://createtopic.json

When you create a new Q topic, the dataset refresh configuration is not copied to the topic. To set a topic refresh schedule for your new topic, you can make a create-topic-refresh-schedule API call. For more information about configuring topic refresh schedules with the CLI, see Configure Q topic refresh schedules with the QuickSight CLI.

After you create your first Q topic, you can update, delete, list, or request a summary of a Q topic.

The following example updates a Q topic.

aws quicksight update-topic
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--topic TOPIC

You can also update a Q topic by using a CLI skeleton file with the following command. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.

aws quicksight update-topic
--cli-input-json file://updatetopic.json

The following example provides a list of all Q topics in a QuickSight account.

aws quicksight list-topics 
--aws-account-id AWSACCOUNTID

The following example deletes a Q topic.

aws quicksight delete-topic 
--aws-account-id AWSACCOUNTID 
--topic-id TOPICID

The following example provides information about how a Q topic was configured.

aws quicksight describe-topic 
--aws-account-id AWSACCOUNTID 
--topic-id TOPICID

The following command updates the permissions of a Q topic.

aws quicksight update-topic-permissions
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--grant-permissions Principal=arn:aws:quicksight:us-east-1:AWSACCOUNTID:user/default/USERNAME,Actions=quicksight:DescribeTopic
--revoke-permissions Principal=arn:aws:quicksight:us-east-1:AWSACCOUNTID:user/default/USERNAME,Actions=quicksight:DescribeTopic

Use the grant-permissions parameter to grant read and author permissions to QuickSight account users. To grant read permissions to an account user, enter the following value: "quicksight:DescribeTopic". To grant permissions to an account user, enter the following values:

  • "quicksight:DescribeTopic"

  • "quicksight:DescribeTopicRefresh"

  • "quicksight:ListTopicRefreshSchedules"

  • "quicksight:DescribeTopicRefreshSchedule"

  • "quicksight:DeleteTopic"

  • "quicksight:UpdateTopic"

  • "quicksight:CreateTopicRefreshSchedule"

  • "quicksight:DeleteTopicRefreshSchedule"

  • "quicksight:UpdateTopicRefreshSchedule"

  • "quicksight:DescribeTopicPermissions"

  • "quicksight:UpdateTopicPermissions"

The RevokePermissions parameter revokes all permissions granted to an account user.

The following command describes all permissions from a Q topic.

aws quicksight describe-topic-permissions 
--aws-account-id AWSACCOUNTID
--topic-id TOPICID

Configure Q topic refresh schedules with the QuickSight CLI

The following command creates a refresh schedule of a Q topic.

aws quicksight create-topic-refresh-schedule
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--dataset-arn DATASETARN
--refresh-schedule REFRESHSCHEDULE

After you create a refresh schedule for a Q topic, you can update, delete, list, or request a summary of the topic's refresh schedule.

The following command updates the refresh schedule of a Q topic.

aws quicksight update-topic-refresh-schedule 
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--dataset-id DATASETID
--refresh-schedule REFRESHSCHEDULE

The following example provides a list of all refresh schedules configured to a Q topic.

aws quicksight list-topic-refresh-schedules
--aws-account-id AWSACCOUNTID
--topic-id TOPICID

The following example deletes a topic refresh schedule.

aws quicksight delete-topic-refresh-schedule 
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--dataset-id DATASETID

The following example provides information about how a topic refresh schedule was configured.

aws quicksight describe-topic-refresh-schedule  
--aws-account-id AWSACCOUNTID
--topic-id TOPICID
--dataset-id DATASETID

Copy and migrate QuickSight Q topics within and between AWS accounts

You can migrate your QuickSight Q topics from one account to another with the QuickSight command line interface (CLI). Instead of manually replicating the same topic across multiple dashboards, namespaces, or accounts, you can use the QuickSight CLI to reuse the same topic repeatedly. This capability saves QuickSight authors time and creates a standardized topic experience for dashboard readers across multiple dashboards.

To migrate Q topics with the QuickSight CLI, use the following procedure

To migrate a Q topic to another account

  1. First, identify the topic that you want to migrate. You can view a list of every Q topic in your QuickSight account with a list-topics API command.

    aws quicksight list-topics --aws-account-id AWSACCOUNTID

  2. After you have a list of Q topics, locate the topic that you want to migrate and make a describe-topic call to receive a JSON structure of the topic's configuration.

    aws quicksight describe-topic 
    --aws-account-id AWSACCOUNTID
    --topic-id TOPICID

    Following is an example of a describe-topic API response.

    {
    "Status": 200,
    "TopicId": "TopicExample", 
    "Arn": "string",
    "Topic": [
        {
            "Name": "{}",
            "DataSets": [
            {
            "DataSetArn": "{}",
            "DataSetName": "{}",
            "DataSetDescription": "{}",
            "DataAggregation": "{}",
            "Filters": [],
            "Columns": [],
            "CalculatedFields": [],
            "NamedEntities": []
            }
            ]
        }
    ],
    "RequestId": "requestId"
    }

  3. Use the JSON response to create a skeleton file that you can input into a new create-topic call in your other QuickSight account. Before you make an API call with your skeleton file, make sure to change the AWS account ID and dataset ID in the skeleton file to match the AWS account ID and dataset ID that you are adding the new Q topic to. For more information about CLI skeleton files, see Using CLI skeleton files in the Amazon QuickSight Developer Guide.

    aws quicksight create-topic --aws-account-id AWSACCOUNTID \
--cli-input-json file://./create-topic-cli-input.json

After you make a create-topic call to the QuickSight API, the new topic appears in your account. To confirm that the new topic exists, make a list-topics call to the QuickSight API. If the source topic that was duplicated contains verified answers, the answers are not migrated to the new topic. To see a list of all verified answers that are configured to the original topic, use a describe-topic API call.