Q in QuickSight トピックの Synonym を一括で設定する
2025.02.15コーヒーが好きな emi です。
以下のブログで Q in QuickSight トピックの 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.」のように解釈されて回答を得られました。
Synonym を一括で変更する
それでは Synonym（シノニム）を一括で設定してみます。
作成した CSV で使った CSV ファイルをアップロードしてデータセットを作成し、トピックを作成しておきます。作業はバージニア北部リージョンで行っています。（2025/2/14 現在、Q in QuickSight は東京リージョンで未 GA）
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" 、 "atmosphere" を追加します。
vim などで編集してください。
{
"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」フィールドのシノニムが更新されていることが確認できました。
注意：DATA FIELDS を更新するとインデックスが更新される
DATA FIELDS を更新するとインデックスが更新されます。
Indexing Dataset
Q is indexing your data fields, they will not be available for questions until indexing is complete. Meanwhile, you can review and edit field settings in data tab or monitor status here.
（日本語訳）
データセットのインデックス作成
Qがデータフィールドをインデックス化しています。インデックス作成が完了するまで、質問には使用できません。その間、データタブでフィールド設定を確認および編集するか、ここでステータスを監視できます。
インデックスはトピック内のデータの定義などを保存していて、ユーザーからは直接見えません。
注意書きの通り、インデックスの更新中は質問ができません。
インデックスの構築時間はトピックに含まれる項目が多ければ多いほど時間がかかります。
実際に運用する際は DATA FIELDS の更新のタイミングや本当に実施するかどうかを検討の上実施ください。
ちなみに今回のデータ量だと数秒で終わることが多かったのですが、インデックス更新中に再度更新をかけると、インデックス更新が終わらなくなってしまい、数時間待ったのちに更新をキャンセルした……ということが一度ありました。
おわりに
もう少し設定を簡略化するには、例えば
- S3 バケットにシノニムを記載した CSV ファイルなどを格納しておく
- Lambda 関数などで AWS SDK (boto3) を使用して
- S3 に格納した CSV ファイルの設定を読み込む
- DescribeTopic API を呼び出しトピックの設定値を JSON で取得する
- 取得した JSON の
"ColumnSynonyms"を S3 から取得したシノニム情報で更新 - 更新された JSON で UpdateTopic API を実行しシノニムを一括更新する
等の開発をすればよいのかなと思います。他に良い方法がございましたらご連絡いただければ幸いです。
本記事への質問やご要望については画面下部のお問い合わせ「DevelopersIO について」からご連絡ください。記事に関してお問い合わせいただけます。
