Athena のクエリエディタとワークグループのクエリ結果を同じ S3 パスにする方法
2025.04.11Athena の動作検証の際に、クエリエディタと Athena API で、クエリ出力結果の S3 パスに違いがあることがわかったのでブログに残します。
起きた事象
現在 Athena に「test-wg-20250411」という名前のワークグループがあり、クエリ結果の保存先は S3 バケット test-20250411 を指定しています。
クエリエディタの設定でも同様に、ワークグループ test-wg-20250411 の保存先を S3 バケット test-20250411 としています。
今現在、保存先である test-20250411 バケットの中身は空の状態です。
この状態で、まずクエリエディタから、適当な名前(firstSavedQueryHoge)を付けたクエリを実行してみます。(画像右上にある通り、test-wg-20250411 を指定した状態で実行しています。)
その結果、S3 バケットにクエリ名 (firstSavedQueryHoge) のフォルダが作成され、
保存先のパスを見ると、<クエリ名>/yyyy/mm/dd/ の形式となっていました。
続いて、コンソールのクエリエディタではなくワークグループを指定した CLI (start-query-execution) からクエリを実行してみます。
以下のコマンドを実行します。
$ aws athena start-query-execution \
--query-string "SELECT * FROM "testconsoledatabase20250411"."testtable20250411" limit 10" \
--work-group "test-wg-20250411"
// 実行結果
{
"QueryExecutionId": "774db3b5-3c13-4119-94e8-43c747059764"
}
その結果、S3 バケットの直下にクエリ結果が保存されました。
まとめると、クエリエディタからの実行では出力結果が「<クエリ名>/yyyy/mm/dd/」のパスに保存されるのにも関わらず、
ワークグループを指定した Athena API 呼び出しでは、バケット直下に結果が保存され、双方のパスが異なっていることがわかります。
この動作は、ワークロードの関係上両方からクエリを実行している場合などに混乱を招く可能性があります。
そのため今回は、クエリ結果の保存先をエディタおよび Athena API の双方で揃える方法を紹介します。
解決方法
クエリエディタとAthena API の2つについて、出力結果のパスを揃える方法は、以下2種類の方法があります。
- Athena API にて OutputLocation を指定する
- ワークグループの「クライアント側の設定を上書き」をオンにする
それぞれやってみます。
Athena API にて OutputLocation を指定する
こちらの方法は、クエリ実行の API StartQueryExecution にて、「OutputLocation」を指定するやり方です。
API 実行の際に毎回出力場所を指定しないといけないため、やや手間ですが、一度設定を入れてしまえば出力場所を固定できるため便利です。
start-query-execution CLI の場合だと、以下のように OutputLocation を指定できます。
$ aws athena start-query-execution \
--query-string "SELECT * FROM "testconsoledatabase20250411"."testtable20250411" limit 10" \
--work-group "test-wg-20250411" \
--result-configuration OutputLocation="s3://test-20250411/firstSavedQueryHoge/2025/04/11/"
// 実行結果
{
"QueryExecutionId": "2dd39d6f-1cc8-4307-93ad-299b1aa2b837"
}
上記を実行すると、以下画像のように S3 バケットの指定したパスにクエリ結果を出力することができます。
クエリエディタのデフォルトの保存先である 「<クエリ名>/yyyy/mm/dd/」に結果を保存することができました。
ワークグループの「クライアント側の設定を上書き」をオンにする
こちらのやり方は、ワークグループの設定を変更し、常にワークグループで指定した S3 パスに結果を保存させるやり方です。
「クライアント側の設定を上書き」の詳細については、以下ドキュメントが詳しいため、ご参照ください。
[クライアント側の設定の上書き] を選択した場合、ワークグループ設定はワークグループのすべてのクライアントにワークグループレベルで実施されます。ワークグループでクライアント側の設定を上書きするオプションを選択すると、Athena はワークグループで実行されるすべてのクエリにワークグループの設定を使用します。これには、クエリ結果の場所、予想バケット所有者、暗号化、クエリ結果バケットに書き込むオブジェクトの制御に関する設定が含まれます。ワークグループ設定は、コンソール、API アクション、または JDBC または ODBC ドライバーを使用するときにクエリに指定したクライアント側の設定よりも優先されます。ワークグループ設定がクライアント側の設定をオーバーライドするように設定された後は、ドライバーまたは API でクライアント側の設定の指定を省略できます。
実際に設定を変更し、動作確認してみます。
ワークグループ右上の編集を選びます。ちなみに現在の「クライアント側の設定を上書き」はオフの状態です。
設定画面にて、任意の保存先パスを指定します。そして、「クライアント側の設定を上書き」にチェックを入れます。
変更を保存すると、「クライアント側の設定を上書き」および「クエリ結果の場所」が変更されていることがわかります。
それでは動作確認していきます。なお、現在の S3 バケットは空の状態です。
クエリエディタにて適当なクエリを実行します。なお、ワークグループは、test-wg-20250411 を選んだ状態です。
実行した結果、S3 バケットにワークグループで指定した HogeHoge フォルダが作成されました。
中身を見ると、クエリエディタで実行された結果が出力されていることがわかります。
続いて、CLI からも start-query-execution を実行し、動作確認します。（※ OutputLocation は指定しないで実行しています）
$ aws athena start-query-execution \
--query-string "SELECT * FROM "testconsoledatabase20250411"."testtable20250411" limit 10" \
--work-group "test-wg-20250411"
// 実行結果
{
"QueryExecutionId": "d4fca8f3-976a-46f6-804c-c8bf7008ea50"
}
CLI を実行した結果、以下のようにワークグループで指定した HogeHoge フォルダに結果が格納されました。
ちなみに CLI コマンドで OutputLocation を指定した状態で再度実行してみます。
$ aws athena start-query-execution \
--query-string "SELECT * FROM "testconsoledatabase20250411"."testtable20250411" limit 10" \
--work-group "test-wg-20250411" \
--result-configuration OutputLocation="s3://test-20250411/FugaFuga/"
// 実行結果
{
"QueryExecutionId": "ee867e26-6a67-4b7e-a87a-8f504cf576e8"
}
上記のコマンド実行はうまくいったようですが、OutputLocation で指定した FugaFuga フォルダは作成されていません。
出力結果を探すと、以下のように HogeHogeフォルダに出力されていました。「クライアント側の設定を上書き」をオンにした場合は、Athena API 側で OutputLocation を指定したとしても、ワークグループ側の設定が優先されることが確認できました。
終わりに
今回は、Athena の保存先パスについて検証してみました。
クエリエディタとワークグループの2つで保存先を指定できること自体はとても便利ですが、保存先パスが一致しないなどは盲点でした。動作仕様をちゃんと理解することが大切ですね。
クエリ結果の保存先については、過去にブログも公開されているので、こちらも併せて見て頂けたらと思います。
また、クエリエディタのデフォルトの保存先である「<クエリ名>/yyyy/mm/dd/」については、以下ドキュメントにある通り、ワークグループ設定が優先されない場合に作成されるもののようです。
次のサブフォルダは、ワークグループ設定が結果パスよりも優先されていないコンソールから実行されるクエリに対してのみ作成されます。AWS CLI から実行されるクエリまたは Athena API を使用して実行されるクエリは、QueryResultsLocationInS3 に直接保存されます。
- QueryName は結果を保存するクエリの名前です。クエリが実行されたものの、保存されなかった場合は、Unsaved が使用されます。
- yyyy/mm/dd は、クエリが実行された日付です。
実際に手を動かしてみて、Athena の結果保存先の挙動について理解が深まりました。
本記事がどなたかのお役に立てば幸いです。
参考情報
![[参加レポート] 流しのエバンジェリストシリーズ AWSを中心として色んなサービスの基礎を学ぼう 「Amazon S3 Tables + Amazon Athena / Apache Iceberg」 #awsbasics](https://images.ctfassets.net/ct0aopd36mqt/wp-thumbnail-066beb776f0c57ce64255fadcc072f60/82b2f6687ab5774cd73f9176dcac7855/amazon-s3)
