Q in QuickSight トピックの Synonym を一括で設定する

トピックの DATA FIELDS が大量にある場合は API を使って一括登録する方法が考えられます。今回は JSON で設定値をあらかじめ入れておいて一括更新しましたが、Excel や CSV ファイルで一括更新したい場合は S3 に元になるファイルを格納し Lambda 等で設定値を読み込んで更新するような開発が必要そうです。
#Amazon Q in QuickSight
#Amazon QuickSight
#AWS CLI
#AWS
emi
2025.02.15
コーヒーが好きな emi です。
以下のブログで Q in QuickSight トピックの Include を一括で設定してみました。
https://dev.classmethod.jp/articles/q-in-q-batch-configuration-include/
本記事では Synonym（シノニム）を一括で設定してみます。
 （おさらい）Synonyms とはトピックは一言で説明しにくいのですが、データセットに含まれる情報がどういうものでどんな意味を持つかを登録しておく場所、とでも言いましょうか。データセットのインデックス（索引）のようなものです。

トピックを作成すると、生成 AI の機能 Q で元のデータに対して自然言語で問い合わせができます。ドキュメントには Generative Q&A と書かれています。
Q in QuickSight でデータセットをもとにトピックを作成すると、データセットのカラムが取り込まれます。
トピックにおける Synonyms（シノニム）とは、類義語のことです。例えば「Northwest」というフィールドがあるとして、自然言語で問い合わせる際に毎回「Northwest」と入力するのが面倒な場合に「NW」というシノニムを登録しておくと、問い合わせの際に Q が解釈してくれます。社内で使われている一般的でない用語を使う場合もシノニムに登録しておくことで Q が解釈してくれるようになります。
ドキュメント

例えば、Sales フィールドは、読者の質問で revenue、rev、または spending と呼ばれることがあります。

Q がこれらの用語を理解し、正しいフィールドにマッピングできるようにするには、フィールドにシノニムを 1 つ以上追加します。これにより、Q の精度が向上します。

フィールド名と同様に、リーダーはフィールド内の特定の値を示すために異なる名前を使用する場合があります。例えば、NW、SE、NE、および SW の値を含むフィールドがある場合、それらの値にシノニムを追加できます。NW にNorthwest 、SE に Southeast などを追加できます

ステップ 5: フィールドとフィールド値にシノニムを追加する


組織内の全員がフィールドの名前を知っているわけではないので、フィールドによく使用される用語をシノニムとして含める必要があります。この例では、作成者は Customer フィールドに、buyer、purchaser、Company、および client のシノニムを追加しました。このようにして、リーダーが「上位 10 人のクライアントを見せて」と尋ねると、Q は Customer フィールドのデータのことを言っていることを知っています。

ステップ 3: サンプルトピックを検索する


以下のブログでは「Osenbei」というフィールドに対して「Rice crackers」というシノニムを登録しましたが、回答では「The total number of rice crackers (Osenbei) is 633. There are 9 unique sections. The top section in terms of rice cracker count is "EFS課" with 84 rice crackers.」のように解釈されて回答を得られました。
https://dev.classmethod.jp/articles/q-in-quicksight-creata-topic-qa-dataset/#%25E3%2583%2588%25E3%2583%2594%25E3%2583%2583%25E3%2582%25AF%25E3%2581%258B%25E3%2582%2589%25E3%2583%2587%25E3%2583%25BC%25E3%2582%25BF%25E3%2582%25BB%25E3%2583%2583%25E3%2583%2588%25E3%2581%25AB%25E5%25AF%25BE%25E3%2581%2597%25E3%2581%25A6%25E8%2587%25AA%25E7%2584%25B6%25E8%25A8%2580%25E8%25AA%259E%25E3%2581%25A7-q%2526a-%25E3%2581%2597%25E3%2581%25A6%25E3%2581%25BF%25E3%2582%258B
 Synonym を一括で変更するそれでは Synonym（シノニム）を一括で設定してみます。
作成した CSV で使った CSV ファイルをアップロードしてデータセットを作成し、トピックを作成しておきます。作業はバージニア北部リージョンで行っています。（2025/2/14 現在、Q in QuickSight は東京リージョンで未 GA）
https://dev.classmethod.jp/articles/q-in-quicksight-creata-topic-qa-dataset/
 sweets_with_status.csv
datetime,department,section,status,chocolate,donut,osenbei
2024-10-16 17:00:00.000,コンピューティング部,EC2課,不調,19,1,20
2024-10-16 17:00:00.000,コンピューティング部,Lambda課,不調,12,1,22
2024-10-16 17:00:00.000,コンピューティング部,Lightsail課,不調,13,1,24
2024-10-16 17:00:00.000,ストレージ部,EFS課,超ごきげん,18,21,29
2024-10-16 17:00:00.000,ストレージ部,FSx課,ごきげん,18,10,24
2024-10-16 17:00:00.000,ストレージ部,S3課,不調,15,2,20
2024-10-16 17:00:00.000,データベース部,RDS課,普通,14,8,28
2024-10-16 17:00:00.000,データベース部,DocumentDB課,不調,19,2,29
2024-10-16 17:00:00.000,データベース部,DynamoDB課,超ごきげん,11,22,24
2024-10-16 18:00:00.000,コンピューティング部,EC2課,普通,18,8,19
2024-10-16 18:00:00.000,コンピューティング部,Lambda課,普通,11,8,21
2024-10-16 18:00:00.000,コンピューティング部,Lightsail課,普通,12,8,23
2024-10-16 18:00:00.000,ストレージ部,EFS課,超ごきげん,17,20,28
2024-10-16 18:00:00.000,ストレージ部,FSx課,超ごきげん,17,20,23
2024-10-16 18:00:00.000,ストレージ部,S3課,普通,14,9,19
2024-10-16 18:00:00.000,データベース部,RDS課,ごきげん,13,12,27
2024-10-16 18:00:00.000,データベース部,DocumentDB課,普通,18,6,28
2024-10-16 18:00:00.000,データベース部,DynamoDB課,超ごきげん,10,23,23
2024-10-16 19:00:00.000,コンピューティング部,EC2課,不調,17,1,18
2024-10-16 19:00:00.000,コンピューティング部,Lambda課,ごきげん,10,12,20
2024-10-16 19:00:00.000,コンピューティング部,Lightsail課,ごきげん,11,13,22
2024-10-16 19:00:00.000,ストレージ部,EFS課,超ごきげん,16,25,27
2024-10-16 19:00:00.000,ストレージ部,FSx課,不調,16,0,22
2024-10-16 19:00:00.000,ストレージ部,S3課,ご機嫌,13,13,18
2024-10-16 19:00:00.000,データベース部,RDS課,超ごきげん,12,20,26
2024-10-16 19:00:00.000,データベース部,DocumentDB課,ご機嫌,18,12,27
2024-10-16 19:00:00.000,データベース部,DynamoDB課,超ごきげん,9,22,22
まずは最初の設定を確認します。トピックを開きます。

「Data」タブを開き「DATA FIELDS」を確認すると、「Osenbei」に対してのシノニムが「Osen」という謎の語になっていたり、Status のシノニムが入力されていなかったりします。

では、この 2 フィールドのシノニムを一気に更新します。

一気にというには少量ですが、量が増えても手順は同じであるためご容赦ください。
 スケルトンファイルの作成update-topic-included-off.json を編集 で作成した update-topic-included-off.json をコピーして流用します。コピー後のファイル名は update-topic-set-synonyms.json とします。

CloudShell で操作してください。
cp update-topic-included-off.json update-topic-set-synonyms.json
▼実行結果
~ $ cp update-topic-included-off.json update-topic-set-synonyms.json
~ $ 
コピーしたファイル update-topic-set-synonyms.json が存在するか ls コマンドで確認します。
▼実行結果
~ $ ls
update-topic-included-off.json  update-topic-set-synonyms.json
~ $ 
コピーできていますね。
 update-topic-included-off.json を編集シノニムは各フィールドにある "ColumnSynonyms"で定義できます。

「Osenbei」には "Rice crackers" 、「Status」には "mood" 、 "mood" を追加します。

vim などで編集してください。
 update-topic-set-synonyms.json
{
    "AwsAccountId": "123456789012",
    "TopicId": "G7NAH7CCmx2csyB9gMrGbKxAZoOcsEhu",
    "Topic": {
        "Name": "sweets_with_status",
        "Description": "sweets_with_status",
        "UserExperienceVersion": "NEW_READER_EXPERIENCE",
        "DataSets": [
            {
                "DatasetArn": "arn:aws:quicksight:us-east-1:123456789012:dataset/40e73fba-718c-4ede-b791-df32268bf966",
                "DatasetName": "Sweets With Status",
                "DataAggregation": {
                    "DefaultDateColumnName": "datetime"
                },
                "Columns": [
                    {
                        "ColumnName": "datetime",
                        "ColumnFriendlyName": "Datetime",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "date",
                            "time"
                        ],
                        "ColumnDataRole": "DIMENSION",
                        "IsIncludedInTopic": false,
                        "SemanticType": {
                            "TypeName": "Date"
                        },
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "department",
                        "ColumnFriendlyName": "Department",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "division"
                        ],
                        "ColumnDataRole": "DIMENSION",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "section",
                        "ColumnFriendlyName": "Section",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "segment"
                        ],
                        "ColumnDataRole": "DIMENSION",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "status",
                        "ColumnFriendlyName": "Status",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "mood",
                            "atmosphere"
                        ],
                        "ColumnDataRole": "DIMENSION",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "chocolate",
                        "ColumnFriendlyName": "Chocolate",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "cacao",
                            "candy",
                            "cocoa"
                        ],
                        "ColumnDataRole": "MEASURE",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "donut",
                        "ColumnFriendlyName": "Donut",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "doughnut",
                            "muffin"
                        ],
                        "ColumnDataRole": "MEASURE",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    },
                    {
                        "ColumnName": "osenbei",
                        "ColumnFriendlyName": "Osenbei",
                        "ColumnDescription": "",
                        "ColumnSynonyms": [
                            "Rice crackers"
                        ],
                        "ColumnDataRole": "MEASURE",
                        "IsIncludedInTopic": false,
                        "NeverAggregateInFilter": false
                    }
                ]
            }
        ],
        "ConfigOptions": {
            "QBusinessInsightsEnabled": true
        }
    }
}
 update-topic コマンドでトピックを更新するでは、update-topic コマンドでトピックを更新します。

--cli-input-json パラメーターで作成した JSON ファイルを指定します。
aws quicksight update-topic \
  --cli-input-json file://update-topic-set-synonyms.json
▼実行結果
~ $ aws quicksight update-topic \
>   --cli-input-json file://update-topic-set-synonyms.json
{
    "Status": 200,
    "TopicId": "G7NAH7CCmx2csyB9gMrGbKxAZoOcsEhu",
    "Arn": "arn:aws:quicksight:us-east-1:123456789012:topic/G7NAH7CCmx2csyB9gMrGbKxAZoOcsEhu",
    "RefreshArn": "arn:aws:quicksight:us-east-1:123456789012:topic/G7NAH7CCmx2csyB9gMrGbKxAZoOcsEhu/refresh/1739421560820",
    "RequestId": "047769e4-1580-4bae-947f-ebc7ebfc51b1"
}
~ $ 
"Status": 200, となっており、コマンドは成功しました。QuickSight コンソールからトピックを確認します。
ブラウザを更新すると、以下のように「Osenbei」フィールドと「Status」フィールドのシノニムが更新されていることが確認できました。
 おわりにもう少し設定を簡略化するには、例えば
S3 バケットにシノニムを記載した CSV ファイルなどを格納しておく
Lambda 関数などで AWS SDK (boto3) を使用して
S3 に格納した CSV ファイルの設定を読み込む
DescribeTopic API を呼び出しトピックの設定値を JSON で取得する
取得した JSON の  "ColumnSynonyms" を S3 から取得したシノニム情報で更新
更新された JSON で UpdateTopic API を実行しシノニムを一括更新する

等の開発をすればよいのかなと思います。他に良い方法がございましたらご連絡いただければ幸いです。
本記事への質問やご要望については画面下部のお問い合わせ「DevelopersIO について」からご連絡ください。記事に関してお問い合わせいただけます。