# Amazon Athena で Apache Spark を使用する
Amazon Athena では、リソースの計画、設定、管理を必要とせずに、Apache Spark を使用してインタラクティブに簡単にデータ分析と探索を実行できます。Athena で Apache Spark アプリケーションを実行するということは、処理用 Spark コードを送信し、追加の設定をしなくても結果を直接受け取ることを意味します。Amazon Athena の Apache Spark はサーバーレスであり、オンデマンドで自動的にスケーリングされるため、データ量や処理要件の変化に合わせて瞬時に処理できます。
リリースバージョン [PySpark エンジンバージョン 3](notebooks-spark-release-versions.md#notebooks-spark-release-versions-pyspark-3) では、Amazon Athena コンソールのシンプルなノートブックエクスペリエンスを使用すると、Python または Athena ノートブック API を使用して Apache Spark アプリケーションを開発できます。
リリースバージョン [Apache Spark バージョン 3.5](notebooks-spark-release-versions.md#notebooks-spark-release-versions-spark-35) では、Amazon SageMaker Unified Studio ノートブックまたは互換性のある Spark Connect クライアントから Spark コードを実行できます。
Amazon Athena には次の特徴があります。
+ **コンソールの使用** - Amazon Athena コンソールから Spark アプリケーションを送信します（Pyspark エンジンバージョン 3 のみ）。
+ **スクリプティング** - Python で Apache Spark アプリケーションを迅速かつインタラクティブにビルドおよびデバッグできます。
+ **動的スケーリング** - Amazon Athena は、ジョブの実行に必要なコンピューティングリソースとメモリリソースを自動的に決定し、それに応じてそれらのリソースを指定された最大値まで継続的にスケーリングします。この動的スケーリングは、速度に影響を与えずにコストを削減します。
+ **ノートブックエクスペリエンス** - Amazon SageMaker AI Unified Studio ノートブックを使用すると、使い慣れたインターフェイスを使用した計算の作成、編集、実行が可能です。Pyspark エンジンバージョン 3 では、Athena コンソール内ノートブックを使用できます。これは Jupyter Notebook と互換性があり、計算として順番に実行されるセルのリストが含まれています。セルの内容には、コード、テキスト、マークダウン、数学、プロット、リッチメディアなどを含めることができます。
追加情報については、「*AWS Big Data Blog*」の「[Run Spark SQL on Amazon Athena Spark](https://aws.amazon.com/blogs/big-data/run-spark-sql-on-amazon-athena-spark/)」と「[Explore your data lake using Amazon Athena for Apache Spark](https://aws.amazon.com/blogs/big-data/explore-your-data-lake-using-amazon-athena-for-apache-spark/)」を参照してください。
**Topics**
+ [リリースバージョン](notebooks-spark-release-versions.md)
+ [考慮事項と制限事項](notebooks-spark-considerations-and-limitations.md)
+ [はじめに](notebooks-spark-getting-started.md)
+ [ノートブックファイルを管理する](notebooks-spark-managing.md)
+ [ノートブックエディタ](notebooks-spark-editor.md)
+ [Hive 以外のテーブル形式](notebooks-spark-table-formats.md)
+ [Python ライブラリのサポート](notebooks-spark-python-library-support.md)
+ [カスタム設定を指定する](notebooks-spark-custom-jar-cfg.md)
+ [サポートされているデータおよびストレージ形式](notebooks-spark-data-and-storage-formats.md)
+ [Apache Spark をモニタリングする](notebooks-spark-metrics.md)
+ [原価配分](notebooks-spark-cost-attribution.md)
+ [ログ記録とモニタリング](notebooks-spark-logging-monitoring.md)
+ [Spark UI アクセス](notebooks-spark-ui-access.md)
+ [Spark Connect](notebooks-spark-connect.md)
+ [リクエスタによるバケットの支払いを有効にする](notebooks-spark-requester-pays.md)
+ [Lake Formation の統合](notebooks-spark-lakeformation.md)
+ [Spark 暗号化を有効にする](notebooks-spark-encryption.md)
+ [カタログへのクロスアカウントアクセス](spark-notebooks-cross-account-glue.md)
+ [サービスクォータ](notebooks-spark-quotas.md)
+ [Athena Spark API](notebooks-spark-api-list.md)
+ [トラブルシューティング](notebooks-spark-troubleshooting.md)
# リリースバージョン
Amazon Athena for Apache Spark には、次のリリースバージョンがあります。
## PySpark エンジンバージョン 3
PySpark バージョン 3 には Apache Spark バージョン 3.2.1 が含まれています。このバージョンでは、Athena コンソール内ノートブックで Spark コードを実行できます。
## Apache Spark バージョン 3.5
Apache Spark バージョン 3.5 は Amazon EMR 7.12 に基づいており、Apache Spark バージョン 3.5.6 をパッケージ化しています。このバージョンでは、Amazon SageMaker AI Unified Studio ノートブックまたは互換性のある Spark クライアントから Spark コードを実行できます。このバージョンには、インタラクティブワークロードのエクスペリエンスを向上させるための主要機能が追加されています。
+ **Spark Connect を固定** – 認証と承認を受けた AWS エンドポイントとして Spark Connect を追加します。
+ **セッションレベル原価配分** – ユーザーは、AWSCost Explorer またはコストと使用状況レポートでインタラクティブセッションあたりのコストを追跡できます。詳細については、「[セッションレベル原価配分](notebooks-spark-cost-attribution.md)」を参照してください。
+ **高度なデバッグ機能** – API とノートブックの両方からワークロードをデバッグするために Spark UI と Spark History Server のライブサポートを追加します。詳細については、「[Spark UI へのアクセス](notebooks-spark-ui-access.md#notebooks-spark-ui-access-methods)」を参照してください。
+ ** フィルタリングされていないアクセスのサポート** – 保護された AWS Glue データカタログテーブルのうち、完全なテーブルアクセス許可を取得しているものにアクセスします。詳細については、「[Lake Formation と Athena Spark ワークグループの併用](notebooks-spark-lakeformation.md)」を参照してください。
### Spark のデフォルトプロパティ
次の表に、Athena SparkConnect セッションに適用される Spark プロパティとそのデフォルト値を示します。
| Key | デフォルトの値 | 説明 |
| --- | --- | --- |
| `spark.app.id` | `` | これは変更できません。 |
| `spark.app.name` | `default` | |
| `spark.driver.cores` | `4` | ドライバーが使用するコアの数。これは初回起動時に変更できません。 |
| `spark.driver.memory` | `10g` | ドライバーが使用するメモリの量。これは初回起動時に変更できません。 |
| `spark.driver.memoryOverhead` | `6g` | ドライバーで実行されている Python ワークロードやその他のプロセスに割り当てられたメモリオーバーヘッドの量。これは初回起動時に変更できません。 |
| `spark.cortex.driver.disk` | `64g` | Spark ドライバーディスク。これは初回起動時に変更できません。 |
| `spark.executor.cores` | `4` | 各エグゼキュターが使用するコアの数。これは初回起動時に変更できません。 |
| `spark.executor.memory` | `10g` | ドライバーが使用するメモリの量。 |
| `spark.executor.memoryOverhead` | `6g` | エグゼキュターで実行されている Python ワークロードやその他のプロセスに割り当てられたメモリオーバーヘッドの量。これは初回起動時に変更できません。 |
| `spark.cortex.executor.disk` | `64g` | Spark エグゼキュターディスク。これは初回起動時に変更できません。 |
| `spark.cortex.executor.architecture` | `AARCH_64` | エグゼキュターのアーキテクチャ。 |
| `spark.driver.extraJavaOptions` | `-Djava.net.preferIPv6Addresses=false -XX:+IgnoreUnrecognizedVMOptions --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/sun.nio.cs=ALL-UNNAMED --add-opens=java.base/sun.security.action=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED -Djdk.reflect.useDirectMethodHandle=false` | Spark ドライバーの追加 Java オプション。これは初回起動時に変更できません。 |
| `spark.executor.extraJavaOptions` | `-Djava.net.preferIPv6Addresses=false -XX:+IgnoreUnrecognizedVMOptions --add-opens=java.base/java.lang=ALL-UNNAMED --add-opens=java.base/java.lang.invoke=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.io=ALL-UNNAMED --add-opens=java.base/java.net=ALL-UNNAMED --add-opens=java.base/java.nio=ALL-UNNAMED --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED --add-opens=java.base/jdk.internal.ref=ALL-UNNAMED --add-opens=java.base/sun.nio.ch=ALL-UNNAMED --add-opens=java.base/sun.nio.cs=ALL-UNNAMED --add-opens=java.base/sun.security.action=ALL-UNNAMED --add-opens=java.base/sun.util.calendar=ALL-UNNAMED --add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED -Djdk.reflect.useDirectMethodHandle=false` | Spark エグゼキューターの追加 Java オプション。これは初回起動時に変更できません。 |
| `spark.executor.instances` | `1` | 割り当てる Spark エグゼキュターコンテナの数。 |
| `spark.dynamicAllocation.enabled` | `TRUE` | 動的リソース割り当てを有効にするオプション。このオプションは、ワークロードに基づいて、アプリケーションに登録されたエグゼキュターの数をスケールアップまたはスケールダウンします。 |
| `spark.dynamicAllocation.minExecutors` | `0` | 動的割り当てを有効にした場合のエグゼキュター数の下限。 |
| `spark.dynamicAllocation.maxExecutors` | `59` | 動的割り当てを有効にした場合のエグゼキュター数の上限。 |
| `spark.dynamicAllocation.initialExecutors` | `1` | 動的割り当てを有効にした場合に実行するエグゼキュターの初期数。 |
| `spark.dynamicAllocation.executorIdleTimeout` | `60s` | Spark がエグゼキュターを削除するまで、エグゼキュターがアイドル状態を維持できる時間の長さ。これは、動的割り当てを有効にした場合にのみ適用されます。 |
| `spark.dynamicAllocation.shuffleTracking.enabled` | `TRUE` | DRA を有効にするには、シャッフル追跡を有効にする必要があります。 |
| `spark.dynamicAllocation.sustainedSchedulerBacklogTimeout` | `1s` | タイムアウトでは、Spark スケジューラが、クラスターマネージャーに対する新規エグゼキュター起動リクエストをトリガーする前に、保留タスクの持続的なバックログを観測する時間を定義します。 |
| `spark.sql.catalogImplementation` | `hive` | |
| `spark.hadoop.hive.metastore.client.factory.class` | `com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory` | AWS Glue メタストア実装クラス。 |
| `spark.hadoop.hive.metastore.glue.catalogid` | `` | AWS Glue カタログアカウントID。 |
| `spark.sql.hive.metastore.sharedPrefixes` | `software.amazon.awssdk.services.dynamodb` | プロパティでは、Hive メタストアのクライアントコード用に作成された単独の ClassLoader ではなく、Application ClassLoader によってロードする必要があるクラス向けパッケージプレフィックスのカンマ区切りリストを指定します。 |
| `spark.hadoop.fs.s3.impl` | `org.apache.hadoop.fs.s3a.S3AFileSystem` | S3A を使用する S3A クライアントの実装を定義します。 |
| `spark.hadoop.fs.s3a.impl` | `org.apache.hadoop.fs.s3a.S3AFileSystem` | S3A クライアント（S3A）の実装を定義します。 |
| `spark.hadoop.fs.s3n.impl` | `org.apache.hadoop.fs.s3a.S3AFileSystem` | S3A を使用するネイティブ S3 クライアント（S3N）の実装を定義します。 |
| `spark.hadoop.fs.AbstractFileSystem.s3.impl` | `org.apache.hadoop.fs.s3a.S3A` | |
| `spark.hadoop.fs.s3a.aws.credentials.provider` | `software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider` | |
| `spark.hadoop.fs.s3.customAWSCredentialsProvider` | `com.amazonaws.auth.DefaultAWSCredentialsProviderChain` | |
| `spark.hadoop.mapreduce.output.fs.optimized.committer.enabled` | `TRUE` | このプロパティにより、Amazon S3 にデータを書き込むときに Spark ジョブ用に最適化されたコミットプロトコルが有効になります。true に設定すると、Spark においてコストのかかるファイル名変更オペレーションが回避されるので、デフォルトの Hadoop コミッターよりも高速で信頼性の高いアトミック書き込みを実現できます。 |
| `spark.hadoop.fs.s3a.endpoint.region` | `` | この設定では、S3A クライアントを介してアクセスされる Amazon S3 バケットの AWS リージョンを明示的に設定します。 |
| `spark.hadoop.fs.s3.getObject.initialSocketTimeoutMilliseconds` | `2000` | ここでは、ソケット接続のタイムアウトをミリ秒単位で指定します。 |
| `spark.hadoop.fs.s3a.committer.magic.enabled` | `TRUE` | これにより S3A「Magic」コミッターが有効になります。これはパフォーマンスは高いが特異性のあるコミットプロトコルで、特別なパスに対するクラスターマネージャーの基本サポートに依存します。 |
| `spark.hadoop.fs.s3a.committer.magic.track.commits.in.memory.enabled` | `TRUE` | これはMagic Committer が有効になっている場合にのみ関係するものであり、タスクによってコミットされたファイルのリストが仮のディスクファイルに書き込まれるのではなくメモリで追跡されるようにするかどうかを指定します。 |
| `spark.hadoop.fs.s3a.committer.name` | `magicv2` | この設定では、使用する特定の S3A 出力コミッターアルゴリズム（ディレクトリ、パーティション化、マジックなど）を明示的に選択します。名前を指定することで、一時データの管理、タスク失敗の処理、ターゲット Amazon S3 パスへの最終的なアトミックコミットの実行に関する戦略を選択します。 |
| `spark.hadoop.fs.s3.s3AccessGrants.enabled` | `FALSE` | プロパティを使用すると、S3A/EMRFS ファイルシステムクライアントを介して Amazon S3 データにアクセスするときに、Amazon S3 Access Grants のサポートが有効になります。 |
| `spark.hadoop.fs.s3.s3AccessGrants.fallbackToIAM` | `FALSE` | Amazon S3 Access Grants を有効にすると、このプロパティにより、Access Grants の検索が失敗した場合や十分なアクセス許可が得られない場合に Amazon S3 クライアントを従来の IAM 認証情報にフォールバックするかどうかが制御されます。 |
| `spark.pyspark.driver.python` | `/usr/bin/python3.11` | ドライバーの Python パス。 |
| `spark.pyspark.python` | `/usr/bin/python3.11` | エグゼキュターの Python パス。 |
| `spark.python.use.daemon` | `TRUE` | この設定では、Spark が各エグゼキュターで Python ワーカーデーモンプロセスを使用するかどうかを制御します。有効（デフォルトでは true）にすると、エグゼキュターがタスク間で Python ワーカーを存続させて、タスクごとに新しい Python インタープリタの起動と初期化を繰り返すオーバーヘッドを回避するため、PySpark アプリケーションのパフォーマンスが大幅に向上します。 |
| `spark.sql.execution.arrow.pyspark.enabled` | `TRUE` | Apache Arrow の使用が有効になり、PySpark の JVM プロセスと Python プロセス間のデータ転送を最適化します。 |
| `spark.sql.execution.arrow.pyspark.fallback.enabled` | `TRUE` | Apache Arrow 最適化を使用した JVM と Python 間のデータ転送中にエラーが発生した場合に Spark の動作を制御する設定プロパティ。 |
| `spark.sql.parquet.fs.optimized.committer.optimization-enabled` | `TRUE` | Parquet ファイルを特定のファイルシステム（特に Amazon S3 などのクラウドストレージシステム）に書き込むときに、最適化されたファイルコミッターを Spark に使用させるかどうかを制御する設定プロパティ。 |
| `spark.sql.parquet.output.committer.class` | `com.amazon.emr.committer.EmrOptimizedSparkSqlParquetOutputCommitter` | Parquet ファイルを書き込むときに使用する Hadoop OutputCommitter の完全修飾クラス名を指定する Spark 設定プロパティ。 |
| `spark.resourceManager.cleanupExpiredHost` | `TRUE` | このプロパティでは、削除されたノードまたは期限切れのノードで実行されていたエグゼキュターに関連付けられている Spark アプリケーションリソースをドライバーによってアクティブにクリーンアップさせるかどうかを制御します。 |
| `spark.blacklist.decommissioning.enabled` | `TRUE` | プロパティを使用すると、クラスターマネージャーにより現在廃止 (正常なシャットダウン) 処理が行われているエグゼキュターをSpark のロジックで自動的にブラックリストに登録できます。これにより、間もなく終了するエグゼキュターに対してスケジューラから新規タスクが送信されなくなるため、リソースのスケールダウン中にジョブの安定性が向上します。 |
| `spark.blacklist.decommissioning.timeout` | `1h` | ブラックリストへのホストの登録前に、タスクが廃止エグゼキュターから正常に移行されるまでの Spark の最長待機時間。 |
| `spark.stage.attempt.ignoreOnDecommissionFetchFailure` | `TRUE` | 廃止エグゼキュターからシャッフルデータを読み取るときに取得に失敗した場合に、厳格にならずステージ全体の試行に失敗しないように Spark に指示を出します。その取得失敗は回復可能と見なされ、Spark は、別の場所からデータを再度取得し（場合によっては再計算が必要）、正常なシャットダウン中に厳密なエラー処理よりもジョブの完了を優先します。 |
| `spark.decommissioning.timeout.threshold` | `20` | このプロパティは通常、内部的または特定のクラスターマネージャー設定で使用され、Spark がホストの廃止プロセスにかかる合計の最長時間を定義します。実際の廃止時間がこのしきい値を超える場合、Spark はホストのブラックリスト登録や強制終了のリクエストなど、リソースを解放するための積極的なアクションを実行する可能性があります。 |
| `spark.files.fetchFailure.unRegisterOutputOnHost` | `TRUE` | タスクが特定のホストからシャッフルデータまたは RDD データを取得できない場合、これを true に設定すると、そのホストで障害が発生したアプリケーションに関連付けられているすべての出力ブロックの登録を解除するように Spark に指示します。これにより、将来のタスクで信頼性の低いホストからデータが取得されるのを防ぎ、Spark に必要なブロックを他の場所で再計算させることで、断続的なネットワーク問題に対するジョブの堅牢性を高めます。 |
# 考慮事項と制限事項
## Apache Spark バージョン 3.5
リリースバージョン Apache Spark バージョン 3.5 の考慮事項と制限事項は次のとおりです。
+ このリリースバージョンは以下の AWS リージョン で利用できます。
+ アジアパシフィック (ムンバイ)
+ アジアパシフィック (ソウル)
+ アジアパシフィック (シンガポール)
+ アジアパシフィック (シドニー)
+ アジアパシフィック (東京)
+ カナダ (中部)
+ 欧州 (フランクフルト)
+ 欧州 (アイルランド)
+ 欧州 (ロンドン)
+ 欧州 (パリ)
+ 欧州 (ストックホルム)
+ 南米 (サンパウロ)
+ 米国東部 (バージニア北部)
+ 米国東部 (オハイオ)
+ 米国西部 (オレゴン)
+ このエンジンバージョンは、Athena コンソール内ノートブックとノートブック API をサポートしていません。代わりに、このバージョンは Amazon SageMaker AI Unified Studio ノートブックと統合されます。互換性のある Spark Connect クライアントを使用することもできます。
+ 計算 API - `StartCalculationExecution`、`ListCalculationExecutions`、`GetCalculationExecution` は、このリリースではサポートされていません。
+ ワークグループを PySpark エンジンバージョン 3 から Apache Spark バージョン 3.5 にアップグレードすることはできません。
## Pyspark エンジンバージョン 3
リリースバージョン Pyspark エンジンバージョン 3 の考慮事項と制限事項は次のとおりです。
+ このリリースバージョンは以下の AWS リージョン で利用できます。
+ アジアパシフィック (ムンバイ)
+ アジアパシフィック (シンガポール)
+ アジアパシフィック (シドニー)
+ アジアパシフィック (東京)
+ 欧州 (フランクフルト)
+ 欧州 (アイルランド)
+ 米国東部 (バージニア北部)
+ 米国東部 (オハイオ)
+ 米国西部 (オレゴン)
+ AWS Lake Formation はサポートされていません。
+ パーティション射影を使用するテーブルはサポートされていません。
+ Apache Spark 対応のワークグループでは Athena ノートブックエディターを使用できますが、Athena クエリエディターを使用することはできません。Athena SQL ワークグループのみが、Athena クエリエディターを使用できます。
+ クロスエンジンビューのクエリはサポートされていません。Athena SQL で作成されたビューでは、Athena for Spark がクエリを実行することはできません。2 つのエンジンのビューは実装方法が異なるため、エンジン間の使用に互換性がありません。
+ MLlib (Apache Spark 機械学習ライブラリ) および `pyspark.ml` パッケージはサポートされていません。サポートされている Python ライブラリのリストについては、「[プリインストールされている Python ライブラリのリスト](notebooks-spark-preinstalled-python-libraries.md)」を参照してください。
+ 現在、Athena for Spark セッションで `pip install` はサポートされていません。
+ 1 つのノートブックで許可されるアクティブなセッションは 1 つのみです。
+ 複数のユーザーがコンソールを使用してワークグループ内の既存のセッションを開く場合、同じノートブックにアクセスします。混同を避けるため、自分で作成したセッションのみを開いてください。
+ Amazon Athena で使用する Apache Spark アプリケーションのホスティングドメイン (例:`analytics-gateway.us-east-1.amazonaws.com`) は、インターネットの「[パブリックサフィックスリスト (PSL)](https://publicsuffix.org/list/public_suffix_list.dat)」に登録されています。ドメインに機密性の高いクッキーを設定する必要がある場合、ドメインをクロスサイトリクエストフォージェリ (CSRF) 攻撃から保護できるように、`__Host-` プレフィックスを付けたクッキーを使用することをお勧めします。詳細については、Mozilla.org のデベロッパー向けドキュメントの「[クッキーの設定](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#cookie_prefixes)」ページを参照してください。
+ Athena での Spark ノートブック、セッション、ワークグループのトラブルシューティングについては、「[Athena for Spark をトラブルシューティングする](notebooks-spark-troubleshooting.md)」を参照してください。
# Amazon Athena で Apache Spark を開始する
**注記**
リリースバージョン Apache Spark バージョン 3.5 については、[SageMaker ノートブック](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)の開始方法ガイドに従ってください。このガイドは、リリースバージョン Pyspark エンジンバージョン 3 に使用します。
Amazon Athena で Apache Spark の使用を開始するには、最初に Spark が有効になっているワークグループを作成する必要があります。ワークグループに切り替えた後、ノートブックを作成するか、既存のノートブックを開くことができます。Athena でノートブックを開くと、そのノートブックに対して新しいセッションが自動的に開始され、Athena ノートブックエディタで直接操作できます。
**注記**
ノートブックを作成する前に、必ず Spark 対応のワークグループを作成してください。
## ステップ 1: Athena で Spark 対応のワークグループを作成する
Athena の[ワークグループ](workgroups-manage-queries-control-costs.md)を使用して、ユーザー、チーム、アプリケーション、またはワークロードをグループ化し、コストを追跡できます。Amazon Athena で Apache Spark を使用するには、Spark エンジンを使用する Amazon Athena ワークグループを作成します。
**注記**
Apache Spark 対応のワークグループでは Athena ノートブックエディターを使用できますが、Athena クエリエディターを使用することはできません。Athena SQL ワークグループのみが、Athena クエリエディターを使用できます。
**Athena で Spark 対応のワークグループを作成するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
![\[展開メニューを選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/nav-pane-expansion.png)
1. ナビゲーションペインで、**[Workgroups]** (ワークグループ) を選択します。
1. **[Workgroups]** (ワークグループ) ページで、**[Create workgroup]** (ワークグループを作成する) をクリックします。
1. **[Workgroup name]** (ワークグループ名) には、Apache Spark ワークグループの名前を入力します。
1. (オプション) **[Description]** (説明) で、ワークグループの説明を入力します。
1. **[Analytics engine]** (アナリティクスエンジン) には、**[Apache Spark]** を選択してください。
**注記**
ワークグループを作成した後は、ワークグループの分析エンジンのタイプを変更することはできません。たとえば、Athena エンジンのバージョン 3 のワークグループを PySpark エンジンのバージョン 3 のワークグループに変更することはできません。
1. このチュートリアルでは、**[Turn on example notebook]** (ノートブックのサンプルを有効にする) を選択します。このオプション機能では、`example-notebook-random_string` という名前のノートブックのサンプルをワークグループに追加し、ノートブックがアカウント内の特定のデータベースやテーブルを作成、表示、削除するために使用する AWS Glue に関連するアクセス許可と、データセットのサンプルの Amazon S3 での読み込みアクセス許可を追加します。追加されたアクセス許可を確認するには、**[View additional permissions details]** (追加のアクセス許可の詳細を表示) を選択します。
**注記**
ノートブックのサンプルを実行すると、追加コストが発生する可能性があります。
1. **[計算結果の設定]** で、次のオプションから選択します。
+ **新しい S3 バケットを作成** - このオプションでは、計算の結果用 Amazon S3 バケットがアカウントに作成されます。バケット名は形式 `account_id-region-athena-results-bucket-alphanumeric_id` で、ACL を無効にする、パブリックアクセスをブロックする、バージョニングを無効にする、バケット所有者を強制するなどの設定を使用しています。
+ **既存の S3 の場所を選択** - このオプションでは、次の操作を行います。
+ 検索ボックスに既存の場所への S3 パスを入力するか、**[Browse S3]** (S3 の参照) を選択してリストからバケットを選択します。
**注記**
Amazon S3 の既存の場所を選択するときは、その場所にスラッシュ (`/`) を追加しないでください。これを行うと、[計算の詳細ページ](#notebooks-spark-getting-started-viewing-session-and-calculation-details)の計算結果の場所へのリンクが間違ったディレクトリを指すようになります。このような場合、ワークグループの結果の場所を編集して末尾のスラッシュを削除してください。
+ (オプション) **[View]** (表示) を選択して Amazon S3 コンソールの **[Buckets]** (バケット) ページを開き、選択した既存のバケットに関する詳細情報を表示できます。
+ (オプション) **[Expected bucket owner]** (想定されるバケット所有者) に、クエリ結果の出力場所バケットの所有者になると想定されている AWS の ID を入力します。可能な限り、追加のセキュリティ対策としてこのオプションを選択することをお勧めします。バケット所有者のアカウント ID が指定した ID と一致しない場合、バケットに出力できません。詳細については、「Amazon S3 ユーザーガイド」の「[バケット所有者条件によるバケット所有者の確認](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html)」を参照してください。
+ (オプション) 計算結果の場所が別のアカウントによって所有されており、クエリ結果に対する完全な制御を他のアカウントに許可したい場合、**[Assign bucket owner full control over query results]** (クエリ結果を完全に制御できるバケット所有者を割り当てる) を選択します。
1. (オプション) クエリ結果を暗号化するには、**[クエリ結果の暗号化]** を選択します。
+ **[暗号化タイプ]** で、以下のいずれかのオプションを選択します。
+ **SSE\$1S3** – このオプションは、Amazon S3 で管理された暗号化キーによるサーバー側の暗号化 (SSE) を使用します。
+ **SSE\$1KMS** – このオプションは、AWS KMS で管理されたキーによるサーバー側の暗号化 (SSE) を使用します。
**[AWS KMS キーを選択]** で、次のいずれかのオプションを選択します。
+ **AWS 所有キーを使用する** – AWS KMS キーは AWS によって所有および管理されます。このキーは追加料金なしで使用されます。
+ **別の AWS KMS キーを選択する (アドバンスト)** – このオプションでは、次のいずれかを実行します。
+ 既存のキーを使用するには、検索ボックスを使用して AWS KMS を選択するか、キーの ARN を入力します。
+ AWS KMS コンソールでキーを作成するには、**[AWS KMS キーを作成する]** を選択します。実行ロールには、作成したキーを使用するアクセス許可が必要です。KMS コンソールでキーを作成し終えたら、Athena コンソールの **[ワークグループを作成]** ページに戻り、**[AWS KMS キーを選択するか、ARN を入力]** 検索ボックスを使用して、今作成したキーを選択します。
**重要**
ワークグループの [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) を変更しても、更新前に管理されていたノートブックは引き続き古い KMS キーを参照します。更新後に管理されるノートブックでは、新しい KMS キーを使用します。以前のノートブックを新しい KMS キーを参照するように更新するには、以前のノートブックをそれぞれエクスポートしてからインポートします。以前のノートブックの参照を新しい KMS キーに更新する前に以前の KMS キーを削除すると、古いノートブックは復号化できなくなり、復元できなくなります。
この動作は、KMS キーのわかりやすい名前である[エイリアス](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)の更新にも当てはまります。KMS キーエイリアスを新しい KMS キーを指すように更新すると、エイリアスの更新前に管理されていたノートブックでは引き続き古い KMS キーを参照し、エイリアスの更新後に管理されたノートブックでは新しい KMS キーを使用します。KMS キーまたはエイリアスを更新する前に、これらの点を考慮してください。
1. **[追加設定]** で、**[デフォルトを使用]** を選択します。このオプションは Spark 対応のワークグループの使用を開始するのに役立ちます。このデフォルトを使用すると、Athena は IAM ロールと計算結果の場所を Amazon S3 に自動的に作成します。IAM ロールの名前と作成する S3 バケットの場所は、**[Additional configurations]** (追加設定) の見出しの下にあるボックスに表示されます。
デフォルトを使用しない場合は、[(オプション) 独自のワークグループ設定を指定します。](#notebooks-spark-getting-started-workgroup-configuration) セクションの手順に進んでワークグループを手動で設定します。
1. (オプション) **[Tags]** (タグ) - このオプションを使用して、ワークグループにタグを追加します。詳細については、「[Athena リソースにタグ付けする](tags.md)」を参照してください。
1. **[Create workgroup]** (ワークグループの作成) を選択します。ワークグループが正常に作成されたことを知らせるメッセージが表示され、そのワークグループはワークグループのリストに表示されます。
### (オプション) 独自のワークグループ設定を指定します。
ノートブック独自の IAM ロールと計算結果の場所を指定する場合は、このセクションの手順に従います。**[Additional configurations]** (その他の設定) オプションに **[Use defaults]** (デフォルトを使用) を選択した場合は、このセクションを飛ばして直接 [ステップ 2: ノートブックエクスプローラーを開いてワークグループを切り替える](#notebooks-spark-getting-started-switching-workgroups-and-opening-notebook-explorer) に進んでください。
以下の手順は、前のセクションの **[To create a Spark enabled workgroup in Athena]** (Athena で Spark 対応のワークグループを作成するには) の手順 1～9 を完了していることを前提としています。
**独自のワークグループ設定を指定するには**
1. 独自の IAM ロールを作成または使用したり、ノートブックの暗号化を設定したりする場合は、**[IAM role configuration]** (IAM ロール設定) を拡張してください。
+ **[Athena を承認するサービスロール]** で、以下のいずれかのオプションを選択します。
+ **新しいサービスロールを作成および使用する** – このオプションを選択すると、Athena はサービスロールを自動的に作成します。ロールを付与するアクセス許可を確認するには、**[View permission details]** (アクセス許可の詳細を表示) を選択します。
+ **既存のサービスロールを使用する** – ドロップダウンメニューから既存のロールを選択します。選択するロールには、最初のオプションでアクセス許可を含める必要があります。ノートブック対応ワークグループのアクセス許可の詳細については、「[Spark 対応ワークグループをトラブルシューティングする](notebooks-spark-troubleshooting-workgroups.md)」を参照してください。
+ **[Notebook and calculation code encryption key management]** (ノートブックと計算コードの暗号化キーを管理) には、次のいずれかのオプションを選択します。
+ **AWS 所有キーを使用して暗号化する (デフォルト)** – AWS KMS キーは AWS によって所有および管理されます。このキーは追加料金なしで使用されます。
+ **独自の AWS KMS キーを使用して暗号化する** – このオプションでは、次のいずれかを実行します。
+ 既存のキーを使用するには、検索ボックスを使用して AWS KMS を選択するか、キーの ARN を入力します。
+ AWS KMS コンソールでキーを作成するには、**[AWS KMS キーを作成する]** を選択します。実行ロールには、作成したキーを使用するアクセス許可が必要です。KMS コンソールでキーを作成し終えたら、Athena コンソールの **[ワークグループを作成]** ページに戻り、**[AWS KMS キーを選択するか、ARN を入力]** 検索ボックスを使用して、今作成したキーを選択します。
**重要**
ワークグループの [AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html) を変更しても、更新前に管理されていたノートブックは引き続き古い KMS キーを参照します。更新後に管理されるノートブックでは、新しい KMS キーを使用します。以前のノートブックを新しい KMS キーを参照するように更新するには、以前のノートブックをそれぞれエクスポートしてからインポートします。以前のノートブックの参照を新しい KMS キーに更新する前に以前の KMS キーを削除すると、古いノートブックは復号化できなくなり、復元できなくなります。
この動作は、KMS キーのわかりやすい名前である[エイリアス](https://docs.aws.amazon.com/kms/latest/developerguide/kms-alias.html)の更新にも当てはまります。KMS キーエイリアスを新しい KMS キーを指すように更新すると、エイリアスの更新前に管理されていたノートブックでは引き続き古い KMS キーを参照し、エイリアスの更新後に管理されたノートブックでは新しい KMS キーを使用します。KMS キーまたはエイリアスを更新する前に、これらの点を考慮してください。
1. (オプション) **[Other settings]** (その他の設定) - このオプションを拡張して、ワークグループの **[Publish CloudWatch metrics]** (CloudWatch メトリクスの公開) オプションを有効または無効にします。このフィールドは、デフォルトで選択されています。詳細については、「[CloudWatch メトリクスを使用して Apache Spark をモニタリングする](notebooks-spark-metrics.md)」を参照してください。
1. (オプション) **[Tags]** (タグ) - このオプションを使用して、ワークグループにタグを追加します。詳細については、「[Athena リソースにタグ付けする](tags.md)」を参照してください。
1. **[Create workgroup]** (ワークグループの作成) を選択します。ワークグループが正常に作成されたことを知らせるメッセージが表示され、そのワークグループはワークグループのリストに表示されます。
## ステップ 2: ノートブックエクスプローラーを開いてワークグループを切り替える
作成したばかりの Spark 対応ワークグループを使用する前に、そのワークグループに切り替える必要があります。Spark 対応のワークグループを切り替えるには、ノートブックエクスプローラー、またはノートブックエディタの **[Workgroup]** (ワークグループ) オプションを使用できます。
**注記**
開始する前に、ブラウザがサードパーティの Cookie をブロックしていないことを確認してください。ブラウザのデフォルトまたはユーザーの設定でサードパーティのCookieをブロックしている場合、ノートブックは起動しません。Cookie の管理の詳細については、以下を参照してください。
[Chrome](https://support.alertlogic.com/hc/en-us/articles/360018127132-Turn-Off-Block-Third-Party-Cookies-in-Chrome-for-Windows)
[Firefox](https://support.mozilla.org/en-US/kb/third-party-cookies-firefox-tracking-protection)
[Safari](https://support.apple.com/guide/safari/manage-cookies-sfri11471/mac)
**ノートブックエクスプローラーを開いてワークグループを切り替える**
1. ナビゲーションペインで、**[Notebook Explorer]** (ノートブックエクスプローラー) を選択します。
1. コンソールの右上にある **[Workgroup]** (ワークグループ) オプションを使用して、作成した Spark 対応ワークグループを選択します。ノートブックのサンプルがノートブックのリストに表示されます。
ノートブックエクスプローラーは次の方法で使用できます。
+ ノートブックのリンクされた名前を選択して、そのノートブックを新しいセッションで開きます。
+ ノートブックの名前変更、削除、またはエクスポートを行うには、**[Actions]** (アクション) メニューを使用します。
+ ノートブックファイルをインポートするには、**[Import file]** (ファイルをインポート) を選択します。
+ ノートブックを作成するには、**[Create notebook]** (ノートブックの作成) を選択します。
## ステップ 3: ノートブックのサンプルを実行する
ノートブックのサンプルは、一般公開されているニューヨーク市のタクシー旅行データセットのデータをクエリします。ノートブックには、Spark DataFrames、Spark SQL、および AWS Glue Data Catalog の操作方法を示す例が示されています。
**ノートブックのサンプルを実行するには**
1. ノートブックエクスプローラーで、ノートブックのサンプルのリンクされた名前を選択します。
これにより、デフォルトのパラメータでノートブックセッションが開始され、ノートブックエディタでノートブックが開きます。デフォルトのパラメータ (最大 20 DPU) を使用して新しい Apache Spark セッションが開始されたことを知らせるメッセージが表示されます。
1. セルを順番に実行して結果を確認するには、ノートブックのセルごとに **[Run]** (実行) ボタンを 1 回選択します。
+ 下へスクロールすると結果が表示され、新しいセルが表示されます。
+ 計算されたセルに対して、進行状況バーには完了率、経過時間、残り時間が表示されます。
+ ノートブックのサンプルは、アカウントにデータベースのサンプルとテーブルを作成します。最後のセルでは、クリーンアップの手順としてこれらを削除します。
**注記**
ノートブックのサンプルのフォルダ、テーブル、またはデータベース名を変更する場合は、それらの変更が使用する IAM ロールに反映されていることを確認してください。そうしない場合、アクセス許可が不十分なため、ノートブックを実行できない可能性があります。
## ステップ 4: セッションの詳細を編集する
ノートブックセッションを開始後に、テーブルの形式、暗号化、セッションアイドルのタイムアウト、使用するデータ処理単位 (DPU) の最大同時数などのセッションの詳細を編集できます。DPU は処理能力を相対的に測定するもので、4 個の vCPU のコンピューティング性能と 16 GB のメモリで構成されています。
**セッションの詳細を編集するには**
1. ノートブックエディタで、右上の **[Session]** (セッション) メニューから **[Edit session]** (セッションの編集) を選択します。
1. **[セッションの詳細の編集]** ダイアログボックスにある **[セッションパラメータ]** セクションで、次のオプションの値を選択するか入力します。
+ **その他のテーブル形式** — **[Linux Foundation Delta Lake]**、**[Apache Hudi]**、**[Apache Iceberg]**、または **[カスタム]** を選択します。
+ **[Delta]**、**[Hudi]**、または **[Iceberg]** のテーブルオプションの場合は、該当するテーブル形式に必要となるテーブルプロパティは **[テーブルで編集]** および **[JSON で編集]** オプションに自動的に提供されます。テーブル形式の使用に関する詳細な情報については、「[Athena for Spark で Hive 以外のテーブル形式を使用する](notebooks-spark-table-formats.md)」を参照してください。
+ **[カスタム]** またはその他のテーブルタイプのテーブルプロパティを追加または削除するには、**[テーブルで編集]** オプションと **[JSON で編集]** オプションを使用します。
+ **[テーブルで編集]** オプションを使用する場合は、**[プロパティを追加]** を選択してプロパティを追加するか、**[削除]** を選択してプロパティを削除します。**[キー]** ボックスと **[値]** ボックスを使用して、プロパティ名とその値を入力します。
+ **[JSON で編集]** オプションを使用する場合は、JSON テキストエディタを使用して設定を直接編集します。
+ JSON テキストをクリップボードにコピーするには、**[コピー]** を選択します。
+ JSON エディタからすべてのテキストを削除するには、**[クリア]** を選択します。
+ 行折り返しの動作を設定するか、JSON エディタのカラーテーマを選択するには、設定 (歯車) アイコンを選択します。
+ **[Spark 暗号化を有効にする]-** — ディスクに書き込まれ、Spark ネットワークノードを介して送信されるデータを暗号化する場合は、このオプションを選択します。詳細については、「[Apache Spark 暗号化を有効にする](notebooks-spark-encryption.md)」を参照してください。
1. **[セッションパラメータ]** セクションで、次のオプションの値を選択するか入力します。
+ **[Session idle timeout]** (セッションアイドルタイムアウト) - 1～480 分の値を選択または入力します。デフォルトは 20 です。
+ **[Coordinator size]** (コーディネーターサイズ) - コーディネーターは、ノートブックセッションで処理作業を調整し、他のエグゼキューターを管理する特別なエグゼキューターです。現在、1 つの DPU がデフォルトで、唯一の設定可能な値です。
+ **[Executor size]** (エグゼキューターサイズ) - エグゼキューターは、ノートブックセッションが Athena にリクエストできる最小の計算単位です。現在、1 つの DPU がデフォルトで、唯一の設定可能な値です。
+ **[Max concurrent value]** (同時実行の最大値) - 同時に実行できる DPU の最大数。デフォルトは 20 で、最小は 3、最大は 60 です。この値を増加しても自動的に追加のリソースが割り当てられるわけではありませんが、Athena では、計算負荷がそれを必要とし、リソースが使用可能になったときに、指定された最大数まで割り当てようとします。
1. **[保存]** を選択します。
1. **[Confirm edit]** (編集を確認) プロンプトで、**[Confirm]** (確認) を選択します。
Athena はノートブックを保存し、指定したパラメータを使用して新しいセッションを開始します。ノートブックエディタのバナーに、変更されたパラメータで新しいセッションが開始されたことが通知されます。
**注記**
Athena はノートブックのセッション設定を記憶します。セッションのパラメータを編集してセッションを終了すると、Athena はノートブックのセッションを次に開始するときに設定したセッションパラメータを使用します。
## ステップ 5: セッションおよび計算の詳細を表示する
ノートブックを実行すると、セッションおよび計算の詳細を表示できます。
**セッションおよび計算の詳細を表示するには**
1. 右上の **[Session]** (セッション) メニューから **[View details]** (詳細を表示) を選択します。
+ **[Current session]** (現在のセッション) タブには、セッション ID、作成時間、ステータス、ワークグループなど、現在のセッションに関する情報が表示されます。
+ **[History]** (履歴) タブには、以前のセッションのセッション ID が表示されます。以前のセッションの詳細を表示するには、**[History]** (履歴) タブを選択し、リストからセッション ID を選択します。
+ **[Calculations]** (計算) セクションには、セッションで実行された計算のリストが表示されます。
1. 計算の詳細を表示するには、計算 ID を選択します。
1. **[Calculation details]** (計算の詳細) ページで、以下の操作を実行できます。
+ 計算用のコードを確認するには、**[Code]** (コード) セクションを参照してください。
+ 計算の結果を確認するには、**[Results]** (結果) タブを選択します。
+ テキスト形式で表示された結果をダウンロードするには、**[Download results]** (結果をダウンロード) を選択します。
+ Amazon S3 の計算結果に関する情報を表示するには、**[View in S3]** (S3 で表示) を選択します。
## ステップ 6: セッションを終了する
**ノートブックセッションを終了するには**
1. ノートブックエディタで、右上の **[Session]** (セッション) メニューから **[Terminate]** (終了) を選択します。
1. **[Confirm session termination]** (セッション終了の確認) プロンプトで、**[Confirm]** (確認) を選択します。ノートブックが保存され、ノートブックエディタに戻ります。
**注記**
ノートブックエディタのノートブックタブを閉じても、アクティブなノートブックのセッションは自動的には終了しません。セッションを確実に終了させたい場合は、**[Session]** (セッション)、**[Terminate]** (終了) オプションを使用してください。
## ステップ 7: 独自のノートブックを作成する
Spark 対応の Athena ワークグループを作成すると、独自のノートブックを作成できます。
**ノートブックを作成するには**
1. コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
1. Athena コンソールのナビゲーションペインで、**[Notebook explorer]** (ノートブックエクスプローラー) または **[Notebook editor]** (ノートブックエディタ) を選択します。
1. 次のいずれかを行います。
+ **[Notebook explorer]** (ノートブックエクスプローラー) で、**[Create notebook]** (ノートブックの作成) を選択します。
+ **[Notebook editor]** (ノートブックエディタ) で、**[Create notebook]** (ノートブックの作成) を選択するか、プラスアイコン (**[\$1]**) を選択してノートブックを追加します。
1. **[Create notebook]** (ノートブックの作成) ダイアログボックスの **[Notebook name]** (ノートブック名) に名前を入力します。
1. (オプション) **[Spark プロパティ]** を展開し、次のオプションの値を選択するか入力します。
+ **その他のテーブル形式** — **[Linux Foundation Delta Lake]**、**[Apache Hudi]**、**[Apache Iceberg]**、または **[カスタム]** を選択します。
+ **[Delta]**、**[Hudi]**、または **[Iceberg]** のテーブルオプションの場合は、該当するテーブル形式に必要となるテーブルプロパティは **[テーブルで編集]** および **[JSON で編集]** オプションに自動的に提供されます。テーブル形式の使用に関する詳細な情報については、「[Athena for Spark で Hive 以外のテーブル形式を使用する](notebooks-spark-table-formats.md)」を参照してください。
+ **[カスタム]** またはその他のテーブルタイプのテーブルプロパティを追加または削除するには、**[テーブルで編集]** オプションと **[JSON で編集]** オプションを使用します。
+ **[テーブルで編集]** オプションを使用する場合は、**[プロパティを追加]** を選択してプロパティを追加するか、**[削除]** を選択してプロパティを削除します。**[キー]** ボックスと **[値]** ボックスを使用して、プロパティ名とその値を入力します。
+ **[JSON で編集]** オプションを使用する場合は、JSON テキストエディタを使用して設定を直接編集します。
+ JSON テキストをクリップボードにコピーするには、**[コピー]** を選択します。
+ JSON エディタからすべてのテキストを削除するには、**[クリア]** を選択します。
+ 行折り返しの動作を設定するか、JSON エディタのカラーテーマを選択するには、設定 (歯車) アイコンを選択します。
+ **[Spark 暗号化を有効にする]-** — ディスクに書き込まれ、Spark ネットワークノードを介して送信されるデータを暗号化する場合は、このオプションを選択します。詳細については、「[Apache Spark 暗号化を有効にする](notebooks-spark-encryption.md)」を参照してください。
1. (オプション) **[Session parameters]** (セッションパラメータ) を展開し、次のオプションの値を選択または入力します。
+ **[Session idle timeout]** (セッションアイドルタイムアウト) - 1～480 分の値を選択または入力します。デフォルトは 20 です。
+ **[Coordinator size]** (コーディネーターサイズ) - コーディネーターは、ノートブックセッションで処理作業を調整し、他のエグゼキューターを管理する特別なエグゼキューターです。現在、1 つの DPU がデフォルトで、唯一の設定可能な値です。DPU (Data Processing Unit) は処理能力を相対的に測定するもので、4 個の vCPU のコンピューティング性能と 16 GB のメモリで構成されています。
+ **[Executor size]** (エグゼキューターサイズ) - エグゼキューターは、ノートブックセッションが Athena にリクエストできる最小の計算単位です。現在、1 つの DPU がデフォルトで、唯一の設定可能な値です。
+ **[Max concurrent value]** (同時実行の最大値) - 同時に実行できる DPU の最大数。デフォルトは 20 で、最大は 60 です。この値を増加しても自動的に追加のリソースが割り当てられるわけではありませんが、Athena では、計算負荷がそれを必要とし、リソースが使用可能になったときに、指定された最大数まで割り当てようとします。
1. **[作成]** を選択します。ノートブックはノートブックエディタの新しいセッションで開きます。
ノートブックファイルの管理方法については、「[ノートブックファイルを管理する](notebooks-spark-managing.md)」を参照してください。
# ノートブックファイルを管理する
**注記**
Athena ノートブックエディタは、Pyspark エンジンバージョン 3 でサポートされています。Apache Spark バージョン 3.5 でのノートブックの使用については、「[SageMaker ノートブック](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)」を参照してください。
ノートブックエクスプローラーを使用してノートブックを[作成](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)できるほか、ノートブックのオープン、名前変更、削除、エクスポート、インポートや、ノートブックのセッション履歴の表示もできます。
**以前に作成したノートブックを開くには**
1. コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
1. Athena コンソールのナビゲーションペインで、**[Notebook editor]** (ノートブックエディタ) または **[Notebook explorer]** (ノートブックエクスプローラー) を選択します。
1. 次のいずれかを行います。
+ **[Notebook editor]** (ノートブックエディタ) で、**[Recent notebooks]** (最近使用したノートブック) または **[Saved notebooks]** (保存したノートブック) リストからノートブックを選択します。新しいセッションでノートブックが開きます。
+ **[Notebook explorer]** (ノートブックエクスプローラー) で、リスト内のノートブックの名前を選択します。新しいセッションでノートブックが開きます。
**ノートブックの名前を変更するには**
1. 名前を変更するノートブックのアクティブなセッションをすべて[終了](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session)します。ノートブックの名前を変更する前に、ノートブックのアクティブなセッションを終了する必要があります。
1. **[Notebook explorer]** (ノートブックエクスプローラー) を開きます。
1. **[Notebooks]** (ノートブック) リストで、名前を変更するノートブックのオプションボタンを選択します。
1. **[Actions]** (アクション) メニューで、**[Rename]** (名前を変更) を選択します。
1. **[Rename notebook]** (ノートブックの名前を変更) プロンプトで、新しい名前を入力してから、**[Save]** (保存) を選択します。新しいノートブック名がノートブックのリストに表示されます。
**ノートブックを削除するには**
1. 削除するノートブックのアクティブなセッションをすべて[終了](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session)します。ノートブックを削除する前に、ノートブックのアクティブなセッションを終了する必要があります。
1. **[Notebook explorer]** (ノートブックエクスプローラー) を開きます。
1. **[Notebooks]** (ノートブック) の一覧で、削除するノートブックのオプションボタンを選択します。
1. [**アクション**] メニューから、[**削除**] を選択します。
1. **[Delete notebook?]** (ノートブックを削除しますか?) のプロンプトで、ノートブックの名前を入力し、**[Delete]** (削除) を選択して削除を確定します。ノートブック名はノートブックのリストから削除されています。
**ノートブックをエクスポートするには**
1. **[Notebook explorer]** (ノートブックエクスプローラー) を開きます。
1. **[Notebooks]** (ノートブック) リストで、エクスポートするノートブックのオプションボタンを選択します。
1. **[Actions]** (アクション) メニューで、**[Export file]** (ファイルのエクスポート) を選択します。
**ノートブックをインポートするには**
1. **[Notebook explorer]** (ノートブックエクスプローラー) を開きます。
1. **[Import file]** (ファイルのインポート) を選択します。
1. インポートするファイルのローカルコンピュータ上の場所を参照し、**[Open]** (開く) を選択します。インポートしたノートブックはノートブックのリストに表示されます。
**ノートブックのセッション履歴を表示するには**
1. **[Notebook explorer]** (ノートブックエクスプローラー) を開きます。
1. **[Notebooks]** (ノートブック) リストで、セッション履歴を表示するノートブックのオプションボタンを選択します。
1. **[Actions]** (アクション) メニューから、**[Session history]** (セッション履歴) を選択します。
1. **[History]** (履歴) タブで、**[Session ID]** (セッション ID) を選択すると、セッションとその計算に関する情報が表示されます。
# Athena ノートブックエディタを使用する
**注記**
Athena ノートブックエディタは、Pyspark エンジンバージョン 3 でサポートされています。Apache Spark バージョン 3.5 でのノートブックの使用については、「[SageMaker ノートブック](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)」を参照してください。
Athena ノートブックエクスプローラーでノートブックを管理し、Athena ノートブックエディタを使用してセッションで編集および実行します。要件に応じて、ノートブックセッションの DPU 使用率を設定できます。
ノートブックを停止すると、関連するセッションが終了します。すべてのファイルは保存されますが、宣言された変数、関数、クラスで行われている変更は失われます。ノートブックを再起動すると、Athena がノートブックファイルをリロードし、コードを再実行できるようになります。
Athena ノートブックエディタは、コードを記述して実行するためのインタラクティブな環境です。以下のセクションでは、環境の機能について説明します。
## ノートブックセッションと計算を理解する
各ノートブックは 1 つの Python カーネルに関連付けられており、Python コードを実行します。ノートブックは、コマンドを含むセルを 1 つ以上含めることができます。ノートブックでセルを実行するには、最初にノートブックのセッションを作成します。セッションは、ノートブックの変数と状態を追跡します。
ノートブックでセルを実行するということは、現在のセッションで計算を実行することを意味します。計算によってノートブックの状態が進行して、Amazon S3 からの読み込みや他のデータストアへの書き込みなどのタスクが実行される場合があります。セッションが実行されている限り、計算によってノートブックの状態は維持され、変更されます。
状態が不要になった場合、セッションを終了できます。セッションを終了してもノートブックは保持されますが、変数やその他の状態情報は破棄されます。同時に複数のプロジェクトに取り組む必要がある場合、プロジェクトごとにセッションを作成すると、セッションは互いに独立したものになります。
セッションには、DPU 単位で測定される専用の処理能力があります。セッションを作成する場合、そのセッションに複数の DPU を割り当てることができます。セッションが異なると、タスクの要件に応じて異なる容量を持つことができます。
## コマンドモードと編集モードを切り替える
ノートブックエディタは、セルにテキストを入力するための編集モードと、コピー、貼り付け、実行などのコマンドをエディタ自体に発行するためのコマンドモードである、モーダルユーザーインターフェイスを備えています。
編集モードとコマンドモードを使用するには、次のタスクを実行できます。
+ 編集モードに入るには、**ENTER** を押すか、セルを選択します。セルが編集モードの場合、セルの左側の余白は緑になります。
+ コマンドモードに入るには、**ESC** を押すか、セルの外側をクリックします。コマンドは通常、現在選択されているセルのみに適用され、すべてのセルには適用されないことに注意してください。エディタがコマンドモードの場合、セルの左側の余白は青くなります。
+ コマンドモードでは、キーボードショートカットとエディタの上にあるメニューを使用できますが、それぞれのセルにテキストを入力することはできません。
+ セルを選択するには、セルを選択します。
+ すべてのセルを選択するには、**Ctrl\$1A** (Windows) または **Cmd\$1A** (Mac) を押します。
## ノートブックエディタメニューでアクションを使用する
ノートブックエディタの上部にあるメニューのアイコンには、次のオプションがあります。
+ **保存** - ノートブックの現在の状態を保存します。
+ **下にセルを挿入** - 現在選択されているセルの下に新しい (空の) セルを追加します。
+ **選択したセルを切り取る** - 選択したセルを現在の場所から削除し、そのセルをメモリにコピーします。
+ **選択したセルをコピー** - 選択したセルをメモリにコピーします。
+ **セルを下に貼り付け** - コピーしたセルを現在のセルの下に貼り付けます。
+ **選択したセルを上に移動** - 現在のセルを上のセルの上に移動します。
+ **選択したセルを下に移動** - 現在のセルを下のセルの下に移動します。
+ **実行** - 現在の (選択済み) セルを実行します。出力は現在のセルのすぐ下に表示されます。
+ **すべて実行** - ノートブック内のすべてのセルを実行します。各セルの出力は、セルのすぐ下に表示されます。
+ **停止 (カーネルを中断)** - カーネルを中断して現在のノートブックを停止します。
+ **フォーマットオプション** - 次のいずれかのセルのフォーマットを選択します。
+ **コード** - Python コードに使用します (デフォルト)。
+ **マークダウン** - [GitHub スタイルのマークダウン](https://docs.github.com/en/get-started/writing-on-github)形式でテキストを入力する場合に使用します。マークダウンをレンダリングするには、セルを実行します。
+ **Raw NBConvert** - 未修正の形式でテキストを入力する場合に使用します。**[Raw NBConvert]** (未加工の NBConvert) とマークされたセルは、Jupyter [nbconvert](https://nbconvert.readthedocs.io/en/latest/usage.html) コマンドラインツールで HTML などの別の形式に変換できます。
+ **見出し** - セルの見出しレベルを変更する場合に使用します。
+ **コマンドパレット** - Jupyter Notebook コマンドとそのキーボードショートカットが含まれています。キーボードショートカットの詳細については、このドキュメント後半のセクションを参照してください。
+ **セッション** - このメニューのオプションを使用して、セッションの詳細を[表示](notebooks-spark-getting-started.md#notebooks-spark-getting-started-viewing-session-and-calculation-details)したり、[セッションパラメータを編集](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)したり、セッションを[終了](notebooks-spark-getting-started.md#notebooks-spark-getting-started-terminating-a-session)したりします。
## 生産性を高めるためにコマンドモードのキーボードショートカットを使用する
一般的なノートブックエディタコマンドモードのキーボードショートカットを次に示します。これらのショートカットは、**ESC** を押してからコマンドモードに入ると使用できます。エディタ後半のコマンドの一覧を表示するには、**ESC \$1 H** を押します。
****
| Key | Action |
| --- | --- |
| 1 - 6 | セルタイプをマークダウンに変更し、見出しレベルを入力した数値に設定する |
| a | 現在のセルの上にセルを作成する |
| b | 現在のセルの下にセルを作成する |
| c | 現在のセルをメモリにコピーする |
| d d | 現在のセルを削除する |
| h | キーボードショートカットのヘルプ画面を表示する |
| j | 1 つ下のセルに移動する |
| k | 1 つ上のセルに移動する |
| m | 現在のセル形式をマークダウンに変更する |
| r | 現在のセル形式を raw に変更する |
| s | ノートブックを保存する |
| v | メモリのコンテンツを現在のセルの下に貼り付ける |
| x | 選択した 1 つまたは複数のセルを切り取る |
| y | セルの形式をコードに変更する |
| z | [Undo] (元に戻す) |
| Ctrl\$1Enter | 現在のセルを実行してコマンドモードに入る |
| Shift\$1Enter、または Alt\$1Enter | 現在のセルを実行して出力の下に新しいセルを作成し、編集モードで新しいセルを入力する |
| Space | ページダウン |
| Shift\$1Space | ページアップ |
| Shift \$1 L | セル内の行番号の表示/非表示を切り替える |
## コマンドモードのショートカットをカスタマイズする
ノートブックエディタには、コマンドモードのキーボードショートカットをカスタマイズするオプションがあります。
**コマンドモードのショートカットを編集するには**
1. ノートブックエディタメニューから、**[Command palette]** (コマンドパレット) を選択します。
1. コマンドパレットから、**[Edit command mode keyboard shortcuts]** (コマンドモードのキーボードショートカット) コマンドを選択します。
1. **[Edit command mode shortcuts]** (編集コマンドモードのショートカット) インターフェイスを使用して、必要なコマンドをキーボードにマッピングまたは再マッピングします。
コマンドモードのショートカットの編集方法を確認するには、**[Edit command mode shortcuts]** (コマンドモードのショートカットの編集) 画面の一番下までスクロールします。
Athena for Apache Spark のマジックコマンドを使用する方法については、「[マジックコマンドを使用する](notebooks-spark-magics.md)」を参照してください。
**Topics**
+ [ノートブックセッションと計算を理解する](#notebooks-spark-sessions-and-calculations)
+ [コマンドモードと編集モードを切り替える](#notebooks-spark-command-mode-vs-edit-mode)
+ [ノートブックエディタメニューでアクションを使用する](#notebooks-spark-notebook-editor-menu)
+ [生産性を高めるためにコマンドモードのキーボードショートカットを使用する](#notebooks-spark-command-mode-keyboard-shortcuts)
+ [コマンドモードのショートカットをカスタマイズする](#notebooks-spark-editing-command-mode-shortcuts)
+ [マジックコマンドを使用する](notebooks-spark-magics.md)
# マジックコマンドを使用する
マジックコマンド、またはマジックは、ノートブックのセルで実行できる特別なコマンドです。例えば、`%env` はノートブックセッションの環境変数を表示します。Athena は IPython 6.0.3 のマジック関数をサポートしています。
このセクションでは、Athena for Apache Spark 用の主要なマジックコマンドをいくつか取り上げて説明します。
+ Athena のマジックコマンドのリストを表示するには、ノートブックのセルでコマンド **%lsmagic** を実行します。
+ Athena ノートブックでマジックを使ってグラフを作成する方法については、[マジックを使用してデータグラフを作成する](notebooks-spark-magics-graphs.md) を参照してください。
+ その他のマジックコマンドの詳細については、IPython ドキュメントの「[組み込みマジックコマンド](https://ipython.readthedocs.io/en/stable/interactive/magics.html)」を参照してください。
**注記**
現在、`%pip` コマンドを実行すると失敗します。これは既知の問題です。
**Topics**
+ [セルマジック](notebooks-spark-magics-cell-magics.md)
+ [ラインマジック](notebooks-spark-magics-line-magics.md)
+ [グラフマジック](notebooks-spark-magics-graphs.md)
# セルマジックを使用する
数行にまたがって書かれたマジックでは、その前に二重パーセント記号 (`%%`) が付き、セルマジック関数またはセルマジックと呼ばれます。
## %%sql
このセルマジックを使用することで、Spark SQL ステートメントで修飾する必要なく、直接 SQL ステートメントを実行することができます。また、このコマンドは、返されたデータフレームで `.show()` を黙示的に呼び出すことで出力も表示します。
![\[%%sql の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-1.png)
この `%%sql` コマンドは、自動的に列出力を 20 文字で切り捨てます。現在、この設定は構成されていません。この制限を回避するには、次の完全な構文を使用し、それに応じて `show` メソッドのパラメーターを変更してください。
```
spark.sql("""YOUR_SQL""").show(n=number, truncate=number, vertical=bool)
```
+ **n** `int` (オプション)。出力する行数。
+ **truncate** — `bool` または`int` (オプション) — `true` の場合、20 文字を超える文字列を切り捨てます。1 より大きい数値を設定すると、長い文字列を指定した長さに切り詰め、セルを右詰めにします。
+ **vertical** — `bool` (オプション)。`true` の場合、出力の行が縦方向に (列値ごとに 1 行) 表示されます。
# ラインマジックを使用する
1 行に記述されているマジックは、先頭にパーセント記号 (`%`) が付き、ラインマジック関数またはラインマジックと呼ばれます。
## %help
利用できるマジックコマンドの説明が表示されます。
![\[%help の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-2.png)
## %list\$1sessions
ノートブックに関連するセッションを一覧表示します。各セッションの情報には、セッション ID、セッションステータス、セッションが開始および終了した日時が含まれます。
![\[%list_sessions の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-3.png)
## %session\$1id
現在のセッション ID を取得します。
![\[session_id の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-4.png)
## %set\$1log\$1level
指定されたログレベルを使用するように、ロガーを設定またはリセットします。使用できる値は `DEBUG`、`ERROR`、`FATAL`、`INFO`、`WARN`、`WARNING` のいずれかです。値は大文字にする必要があり、一重引用符または二重引用符で囲むことはできません。
![\[%set_log_level の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-5.png)
## %status
現在のセッションについて説明します。出力には、セッション ID、セッション状態、ワークグループ名、PySpark エンジンバージョン、セッション開始時間が含まれます。このマジックコマンドは、セッションの詳細を取得するにあたりアクティブなセッションを必要とします。
ステータスに表示される可能性のある値は、以下のとおりです。
**CREATING** — セッションが開始されている状態です (リソースの取得を含む)。
**CREATED** — セッションが開始されました。
**IDLE** — セッションは計算を受け入れることができる状態にあります。
**BUSY** — セッションは別のタスクを処理中で、計算を受け入れることができません。
**TERMINATING** – セッションはシャットダウン処理の途中です。
**TERMINATED** – セッションとそのリソースはもう実行されていません。
**DEGRADED** — セッションには正常なコーディネーターがありません。
**FAILED** — 障害が発生したため、セッションとそのリソースは実行されなくなりました。
![\[%status の使用。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-6.png)
# マジックを使用してデータグラフを作成する
このセクションに記載されているラインマジックは、特定タイプのデータのレンダリングや、グラフライブラリとの関連付けに特化したものです。
## %table
`%table` マジックコマンドを使用して、データフレームデータをテーブル形式で表示できます。
次の例では、2 列 3 行のデータが含まれるデータフレームを作成し、データを表形式で表示しています。
![\[%table マジックコマンドを使用します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-graphs-1.png)
## %matplot
[Matplotlib](https://matplotlib.org/) は Python で静的な視覚化、アニメーション化による視覚化、インタラクティブな視覚化を作成するための包括的なライブラリです。matplotlib ライブラリをノートブックセルにインポートした後、`%matplot` マジックコマンドを使用してグラフを作成することができます。
次の例では、matplotlib ライブラリをインポートして X Y 座標セットを作成し、その後 `%matplot` マジックコマンドを使用して点グラフを作成しています。
```
import matplotlib.pyplot as plt
x=[3,4,5,6,7,8,9,10,11,12]
y= [9,16,25,36,49,64,81,100,121,144]
plt.plot(x,y)
%matplot plt
```
![\[%matplot マジックコマンドを使用します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-graphs-2.png)
### matplotlib ライブラリと seaborn ライブラリを併用する
[Seaborn](https://seaborn.pydata.org/tutorial/introduction) は Python で統計グラフィックを作成するためのライブラリです。matplotlib 上に構築され、[pandas](https://pandas.pydata.org/) (Python データ分析) データ構造と密接に統合されます。`%matplot` マジックコマンドを使用して、seaborn データをレンダリングすることもできます。
次の例では、matplotlib ライブラリと seaborn ライブラリの両方を使用して、単純な棒グラフを作成しています。
```
import matplotlib.pyplot as plt
import seaborn as sns
x = ['A', 'B', 'C']
y = [1, 5, 3]
sns.barplot(x, y)
%matplot plt
```
![\[%matplot を使用して seaborn データをレンダリングします。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-graphs-3.png)
## %plotly
[Plotly](https://plotly.com/python/) は Python 用のオープンソースのグラフライブラリであり、インタラクティブなグラフを作成するために使用できます。`%ploty` マジックコマンドを使用して、ploty データをレンダリングすることができます。
次の例では、株価データに [StringIO](https://docs.python.org/3.13/library/io.html#io.StringIO)、plotly、pandas ライブラリを使用して、2015 年 2 月と 3 月の株式活動グラフを作成しています。
```
from io import StringIO
csvString = """
Date,AAPL.Open,AAPL.High,AAPL.Low,AAPL.Close,AAPL.Volume,AAPL.Adjusted,dn,mavg,up,direction
2015-02-17,127.489998,128.880005,126.919998,127.830002,63152400,122.905254,106.7410523,117.9276669,129.1142814,Increasing
2015-02-18,127.629997,128.779999,127.449997,128.720001,44891700,123.760965,107.842423,118.9403335,130.0382439,Increasing
2015-02-19,128.479996,129.029999,128.330002,128.449997,37362400,123.501363,108.8942449,119.8891668,130.8840887,Decreasing
2015-02-20,128.619995,129.5,128.050003,129.5,48948400,124.510914,109.7854494,120.7635001,131.7415509,Increasing
2015-02-23,130.020004,133,129.660004,133,70974100,127.876074,110.3725162,121.7201668,133.0678174,Increasing
2015-02-24,132.940002,133.600006,131.169998,132.169998,69228100,127.078049,111.0948689,122.6648335,134.2347981,Decreasing
2015-02-25,131.559998,131.600006,128.149994,128.789993,74711700,123.828261,113.2119183,123.6296667,134.0474151,Decreasing
2015-02-26,128.789993,130.869995,126.610001,130.419998,91287500,125.395469,114.1652991,124.2823333,134.3993674,Increasing
2015-02-27,130,130.570007,128.240005,128.460007,62014800,123.510987,114.9668484,124.8426669,134.7184854,Decreasing
2015-03-02,129.25,130.279999,128.300003,129.089996,48096700,124.116706,115.8770904,125.4036668,134.9302432,Decreasing
2015-03-03,128.960007,129.520004,128.089996,129.360001,37816300,124.376308,116.9535132,125.9551669,134.9568205,Increasing
2015-03-04,129.100006,129.559998,128.320007,128.539993,31666300,123.587892,118.0874253,126.4730002,134.8585751,Decreasing
2015-03-05,128.580002,128.75,125.760002,126.410004,56517100,121.539962,119.1048311,126.848667,134.5925029,Decreasing
2015-03-06,128.399994,129.369995,126.260002,126.599998,72842100,121.722637,120.190797,127.2288335,134.26687,Decreasing
2015-03-09,127.959999,129.570007,125.059998,127.139999,88528500,122.241834,121.6289771,127.631167,133.6333568,Decreasing
2015-03-10,126.410004,127.220001,123.800003,124.510002,68856600,119.71316,123.1164763,127.9235004,132.7305246,Decreasing
"""
csvStringIO = StringIO(csvString)
from io import StringIO
import plotly.graph_objects as go
import pandas as pd
from datetime import datetime
df = pd.read_csv(csvStringIO)
fig = go.Figure(data=[go.Candlestick(x=df['Date'],
open=df['AAPL.Open'],
high=df['AAPL.High'],
low=df['AAPL.Low'],
close=df['AAPL.Close'])])
%plotly fig
```
![\[%ploty マジックコマンドを使用します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-magics-graphs-4.png)
# Athena for Spark で Hive 以外のテーブル形式を使用する
**注記**
このページでは、リリースバージョン Pyspark エンジンバージョン 3 での Python ライブラリの使用について説明します。サポートされているオープンテーブル形式のバージョンについては、「[Amazon EMR 7.12](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-7120-release.html)」を参照してください。
Athena for Spark でセッションやノートブックを使用する場合は、Apache Hive テーブルだけでなく Linux Foundation Delta Lake、Apache Hudi、Apache Iceberg の各テーブルも使用できます。
## 考慮事項と制限事項
Apache Hive 以外のテーブル形式を Athena for Spark で使用する場合は、次の点を考慮してください。
+ 各ノートブックでサポートされるテーブル形式は、Apache Hive 以外は 1 つだけです。Athena for Spark で複数のテーブル形式を使用する場合は、各テーブル形式に対して個別のノートブックを作成してください。Athena for Spark でノートブックを作成するための情報については、「[ステップ 7: 独自のノートブックを作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)」を参照してください。
+ Delta Lake、Hudi、および Iceberg テーブル形式は、AWS Glue をメタストアとして使用した Athena for Spark でテスト検証済みです。他のメタストアも使用できる可能性はありますが、その使用法は現在サポートされていません。
+ その他のテーブル形式を使用するには、Athena コンソールとこのドキュメントの説明にあるように、デフォルトの `spark_catalog` プロパティを上書きしてください。これらの Hive 以外のカタログは、自身のテーブル形式に加えて Hive テーブルも読み取れます。
## テーブルのバージョン
次の表は、Amazon Athena for Apache Spark でサポートされている Hive 以外のテーブルバージョンを示しています。
****
| テーブル形式 | サポートされる のバージョン |
| --- | --- |
| Apache Iceberg | 1.2.1 |
| Apache Hudi | 0.13 |
| Linux Foundation Delta Lake | 2.0.2 |
Athena for Spark では、これらのテーブル形式 `.jar` ファイルとその依存関係は Spark ドライバーとエグゼキューターのクラスパスに読み込まれます。
Amazon Athena ノートブックで Spark SQL を使用して Iceberg、Hudi、および Delta Lake テーブル形式を操作する方法については AWS Big Data Blog 記事「[Use Amazon Athena with Spark SQL for your open-source transactional table formats](https://aws.amazon.com/blogs/big-data/use-amazon-athena-with-spark-sql-for-your-open-source-transactional-table-formats/)」を参照してください。
**Topics**
+ [考慮事項と制限事項](#notebooks-spark-table-formats-considerations-and-limitations)
+ [テーブルのバージョン](#notebooks-spark-table-formats-versions)
+ [Iceberg](notebooks-spark-table-formats-apache-iceberg.md)
+ [Hudi](notebooks-spark-table-formats-apache-hudi.md)
+ [Delta Lake](notebooks-spark-table-formats-linux-foundation-delta-lake.md)
# Athena for Spark で Apache Iceberg テーブルを使用する
[Apache Iceberg](https://iceberg.apache.org/) は、Amazon Simple Storage Service (Amazon S3) の大規模データセット用のオープンテーブル形式です。大きなテーブルに対する高速のクエリパフォーマンス、アトミックコミット、同時書き込み、および SQL 互換テーブルの進化を提供します。
Athena for Spark で Apache Iceberg テーブルを使用するには、次の Spark プロパティを設定します。これらのプロパティは、Athena for Spark コンソールでテーブル形式として Apache Iceberg を選択したときに、デフォルトで自動的に設定されます。手順については、「[ステップ 4: セッションの詳細を編集する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)」または「[ステップ 7: 独自のノートブックを作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)」を参照してください。
```
"spark.sql.catalog.spark_catalog": "org.apache.iceberg.spark.SparkSessionCatalog",
"spark.sql.catalog.spark_catalog.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
"spark.sql.catalog.spark_catalog.io-impl": "org.apache.iceberg.aws.s3.S3FileIO",
"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
```
以下の手順では、Athena for Spark ノートブックで Apache Iceberg テーブルを使用する方法を示しています。ノートブックの新しいセルで各ステップを実行します。
**Athena for Spark で Apache Iceberg テーブルを使用する方法**
1. ノートブックで使用する定数を定義します。
```
DB_NAME = "NEW_DB_NAME"
TABLE_NAME = "NEW_TABLE_NAME"
TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
```
1. Apache Spark [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) を作成します。
```
columns = ["language","users_count"]
data = [("Golang", 3000)]
df = spark.createDataFrame(data, columns)
```
1. データベースを作成します。
```
spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
```
1. 空の Apache Iceberg テーブルを作成します。
```
spark.sql("""
CREATE TABLE {}.{} (
language string,
users_count int
) USING ICEBERG
""".format(DB_NAME, TABLE_NAME))
```
1. テーブルにデータ行を挿入します。
```
spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME, TABLE_NAME))
```
1. 新しいテーブルをクエリできることを確認します。
```
spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
```
Spark DataFrames と Iceberg テーブルの使用に関する詳細と例については、Apache Iceberg ドキュメントの「[Spark クエリ](https://iceberg.apache.org/docs/latest/spark-queries/)」を参照してください。
# Athena for Spark で Apache Hudi テーブルを使用する
[https://hudi.apache.org/](https://hudi.apache.org/) は、増分データ処理を簡素化するオープンソースのデータ管理フレームワークです。レコードレベルの挿入、更新、upsert、および削除アクションがより正確に処理されるため、オーバーヘッドが減少します。
Athena for Spark で Apache Hudi テーブルを使用するには、次の Spark プロパティを設定します。これらのプロパティは、Athena for Spark コンソールでテーブル形式として Apache Hudi を選択したときに、デフォルトで自動的に設定されます。手順については、「[ステップ 4: セッションの詳細を編集する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)」または「[ステップ 7: 独自のノートブックを作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)」を参照してください。
```
"spark.sql.catalog.spark_catalog": "org.apache.spark.sql.hudi.catalog.HoodieCatalog",
"spark.serializer": "org.apache.spark.serializer.KryoSerializer",
"spark.sql.extensions": "org.apache.spark.sql.hudi.HoodieSparkSessionExtension"
```
以下の手順では、Athena for Spark ノートブックで Apache Hudi テーブルを使用する方法を示しています。ノートブックの新しいセルで各ステップを実行します。
**Athena for Spark で Apache Hudi テーブルを使用する方法**
1. ノートブックで使用する定数を定義します。
```
DB_NAME = "NEW_DB_NAME"
TABLE_NAME = "NEW_TABLE_NAME"
TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
```
1. Apache Spark [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) を作成します。
```
columns = ["language","users_count"]
data = [("Golang", 3000)]
df = spark.createDataFrame(data, columns)
```
1. データベースを作成します。
```
spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
```
1. 空の Apache Hudi テーブルを作成します。
```
spark.sql("""
CREATE TABLE {}.{} (
language string,
users_count int
) USING HUDI
TBLPROPERTIES (
primaryKey = 'language',
type = 'mor'
);
""".format(DB_NAME, TABLE_NAME))
```
1. テーブルにデータ行を挿入します。
```
spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME,TABLE_NAME))
```
1. 新しいテーブルをクエリできることを確認します。
```
spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
```
# Athena for Spark で Linux Foundation Delta Lake テーブルを使用する
[Linux Foundation Delta Lake](https://delta.io/) は、ビッグデータ分析に使用できるテーブル形式です。Athena for Spark を使用して、Amazon S3 に保存されている Delta Lake テーブルを直接読み取れます。
Athena for Spark で Delta Lake テーブルを使用するには、次の Spark プロパティを設定します。これらのプロパティは、Athena for Spark コンソールでテーブル形式として Delta Lake を選択したときに、デフォルトで自動的に設定されます。手順については、「[ステップ 4: セッションの詳細を編集する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)」または「[ステップ 7: 独自のノートブックを作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)」を参照してください。
```
"spark.sql.catalog.spark_catalog" : "org.apache.spark.sql.delta.catalog.DeltaCatalog",
"spark.sql.extensions" : "io.delta.sql.DeltaSparkSessionExtension"
```
以下の手順では、Athena for Spark ノートブックで Delta Lake テーブルを使用する方法を示しています。ノートブックの新しいセルで各ステップを実行します。
**Athena の Spark で Delta Lake テーブルを使用する方法**
1. ノートブックで使用する定数を定義します。
```
DB_NAME = "NEW_DB_NAME"
TABLE_NAME = "NEW_TABLE_NAME"
TABLE_S3_LOCATION = "s3://amzn-s3-demo-bucket"
```
1. Apache Spark [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) を作成します。
```
columns = ["language","users_count"]
data = [("Golang", 3000)]
df = spark.createDataFrame(data, columns)
```
1. データベースを作成します。
```
spark.sql("CREATE DATABASE {} LOCATION '{}'".format(DB_NAME, TABLE_S3_LOCATION))
```
1. 空の Delta Lake テーブルを作成します。
```
spark.sql("""
CREATE TABLE {}.{} (
language string,
users_count int
) USING DELTA
""".format(DB_NAME, TABLE_NAME))
```
1. テーブルにデータ行を挿入します。
```
spark.sql("""INSERT INTO {}.{} VALUES ('Golang', 3000)""".format(DB_NAME, TABLE_NAME))
```
1. 新しいテーブルをクエリできることを確認します。
```
spark.sql("SELECT * FROM {}.{}".format(DB_NAME, TABLE_NAME)).show()
```
# Athena for Spark で Python ライブラリを使用する
**注記**
このページでは、リリースバージョン Pyspark エンジンバージョン 3 での Python ライブラリの使用について説明します。リリースバージョン Apache Spark バージョン 3.5 は、[Amazon EMR 7.12](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-7120-release.html) に基づいています。このバージョンに含まれるライブラリについては、「EMR 7.12」を参照してください。
このページでは、Amazon Athena for Apache Spark で使用されるランタイム、ライブラリ、パッケージで使用される用語とライフサイクル管理について説明します。
## 定義
+ **[Amazon Athena for Apache Spark]** は、オープンソースの Apache Spark をカスタマイズしたバージョンです。現在のバージョンを確認するには、ノートブックのセルで `print(f'{spark.version}')` コマンドを実行します。
+ **[Athena runtime]** (Athena ランタイム) とは、コードが実行される環境のことです。この環境には Python インタープリターと PySpark ライブラリが含まれています。
+ **[External library or package]** (外部ライブラリまたはパッケージ) は、Athena ランタイムには含まれていない Java、Scala の JAR または Python ライブラリですが、Athena for Spark のジョブに含めることができます。外部パッケージは、Amazon が作成することも、ユーザー自身で作成することもできます。
+ **[Convenience package]** (コンビニエンスパッケージ) とは、Athena が選択した外部パッケージのコレクションで、Spark アプリケーションに含めることを選択できます。
+ **[bundle]** (バンドル) は Athena ランタイムと便利なパッケージを組み合わせたものです。
+ **[User library]** (ユーザーライブラリ) は、Athena for Spark ジョブに明示的に追加する外部ライブラリまたはパッケージです。
+ ユーザーライブラリとは、コンビニエンスパッケージの一部ではない外部パッケージです。ユーザーライブラリは、いくつかの `.py` ファイルを作成して圧縮し、`.zip` ファイルをアプリケーションに追加する場合と同様に、ロードとインストールが必要です。
+ **[Athena for Spark application]** (Athena for Spark アプリケーション) とは、ユーザーが Athena for Spark に送信するジョブまたはクエリです。
## ライフサイクル管理
以下のセクションでは、Athena for Spark で使用されるランタイムパッケージとコンビニエンスパッケージに関するバージョニングポリシーと非推奨ポリシーについて説明します。
### ランタイムのバージョニングと廃止予定
Athena ランタイムの主なコンポーネントは、Python インタープリターです。Python は進化が続いている言語であるため、新しいバージョンが定期的にリリースされ、古いバージョンのサポートは停止されます。Athena では、廃止予定の Python インタープリターバージョンでプログラムを実行することはお勧めしていません。また、可能な限り最新の Athena ランタイムを使用することを強くお勧めします。
Athena ランタイムの廃止予定のスケジュールは次のとおりです。
1. Athena が新しいランタイムを提供した後も、Athena は以前のランタイムを 6 か月間サポートし続けます。その間、Athena は以前のランタイムにセキュリティパッチとアップデートを適用します。
1. 6 か月後、Athena は以前のランタイムのサポートを終了します。Athena は、以前のランタイムにセキュリティパッチやその他の更新を適用しなくなります。以前のランタイムを使用している Spark アプリケーションは、テクニカルサポートの対象ではなくなります。
1. 12 か月後、以前のランタイムを使用するワークグループでは Spark アプリケーションを更新または編集することはできなくなります。この期間が終了する前に、Spark アプリケーションを更新することをお勧めします。期間終了後も既存のノートブックを実行できますが、以前のランタイムをまだ使用しているノートブックにはその旨の警告がログ記録されます。
1. 18 か月が経過すると、以前のランタイムを使用してワークグループでジョブを実行できなくなります。
### コンビニエンスパッケージのバージョニングと廃止予定
コンビニエンスパッケージの内容は時間の経過とともに変化します。Athena では、これらのコンビニエンスパッケージを追加、削除、またはアップグレードする場合があります。
Athena はコンビニエンスパッケージについて以下のガイドラインを採用しています。
+ コンビニエンスパッケージには、1、2、3 などのシンプルなバージョニングスキームがあります。
+ 各コンビニエンスパッケージのバージョンには、特定のバージョンの外部パッケージが含まれています。Athena がコンビニエンスパッケージを作成しても、そのコンビニエンスパッケージの外部パッケージセットとそれに対応するバージョンは変更されません。
+ Athena は、新しい外部パッケージを含めたり、外部パッケージを削除したり、1 つ以上の外部パッケージのバージョンをアップグレードしたりする場合に、新しいコンビニエンスパッケージバージョンを作成します。
Athena は、そのパッケージが使用する Athena ランタイムを廃止すると便利であるパッケージを廃止します。Athena は、サポートするバンドルの数を制限するために、パッケージをすぐに非推奨にすることができます。
コンビニエンスパッケージの非推奨スケジュールは、Athena ランタイムの非推奨スケジュールに従います。
# プリインストールされている Python ライブラリのリスト
プリインストールされている Python ライブラリには以下が含まれます。
```
boto3==1.24.31
botocore==1.27.31
certifi==2022.6.15
charset-normalizer==2.1.0
cycler==0.11.0
cython==0.29.30
docutils==0.19
fonttools==4.34.4
idna==3.3
jmespath==1.0.1
joblib==1.1.0
kiwisolver==1.4.4
matplotlib==3.5.2
mpmath==1.2.1
numpy==1.23.1
packaging==21.3
pandas==1.4.3
patsy==0.5.2
pillow==9.2.0
plotly==5.9.0
pmdarima==1.8.5
pyathena==2.9.6
pyparsing==3.0.9
python-dateutil==2.8.2
pytz==2022.1
requests==2.28.1
s3transfer==0.6.0
scikit-learn==1.1.1
scipy==1.8.1
seaborn==0.11.2
six==1.16.0
statsmodels==0.13.2
sympy==1.10.1
tenacity==8.0.1
threadpoolctl==3.1.0
urllib3==1.26.10
pyarrow==9.0.0
```
## 注意事項
+ MLlib (Apache Spark 機械学習ライブラリ) および `pyspark.ml` パッケージはサポートされていません。
+ 現在、Athena for Spark セッションで `pip install` はサポートされていません。
Amazon Athena for Apache Spark への Python ライブラリのインポートについては、「[Athena for Spark にファイルと Python ライブラリをインポートする](notebooks-import-files-libraries.md)」を参照してください。
# Athena for Spark にファイルと Python ライブラリをインポートする
このドキュメントでは、Amazon Athena for Apache Spark にファイルおよび Python ライブラリをインポートする方法の例を紹介します。
## 考慮事項と制約事項
+ **Python のバージョン** — 現在、Athena for Spark では Python バージョン 3.9.16 が使用されています。Python パッケージは Python のマイナーバージョンにセンシティブであることに注意してください。
+ **Athena for Spark のアーキテクチャ** — Athena for Spark は ARM64 アーキテクチャ上で Amazon Linux 2 を使用しています。Python ライブラリの中には、このアーキテクチャ用のバイナリを配布していないものがあることに注意してください。
+ **バイナリ共有オブジェクト (SO)** — SparkContext [addPyFile](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.SparkContext.addPyFile.html) メソッドは、バイナリ共有オブジェクトを検出しないため、Athena for Spark では共有オブジェクトに依存する Python パッケージを追加するためには使用できません。
+ **Resilient Distributed Dataset (RDD)** — [RDD](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.RDD.html) はサポートされていません。
+ **Dataframe.foreach** — PySpark の [DataFrame.foreach](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/api/pyspark.sql.DataFrame.foreach.html) メソッドはサポートされていません。
## 例
例では次の規則を使用しています。
+ Amazon S3 のプレースホルダーの場所 `s3://amzn-s3-demo-bucket`。これをユーザーの S3 バケットの場所に置き換えます。
+ Unix シェルから実行されるすべてのコードブロックは *directory\$1name* `$` として表示されます。例えば、ディレクトリ `/tmp` 内のコマンド `ls` とその出力は次のように表示されます。
```
/tmp $ ls
```
**出力**
```
file1 file2
```
## 計算に使用するテキストファイルをインポートする
このセクションの例では、Athena for Spark 内のノートブックで計算に使用するテキストファイルをインポートする方法を示します。
### ファイルをローカル一時ディレクトリに書き込んでからノートブックに追加する
次の例は、ローカルの一時ディレクトリにファイルを書き込み、ノートブックに追加してテストする方法です。
```
import os
from pyspark import SparkFiles
tempdir = '/tmp/'
path = os.path.join(tempdir, "test.txt")
with open(path, "w") as testFile:
_ = testFile.write("5")
sc.addFile(path)
def func(iterator):
with open(SparkFiles.get("test.txt")) as testFile:
fileVal = int(testFile.readline())
return [x * fileVal for x in iterator]
#Test the file
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
udf_with_import = udf(func)
df = spark.createDataFrame([(1, "a"), (2, "b")])
df.withColumn("col", udf_with_import(col('_2'))).show()
```
**出力**
```
Calculation completed.
+---+---+-------+
| _1| _2| col|
+---+---+-------+
| 1| a|[aaaaa]|
| 2| b|[bbbbb]|
+---+---+-------+
```
### Amazon S3 からファイルをインポートする
次の例は、Amazon S3 からファイルをノートブックにインポートしてテストする方法です。
**Amazon S3 からノートブックにファイルをインポートするには**
1. 値 `5` を含む 1 行を持つ、`test.txt` という名前のファイルを作成します。
1. Amazon S3 のバケットにファイルを追加します。この例ではロケーション `s3://amzn-s3-demo-bucket` を使用しています。
1. 次のコードを使用してファイルをノートブックにインポートし、ファイルをテストします。
```
from pyspark import SparkFiles
sc.addFile('s3://amzn-s3-demo-bucket/test.txt')
def func(iterator):
with open(SparkFiles.get("test.txt")) as testFile:
fileVal = int(testFile.readline())
return [x * fileVal for x in iterator]
#Test the file
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
udf_with_import = udf(func)
df = spark.createDataFrame([(1, "a"), (2, "b")])
df.withColumn("col", udf_with_import(col('_2'))).show()
```
**出力**
```
Calculation completed.
+---+---+-------+
| _1| _2| col|
+---+---+-------+
| 1| a|[aaaaa]|
| 2| b|[bbbbb]|
+---+---+-------+
```
## Python ファイルを追加する
このセクションの例では、Athena の Spark ノートブックに Python ファイルとライブラリを追加する方法を示します。
### Python ファイルを追加し UDF を登録する
次の例は、Amazon S3 から Python ファイルをノートブックに追加し、UDF を登録する方法です。
**Python ファイルをノートブックに追加して UDF を登録するには**
1. 独自の Amazon S3 のロケーションを使用して、次の内容のファイル `s3://amzn-s3-demo-bucket/file1.py` を作成します。
```
def xyz(input):
return 'xyz - udf ' + str(input);
```
1. 同じ S3 のロケーションに、次の内容のファイル `s3://amzn-s3-demo-bucket/file2.py` を作成します。
```
from file1 import xyz
def uvw(input):
return 'uvw -> ' + xyz(input);
```
1. Athena for Spark ノートブックで、次のコマンドを実行します。
```
sc.addPyFile('s3://amzn-s3-demo-bucket/file1.py')
sc.addPyFile('s3://amzn-s3-demo-bucket/file2.py')
def func(iterator):
from file2 import uvw
return [uvw(x) for x in iterator]
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
udf_with_import = udf(func)
df = spark.createDataFrame([(1, "a"), (2, "b")])
df.withColumn("col", udf_with_import(col('_2'))).show(10)
```
**出力**
```
Calculation started (calculation_id=1ec09e01-3dec-a096-00ea-57289cdb8ce7) in (session=c8c09e00-6f20-41e5-98bd-4024913d6cee). Checking calculation status...
Calculation completed.
+---+---+--------------------+
| _1| _2| col|
+---+---+--------------------+
| 1 | a|[uvw -> xyz - ud... |
| 2 | b|[uvw -> xyz - ud... |
+---+---+--------------------+
```
### Python .zip ファイルをインポートする
Python `addPyFile` と `import` のメソッドを使用して、Python .zip ファイルをノートブックにインポートできます。
**注記**
Athena Spark にインポートする `.zip` ファイルには、Python パッケージのみを含める必要があります。例えば、C ベースのファイルが含まれるパッケージを含めることはサポートされていません。
**Python `.zip` ファイルをノートブックにインポートするには**
1. ローカルコンピュータの `\tmp` などのデスクトップディレクトリに、`moduletest` というディレクトリを作成します。
1. `moduletest` ディレクトリで、次の内容で `hello.py` というファイルを作成します。
```
def hi(input):
return 'hi ' + str(input);
```
1. 同じディレクトリに、`__init__.py` という名前の空のファイルを追加します。
ディレクトリの内容を一覧すると、以下のようになります。
```
/tmp $ ls moduletest
__init__.py hello.py
```
1. `zip` コマンドを使用して、2 つのモジュールファイルを `moduletest.zip` というファイルに格納します。
```
moduletest $ zip -r9 ../moduletest.zip *
```
1. `.zip` のファイルを Amazon S3 のバケットにアップロードしてください。
1. 次のコードを使用して、Python`.zip` ファイルをノートブックにインポートします。
```
sc.addPyFile('s3://amzn-s3-demo-bucket/moduletest.zip')
from moduletest.hello import hi
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
hi_udf = udf(hi)
df = spark.createDataFrame([(1, "a"), (2, "b")])
df.withColumn("col", hi_udf(col('_2'))).show()
```
**出力**
```
Calculation started (calculation_id=6ec09e8c-6fe0-4547-5f1b-6b01adb2242c) in (session=dcc09e8c-3f80-9cdc-bfc5-7effa1686b76). Checking calculation status...
Calculation completed.
+---+---+----+
| _1| _2| col|
+---+---+----+
| 1| a|hi a|
| 2| b|hi b|
+---+---+----+
```
### Python のライブラリの 2 つのバージョンを別々のモジュールとしてインポートする
次のコード例は、Amazon S3 内の場所から 2 つの異なるバージョンの Python ライブラリを、2 つの独立したモジュールとして追加およびインポートする方法を示しています。このコードは、S3 から各ライブラリファイルを追加してインポートし、ライブラリのバージョンを出力してインポートを確認するものです。
```
sc.addPyFile('s3://amzn-s3-demo-bucket/python-third-party-libs-test/simplejson_v3_15.zip')
sc.addPyFile('s3://amzn-s3-demo-bucket/python-third-party-libs-test/simplejson_v3_17_6.zip')
import simplejson_v3_15
print(simplejson_v3_15.__version__)
```
**出力**
```
3.15.0
```
```
import simplejson_v3_17_6
print(simplejson_v3_17_6.__version__)
```
**出力**
```
3.17.6
```
### PyPI から Python .zip ファイルをインポートする
この例では、`pip` コマンドを使用して、[Python Package インデックス (PyPI)](https://pypi.org/) から [bpabel/piglatin](https://github.com/bpabel/piglatin) プロジェクトの Python .zip ファイルをダウンロードしています。
**PyPI から Python .zip ファイルをインポートするには**
1. ローカルデスクトップで、次のコマンドを使用して `testpiglatin` というディレクトリを作成し、仮想環境を作成します。
```
/tmp $ mkdir testpiglatin
/tmp $ cd testpiglatin
testpiglatin $ virtualenv .
```
**出力**
```
created virtual environment CPython3.9.6.final.0-64 in 410ms
creator CPython3Posix(dest=/private/tmp/testpiglatin, clear=False, no_vcs_ignore=False, global=False)
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/Users/user1/Library/Application Support/virtualenv)
added seed packages: pip==22.0.4, setuptools==62.1.0, wheel==0.37.1
activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
```
1. プロジェクトを格納するために、`unpacked` という名前のサブディレクトリを作成します。
```
testpiglatin $ mkdir unpacked
```
1. `pip` コマンドを使用して、プロジェクトを `unpacked` ディレクトリにインストールします。
```
testpiglatin $ bin/pip install -t $PWD/unpacked piglatin
```
**出力**
```
Collecting piglatin
Using cached piglatin-1.0.6-py2.py3-none-any.whl (3.1 kB)
Installing collected packages: piglatin
Successfully installed piglatin-1.0.6
```
1. ディレクトリの内容を確認する。
```
testpiglatin $ ls
```
**出力**
```
bin lib pyvenv.cfg unpacked
```
1. `unpacked` のディレクトリに移動して、内容を表示します。
```
testpiglatin $ cd unpacked
unpacked $ ls
```
**出力**
```
piglatin piglatin-1.0.6.dist-info
```
1. `zip` コマンドを使用して、piglatin プロジェクトの内容を、`library.zip` という名前のファイルに格納します。
```
unpacked $ zip -r9 ../library.zip *
```
**出力**
```
adding: piglatin/ (stored 0%)
adding: piglatin/__init__.py (deflated 56%)
adding: piglatin/__pycache__/ (stored 0%)
adding: piglatin/__pycache__/__init__.cpython-39.pyc (deflated 31%)
adding: piglatin-1.0.6.dist-info/ (stored 0%)
adding: piglatin-1.0.6.dist-info/RECORD (deflated 39%)
adding: piglatin-1.0.6.dist-info/LICENSE (deflated 41%)
adding: piglatin-1.0.6.dist-info/WHEEL (deflated 15%)
adding: piglatin-1.0.6.dist-info/REQUESTED (stored 0%)
adding: piglatin-1.0.6.dist-info/INSTALLER (stored 0%)
adding: piglatin-1.0.6.dist-info/METADATA (deflated 48%)
```
1. (オプション) 次のコマンドを使用して、インポートをローカルでテストします。
1. Python パスを `library.zip` ファイルの場所に設定し、Python を起動します。
```
/home $ PYTHONPATH=/tmp/testpiglatin/library.zip
/home $ python3
```
**出力**
```
Python 3.9.6 (default, Jun 29 2021, 06:20:32)
[Clang 12.0.0 (clang-1200.0.32.29)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
```
1. ライブラリをインポートし、テストコマンドを実行します。
```
>>> import piglatin
>>> piglatin.translate('hello')
```
**出力**
```
'ello-hay'
```
1. 次のようなコマンドを使用して Amazon S3 から `.zip` ファイルを追加し、Athena のノートブックにインポートしてテストします。
```
sc.addPyFile('s3://amzn-s3-demo-bucket/library.zip')
import piglatin
piglatin.translate('hello')
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
hi_udf = udf(piglatin.translate)
df = spark.createDataFrame([(1, "hello"), (2, "world")])
df.withColumn("col", hi_udf(col('_2'))).show()
```
**出力**
```
Calculation started (calculation_id=e2c0a06e-f45d-d96d-9b8c-ff6a58b2a525) in (session=82c0a06d-d60e-8c66-5d12-23bcd55a6457). Checking calculation status...
Calculation completed.
+---+-----+--------+
| _1| _2| col|
+---+-----+--------+
| 1|hello|ello-hay|
| 2|world|orld-way|
+---+-----+--------+
```
### 依存関係のある PyPI から Python .zip ファイルをインポートする
この例では、マークダウン内のテキストを [Gemini](https://gemini.circumlunar.space/) テキスト形式に変換する [md2gemini](https://github.com/makeworld-the-better-one/md2gemini) パッケージを PyPI からインポートします。このパッケージには次の[依存関係](https://libraries.io/pypi/md2gemini)があります。
```
cjkwrap
mistune
wcwidth
```
**依存関係のある Python .zip ファイルをインポートするには**
1. ローカルコンピュータで、次のコマンドを使用して `testmd2gemini` というディレクトリを作成し、仮想環境を作成します。
```
/tmp $ mkdir testmd2gemini
/tmp $ cd testmd2gemini
testmd2gemini$ virtualenv .
```
1. プロジェクトを格納するために、`unpacked` という名前のサブディレクトリを作成します。
```
testmd2gemini $ mkdir unpacked
```
1. `pip` コマンドを使用して、プロジェクトを `unpacked` ディレクトリにインストールします。
```
/testmd2gemini $ bin/pip install -t $PWD/unpacked md2gemini
```
**出力**
```
Collecting md2gemini
Downloading md2gemini-1.9.0-py3-none-any.whl (31 kB)
Collecting wcwidth
Downloading wcwidth-0.2.5-py2.py3-none-any.whl (30 kB)
Collecting mistune<3,>=2.0.0
Downloading mistune-2.0.2-py2.py3-none-any.whl (24 kB)
Collecting cjkwrap
Downloading CJKwrap-2.2-py2.py3-none-any.whl (4.3 kB)
Installing collected packages: wcwidth, mistune, cjkwrap, md2gemini
Successfully installed cjkwrap-2.2 md2gemini-1.9.0 mistune-2.0.2 wcwidth-0.2.5
...
```
1. `unpacked` のディレクトリに移動して、内容を確認します。
```
testmd2gemini $ cd unpacked
unpacked $ ls -lah
```
**出力**
```
total 16
drwxr-xr-x 13 user1 wheel 416B Jun 7 18:43 .
drwxr-xr-x 8 user1 wheel 256B Jun 7 18:44 ..
drwxr-xr-x 9 user1 staff 288B Jun 7 18:43 CJKwrap-2.2.dist-info
drwxr-xr-x 3 user1 staff 96B Jun 7 18:43 __pycache__
drwxr-xr-x 3 user1 staff 96B Jun 7 18:43 bin
-rw-r--r-- 1 user1 staff 5.0K Jun 7 18:43 cjkwrap.py
drwxr-xr-x 7 user1 staff 224B Jun 7 18:43 md2gemini
drwxr-xr-x 10 user1 staff 320B Jun 7 18:43 md2gemini-1.9.0.dist-info
drwxr-xr-x 12 user1 staff 384B Jun 7 18:43 mistune
drwxr-xr-x 8 user1 staff 256B Jun 7 18:43 mistune-2.0.2.dist-info
drwxr-xr-x 16 user1 staff 512B Jun 7 18:43 tests
drwxr-xr-x 10 user1 staff 320B Jun 7 18:43 wcwidth
drwxr-xr-x 9 user1 staff 288B Jun 7 18:43 wcwidth-0.2.5.dist-info
```
1. `zip` コマンドを使用して、md2gemini プロジェクトの内容を、`md2gemini.zip` という名前のファイルに格納します。
```
unpacked $ zip -r9 ../md2gemini *
```
**出力**
```
adding: CJKwrap-2.2.dist-info/ (stored 0%)
adding: CJKwrap-2.2.dist-info/RECORD (deflated 37%)
....
adding: wcwidth-0.2.5.dist-info/INSTALLER (stored 0%)
adding: wcwidth-0.2.5.dist-info/METADATA (deflated 62%)
```
1. (オプション) 次のコマンドを使用して、ライブラリがローカルコンピュータで動作することをテストします。
1. Python パスを `md2gemini.zip` ファイルの場所に設定し、Python を起動します。
```
/home $ PYTHONPATH=/tmp/testmd2gemini/md2gemini.zip
/home python3
```
1. ライブラリをインポートしてテストを実行します。
```
>>> from md2gemini import md2gemini
>>> print(md2gemini('[abc](https://abc.def)'))
```
**出力**
```
https://abc.def abc
```
1. 次のコマンドを使用して Amazon S3 から `.zip` ファイルを追加し、Athena のノートブックにインポートして、UDF 以外のテストを実行します。
```
# (non udf test)
sc.addPyFile('s3://amzn-s3-demo-bucket/md2gemini.zip')
from md2gemini import md2gemini
print(md2gemini('[abc](https://abc.def)'))
```
**出力**
```
Calculation started (calculation_id=0ac0a082-6c3f-5a8f-eb6e-f8e9a5f9bc44) in (session=36c0a082-5338-3755-9f41-0cc954c55b35). Checking calculation status...
Calculation completed.
=> https://abc.def (https://abc.def/) abc
```
1. 次のコマンドを使用して、UDF テストを実行します。
```
# (udf test)
from pyspark.sql.functions import udf
from pyspark.sql.functions import col
from md2gemini import md2gemini
hi_udf = udf(md2gemini)
df = spark.createDataFrame([(1, "[first website](https://abc.def)"), (2, "[second website](https://aws.com)")])
df.withColumn("col", hi_udf(col('_2'))).show()
```
**出力**
```
Calculation started (calculation_id=60c0a082-f04d-41c1-a10d-d5d365ef5157) in (session=36c0a082-5338-3755-9f41-0cc954c55b35). Checking calculation status...
Calculation completed.
+---+--------------------+--------------------+
| _1| _2| col|
+---+--------------------+--------------------+
| 1|[first website](h...|=> https://abc.de...|
| 2|[second website](...|=> https://aws.co...|
+---+--------------------+--------------------+
```
# Spark プロパティを使用してカスタム設定を指定する
Amazon Athena for Apache Spark でセッションを作成または編集する場合、[[Spark プロパティ]](https://spark.apache.org/docs/latest/configuration.html#spark-properties) を使用してセッションの `.jar` ファイル、パッケージ、またはその他のカスタム設定を指定できます。Spark のプロパティを指定するには、Athena コンソール、AWS CLI、または Athena API を使用できます。
## Athena コンソールを使用して Spark プロパティを指定する
Athena コンソールでは、[ノートブックの作成](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)時や[現在のセッションの編集](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)時に Spark プロパティを指定できます。
****[ノートブックの作成]** または **[セッションの詳細の編集]** ダイアログボックスにプロパティを追加する方法**
1. **[Spark のプロパティ]** を拡張します。
1. プロパティを追加するには、**[テーブルで編集]** または **[JSON で編集]** オプションを使用します。
+ **[テーブルで編集]** オプションを使用する場合は、**[プロパティを追加]** を選択してプロパティを追加するか、**[削除]** を選択してプロパティを削除します。**[キー]** ボックスと **[値]** ボックスを使用して、プロパティ名とその値を入力します。
+ カスタム `.jar` ファイルを追加するには、`spark.jars` プロパティを使用します。
+ パッケージファイルを指定するには、`spark.jars.packages` プロパティを使用します。
+ 設定を直接入力して編集するには、**[JSON で編集]** オプションを選択します。JSON テキストエディタでは、次のタスクを実行できます。
+ JSON テキストをクリップボードにコピーするには、**[コピー]** を選択します。
+ JSON エディタからすべてのテキストを削除するには、**[クリア]** を選択します。
+ 設定 (歯車) アイコンを選択して行折り返しの動作を設定するか、JSON エディタのカラーテーマを選択します。
### 注意事項
+ Athena for Spark でプロパティを設定できます。これは [[SparkConf]](https://spark.apache.org/docs/latest/api/python/reference/api/pyspark.SparkConf.html) オブジェクトで [[Spark properties]](https://spark.apache.org/docs/latest/configuration.html#spark-properties) を直接設定する場合と同じです。
+ `spark.` プレフィックスが付いたすべての Spark プロパティを開始します。他のプレフィックスが付いたプロパティは無視されます。
+ Athena のカスタム設定では、すべての Spark プロパティを利用できるわけではありません。設定が制限されている `StartSession` リクエストを送信すると、セッションは開始時に失敗します。
+ `spark.athena.` プレフィックスは予約されているため使用できません。
## AWS CLI または Athena API を使用してカスタム設定を指定する
AWS CLI または Athena API を使用してセッション設定を指定するには、[StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) API アクションまたは [start-session](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/start-session.html) CLI コマンドを使用します。`StartSession` リクエストでは、[EngineConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EngineConfiguration.html) オブジェクトの `SparkProperties` フィールドを使用して設定情報を JSON 形式で渡します。これにより、指定した設定でセッションが開始されます。
AWS CLI からカスタム Spark プロパティを指定するには、インタラクティブセッションの開始時に `engine-configuration` 設定を使用します。
```
aws athena start-session \
--region "REGION"
--work-group "WORKGROUP" \
--engine-configuration '{
"Classifications": [{
"Name": "spark-defaults",
"Properties": {
"spark.dynamicAllocation.minExecutors": "1",
"spark.dynamicAllocation.initialExecutors": "2",
"spark.dynamicAllocation.maxExecutors": "10",
"spark.dynamicAllocation.executorIdleTimeout": "300"
}
}]
}'
```
`CreateWorkgroup` API アクションまたは `UpdateWorkgroup` API アクションを使用して、ワークグループレベルでデフォルト設定を指定することもできます。ワークグループで定義したデフォルト設定は、そのワークグループで開始されたすべてのセッションに適用されます。
ワークグループの AWS CLI からデフォルトの Spark プロパティを指定するには、新しいワークグループの作成時に `engine-configuration` 設定を使用します。
```
aws athena create-work-group \
--region "REGION" \
--name "WORKGROUP_NAME" \
--configuration '{
"EngineVersion": {
"SelectedEngineVersion": "Apache Spark version 3.5"
},
"ExecutionRole": "EXECUTION_ROLE",
"EngineConfiguration": {
"Classifications": [
{
"Name": "spark-defaults",
"Properties": {
"spark.dynamicAllocation.minExecutors": "1",
"spark.dynamicAllocation.initialExecutors": "2",
"spark.dynamicAllocation.maxExecutors": "10",
"spark.dynamicAllocation.executorIdleTimeout": "300"
}
}
]
}
}'
```
ワークグループの AWS CLI からデフォルトの Spark プロパティに変更を加えるには、ワークグループの更新時に `engine-configuration` 設定を使用します。この変更は、その後の新しいインタラクティブセッションに適用されます。
```
aws athena update-work-group \
--region "REGION" \
--work-group "WORKGROUP_NAME" \
--configuration-updates '{
"EngineVersion": {
"SelectedEngineVersion": "Apache Spark version 3.5"
},
"ExecutionRole": "EXECUTION_ROLE",
"EngineConfiguration": {
"Classifications": [
{
"Name": "spark-defaults",
"Properties": {
"spark.dynamicAllocation.minExecutors": "1",
"spark.dynamicAllocation.initialExecutors": "2",
"spark.dynamicAllocation.maxExecutors": "12",
"spark.dynamicAllocation.executorIdleTimeout": "300"
}
}
]
}
}'
```
# サポートされているデータおよびストレージ形式
次の表に、Athena for Apache Spark でネイティブにサポートされている形式を示します。
****
| **[Data format]** (データ形式) | **読み込み** | **書き込み** | **[Write compression]** (書き込み圧縮) |
| --- | --- | --- | --- |
| parquet | はい | はい | なし、非圧縮、snappy、gzip |
| orc | はい | はい | なし、snappy、zlib、lzo |
| json | はい | はい | bzip2、gzip、デフレート |
| csv | はい | はい | bzip2、gzip、デフレート |
| text | はい | はい | なし、bzip2、gzip、デフレート |
| バイナリファイル | はい | 該当なし | 該当なし |
# CloudWatch メトリクスを使用して Apache Spark をモニタリングする
Spark 対応のワークグループの **[[Publish CloudWatch metrics](notebooks-spark-getting-started.md#notebook-gs-metrics)]** オプションが選択されている場合、Athena は計算関連のメトリクスを Amazon CloudWatch に発行します。カスタムダッシュボードを作成して、CloudWatch コンソールでメトリクスにアラームおよびトリガーを設定できます。
Athena は、次のメトリクスを `AmazonAthenaForApacheSpark` 名前空間で CloudWatch コンソールに発行します。
+ `DPUCount` - 計算を実行するために、セッション中に消費された DPU の数。
このメトリクスには、次のディメンションがあります。
+ `SessionId` - 計算が送信されるセッションの ID。
+ `WorkGroup` - ワークグループの名前。
**Amazon CloudWatch コンソールで Spark 対応のワークグループ用メトリクスを表示する**
1. CloudWatch コンソールの [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) を開いてください。
1. ナビゲーションペインで、[**Metrics**]、[**All metrics**] を選択します。
1. **[AmazonAthenaForApacheSpark]** 名前空間を選択してください。
**CLI を使用してメトリクスを表示するには**
+ 次のいずれかを行います。
+ Athena Spark 対応のワークグループ用メトリクスを一覧表示するには、コマンドプロンプトを開き、次のコマンドを使用します。
```
aws cloudwatch list-metrics --namespace "AmazonAthenaForApacheSpark"
```
+ すべての使用可能なメトリクスのリストを表示するには、次のコマンドを使用します。
```
aws cloudwatch list-metrics
```
## Athena の Apache Spark 向けの CloudWatch メトリクスおよびディメンションのリスト
Spark 対応の Athena ワークグループで CloudWatch メトリクスを有効にしている場合、Athena はワークグループごとに次のメトリクスを CloudWatch に送信します。メトリクスは `AmazonAthenaForApacheSpark` 名前空間を使用します。
****
| メトリクス名 | 説明 |
| --- | --- |
| DPUCount | 計算を実行するためにセッション中に消費された DPU (Data Processing Units) の数。DPU は処理能力を相対的に測定するもので、4 個の vCPU のコンピューティング性能と 16 GB のメモリで構成されています。 |
このメトリクスには、次のディメンションがあります。
| ディメンション | 説明 |
| --- | --- |
| SessionId | 計算が送信されるセッションの ID。 |
| WorkGroup | ワークグループの名前。 |
## Athena Spark インタラクティブセッション向けの CloudWatch メトリクスとディメンションのリスト
リリースバージョン Apache Spark バージョン 3.5 では、Athena Spark ワークグループで CloudWatch メトリクスを有効にしている場合、Athena は次のメトリクスを CloudWatch に送信します。メトリクスは `AmazonAthenaForApacheSpark` 名前空間を使用します。
****
| 名前 | 説明 |
| --- | --- |
| DPUConsumed | ワークグループで所定の時間に RUNNING 状態でクエリによってアクティブに消費される DPU の数。 |
このメトリクスには、次のディメンションがあります。
| ディメンション | 説明 |
| --- | --- |
| アカウント | AWS アカウント ID。 |
| WorkGroup | ワークグループの名前。 |
# セッションレベル原価配分
Apache Spark バージョン 3.5 以降のリリースバージョンでは、Athena は各セッションのコストを追跡できます。セッションの開始時にコスト配分タグを定義できます。セッションに対して報告されたコストは、Cost Explorer または AWS 請求コスト配分レポートに表示されます。コスト配分タグをワークグループレベルで適用し、そのワークグループで開始されたセッションにそれらのタグをコピーすることもできます。
## セッションレベル原価配分の使用
デフォルトでは、ワークグループレベルで指定されたコスト配分タグは、そのワークグループで開始されたインタラクティブセッションにコピーされます。
AWS CLI からインタラクティブセッションを開始するときにワークグループからコピーされるタグを無効にする方法:
```
aws athena start-session \
--region "REGION" \
--work-group "WORKGROUP" \
--tags '[
{
"Key": "tag_key",
"Value": "tag_value"
}
]' \
--no-copy-work-group-tags
```
AWS CLI からインタラクティブセッションを開始するときにワークグループからコピーされるタグを有効にする方法:
```
aws athena start-session \
--region "REGION" \
--work-group "WORKGROUP" \
--copy-work-group-tags
```
## 考慮事項と制約事項
+ セッションタグは、ワークグループタグを同じキーで上書きします。
# Apache Spark セッションのログ記録とモニタリング
リリース Apache Spark バージョン 3.5 以降では、ログ記録オプションとして、マネージド、Amazon S3、または CloudWatch のログ記録を指定できます。
マネージドログ記録と S3 ログ記録について、これらのオプションを選択した場合に想定されるログの場所と UI の可用性を次の表に一覧表示します。
****
| オプション | イベントログ | コンテナログ | アプリケーション UI |
| --- | --- | --- | --- |
| マネージドログ記録（デフォルト） | マネージド S3 バケットに保存 | マネージド S3 バケットに保存 | サポート |
| マネージドログ記録と S3 バケットの両方 | 両方の場所に保存 | S3 バケットに保存 | サポート |
| Amazon S3 バケット | S3 バケットに保存 | S3 バケットに保存 | サポート外1 |
1 マネージドログ記録オプションを選択したままにすることをお勧めします。それ以外の場合は、組み込みのアプリケーション UI を使用できません。
## マネージドログ記録
デフォルトでは、Athena Spark ワークグループはアプリケーションログをサービスマネージド S3 バケットに最長で 30 日間安全に保存します。
必要に応じて、サービスでマネージドログの暗号化に使用する KMS キー （キー ID、ARN、エイリアス、またはエイリアス ARN）を指定できます。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"ManagedLoggingConfiguration": {
"Enabled": true,
"KmsKey": "KMS_KEY"
},
}'
--engine-configuration ''
```
**注記**
マネージドログ記録をオフにすると、Athena はユーザーに代わってセッションのトラブルシューティングを行うことができません。例：Amazon SageMaker AI Studio ノートブックまたは `GetResourceDashboard` API を使用して Spark-UI にアクセスすることはできません。
このオプションを AWS CLI からオフにするには、インタラクティブセッションの開始時に `ManagedLoggingConfiguration` 設定を使用します。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"ManagedLoggingConfiguration": {
"Enabled": false
},
}'
--engine-configuration ''
```
### マネージドログ記録に必要な許可
KMS キーを指定した場合は、実行ロールの許可ポリシーに次のア許可が必要になります。
```
{
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*",
"Effect": "Allow"
}
```
## Amazon S3 ログ記録
Amazon S3 バケットへのログ配信を設定できます。
S3 ログ配信を AWS CLI から有効にするには、インタラクティブセッションの開始時に `S3LoggingConfiguration` 設定を使用します。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"S3LoggingConfiguration": {
"Enabled":true,
"LogLocation": "s3://bucket/",
},
}'
--engine-configuration ''
```
必要に応じて、サービスで S3 ログの暗号化に使用する KMS キー （キー ID、ARN、エイリアス、またはエイリアス ARN）を指定できます。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"S3LoggingConfiguration": {
"Enabled":true,
"LogLocation": "s3://bucket/",
"KmsKey": "KMS_KEY"
},
}'
--engine-configuration ''
```
### Amazon S3 へのログ配信に必要な許可
セッションで Amazon S3 バケットへのログ配信を可能にする前に、実行ロールの許可ポリシーに次の許可を含めてください。
```
{
"Action": "s3:*",
"Resource": "*",
"Effect": "Allow"
}
```
KMS キーを指定した場合は、実行ロールの許可ポリシーに次のア許可も必要になります。
```
{
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*",
"Effect": "Allow"
}
```
KMS キーとバケットが同じアカウントに由来していない場合、KMS は S3 サービスプリンシパルを許可する必要があります。
```
{
"Effect": "Allow",
"Principal": { "Service": "s3.amazonaws.com" },
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey*"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "ACCOUNT_HAVING_KMS_KEY"
}
}
}
```
## CloudWatch ロギング
CloudWatch ロググループへのログ配信を設定できます。
S3 ログ配信を AWS CLI から有効にするには、インタラクティブセッションの開始時に `CloudWatchLoggingConfiguration` 設定を使用します。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"CloudWatchLoggingConfiguration": {
"Enabled": true,
"LogGroup": "/aws/athena/sessions/${workgroup}",
"LogStreamNamePrefix": "session-"
}
}'
--engine-configuration ''
```
デフォルトではすべてのログが配信されますが、含めるログタイプを指定できるオプションがあります。
```
aws athena start-session \
--work-group "WORKGROUP" \
--monitoring-configuration '{
"CloudWatchLoggingConfiguration": {
"Enabled": true,
"LogGroup": "/aws/athena/sessions/${workgroup}",
"LogStreamNamePrefix": "session-",
"LogTypes": {
"SPARK_DRIVER": [
"STDOUT",
"STDERR"
],
"SPARK_EXECUTOR": [
"STDOUT",
"STDERR"
]
}
}
}'
--engine-configuration ''
```
### CloudWatch へのログ配信に必要な許可
セッションで CloudWatch ロググループへのログ配信を可能にする前に、実行ロールの許可ポリシーに次の許可を含めてください。
```
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogGroups",
"logs:DescribeLogStreams"
],
"Resource": "*",
"Effect": "Allow"
}
```
そして次の許可を KMS キーリソースポリシーに含めてください。
```
{
"Effect": "Allow",
"Principal": {
"Service": "logs..amazonaws.com"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource": "*"
}
```
## ワークグループでのログ記録のデフォルト設定
ワークグループレベルでデフォルトのログ記録オプションを指定することもできます。
ワークグループの AWS CLI からデフォルトのログ記録オプションを指定するには、新規ワークグループの作成時に `monitoring-configuration` 設定を使用します。
```
aws athena create-work-group \
--region "REGION" \
--name "WORKGROUP_NAME" \
--monitoring-configuration '{
"CloudWatchLoggingConfiguration": {
"Enabled": true,
"LogGroup": "/aws/athena/sessions/${workgroup}",
"LogStreamNamePrefix": "session-",
"LogTypes": {
"SPARK_DRIVER": [
"STDOUT",
"STDERR"
],
"SPARK_EXECUTOR": [
"STDOUT",
"STDERR"
]
}
},
"ManagedLoggingConfiguration": {
"Enabled": true,
"KmsKey": "KMS_KEY"
},
"S3LoggingConfiguration": {
"Enabled": true,
"KmsKey": "KMS_KEY"
"LogLocation": "s3://bucket/",
"LogTypes": {
"SPARK_DRIVER": [
"STDOUT",
"STDERR"
],
"SPARK_EXECUTOR": [
"STDOUT",
"STDERR"
]
}
}
}'
```
ワークグループの AWS CLI からデフォルトのログ記録オプションに変更を加えるには、ワークグループのアップデート時に `monitoring-configuration` 設定を使用します。この変更は、その後の新しいインタラクティブセッションに適用されます。
```
aws athena update-work-group \
--region "REGION" \
--work-group "WORKGROUP_NAME"
--monitoring-configuration '{
"CloudWatchLoggingConfiguration": {
"Enabled": true,
"LogGroup": "/aws/athena/sessions/${workgroup}",
"LogStreamNamePrefix": "session-",
"LogTypes": {
"SPARK_DRIVER": [
"STDOUT",
"STDERR"
],
"SPARK_EXECUTOR": [
"STDOUT",
"STDERR"
]
}
},
"ManagedLoggingConfiguration": {
"Enabled": true,
"KmsKey": "KMS_KEY"
},
"S3LoggingConfiguration": {
"Enabled": true,
"KmsKey": "KMS_KEY"
"LogLocation": "s3://bucket/",
"LogTypes": {
"SPARK_DRIVER": [
"STDOUT",
"STDERR"
],
"SPARK_EXECUTOR": [
"STDOUT",
"STDERR"
]
}
}
}'
```
# Spark UI へのアクセス
Apache Spark UI は、実行中および完了した Spark ジョブに関する詳細情報が含まれているビジュアルインターフェイスです。ネイティブ Apache Spark UIs を使用して Athena Spark のインタラクティブセッションのモニタリングとデバッグを実行できます。その中で、各 Spark ジョブのイベントタイムライン、ステージ、タスク、エグゼキュターに関するジョブ固有のメトリクスと情報を詳しく調べることができます。
## Spark UI へのアクセス
Athena Spark インタラクティブセッションを開始すると、Amazon SageMaker AI Unified Studio ノートブックからセッションを実行するためにリアルタイム Spark UI を表示したり、`GetResourceDashboard` API を使用して安全な URL をリクエストしたりすることができます。完了したセッションについては、Amazon SageMaker AI Unified Studio ノートブックから、Amazon Athena コンソールから、または同じ API を使用して、Spark History Server を表示できます。
```
aws athena get-resource-dashboard \
--region "REGION" \
--session-id "SESSION_ID"
```
## Spark UI へのアクセスに必要なアクセス許可
Spark UI にアクセスする前に、ユーザーまたはロールのアクセス許可ポリシーに次のアクセス許可を含めます。
```
{
"Action": "athena:GetResourceDashboard",
"Resource": "WORKGROUP",
"Effect": "Allow"
}
```
# Spark Connect のサポート
Spark Connect は Apache Spark 向けのクライアントサーバーアーキテクチャであり、アプリケーションクライアントを Spark クラスターのドライバープロセスから切り離すことで、サポートされているクライアントから Spark へのリモート接続を可能にします。Spark Connect では、開発中に好みの IDE/クライアントからインタラクティブデバッグを直接実行することもできます。
Apache Spark バージョン 3.5 以降のリリースバージョンでは、Athena は `GetSessionEndpoint` API を使用してアクセスできる AWS エンドポイントとして Spark Connect をサポートしています。
## API/CLI の例（GetSessionEndpoint）
`GetSessionEndpoint` API を使用して、インタラクティブセッションの Spark Connect エンドポイントを取得できます。
```
aws athena get-session-endpoint \
--region "REGION" \
--session-id "SESSION_ID"
```
この API は、そのセッションの Spark Connect エンドポイント URL を返します。
```
{
"EndpointUrl": "ENDPOINT_URL",
"AuthToken": "AUTH_TOKEN",
"AuthTokenExpirationTime": "AUTH_TOKEN_EXPIRY_TIME"
}
```
## セルフマネージドクライアントからの接続
セルフマネージドクライアントから Athena Spark インタラクティブセッションに接続できます。
### 前提条件
Spark 3.5.6 および AWS SDK for Python 用の pyspark-connect クライアントをインストールします。
```
pip install --user pyspark[connect]==3.5.6
pip install --user boto3
```
以下に示すのは、リクエストをセッションエンドポイントに直接送信するための Python スクリプトのサンプルです。
```
import boto3
import time
from pyspark.sql import SparkSession
client = boto3.client('athena', region_name='')
# start the session
response = client.start_session(
WorkGroup='',
EngineConfiguration={}
)
# wait for the session endpoint to be ready
time.sleep(5)
response = client.get_session_endpoint(SessionId=session_id)
# construct the authenticated remote url
authtoken=response['AuthToken']
endpoint_url=response['EndpointUrl']
endpoint_url=endpoint_url.replace("https", "sc")+":443/;use_ssl=true;"
url_with_headers = (
f"{endpoint_url}"
f"x-aws-proxy-auth={authtoken}"
)
# start the Spark session
start_time = time.time()
spark = SparkSession.builder\
.remote(url_with_headers)\
.getOrCreate()
spark.version
#
# Enter your spark code here
#
# stop the Spark session
spark.stop()
```
以下に示すのは、セッションのライブ Spark UI または Spark History Server にアクセスするための Python スクリプトの例です。
```
Region=''
WorkGroupName=''
SessionId=''
Partition='aws'
Account=''
SessionARN=f"arn:{Partition}:athena:{Region}:{Account}:workgroup/{WorkGroupName}/session/{SessionId}"
# invoke the API to get the live UI/persistence UI for a session
response = client.get_resource_dashboard(
ResourceARN=SessionARN
)
response['Url']
```
# Athena for Spark でリクエスタによる Amazon S3 バケットの支払いを有効にする
Amazon S3 バケットをリクエスタが支払うように設定すると、クエリに関連するデータアクセス料金とデータ転送料金がクエリを実行したユーザーのアカウントに請求されます。詳細については、「*Amazon S3 ユーザーガイド*」の「[ストレージ転送と使用量のリクエスタ支払いバケットの使用](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html)」を参照してください。
Athena for Spark では、リクエスタ支払いバケットがワークグループごとではなく、セッションごとに有効化されます。リクエスタ支払いバケットを有効にする大まかな手順は次のとおりです。
1. Amazon S3 コンソールで、バケットのプロパティに対するリクエスタによる支払いを有効にし、アクセスを指定するバケットポリシーを追加します。
1. IAM コンソールで、バケットへのアクセスを許可する IAM ポリシーを作成し、そのポリシーをリクエスタ支払いバケットへのアクセスに使用する IAM ロールにアタッチします。
1. Athena for Spark では、セッションプロパティを追加してリクエスタによる支払い機能を有効にします。
## ステップ 1: Amazon S3 バケットでリクエスタ支払いを有効にし、バケットポリシーを追加する
**Amazon S3 バケットのリクエスタ支払いを有効にするには**
1. Amazon S3 コンソール ([https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)) を開きます。
1. バケットのリストで、リクエスタ支払いを有効にするバケットのリンクを選択します。
1. バケットのページで、**[プロパティ]** タブを選択します。
1. **[リクエスタ支払い]** セクションまで下にスクロールし、**[編集]** を選択します。
1. **[リクエスタ支払いを編集]** ページで、**[有効化]** を選択し、**[変更の保存]** を選択します。
1. **[アクセス許可]** タブを選択します。
1. **[バケットポリシー]** セクションで、**[編集]** を選択します。
1. **[バケットポリシーを編集]** ページで、必要なバケットポリシーをソースバケットに適用します。以下のポリシー例では、すべての AWS プリンシパル (`"AWS": "*"`) へのアクセスを許可していますが、アクセスをより細かく設定することもできます。例えば、別のアカウントの特定の IAM ロールのみを指定したい場合があります。
------
#### [ JSON ]
****
```
{ "Version":"2012-10-17", "Statement": [ { "Sid": "Statement1", "Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::111122223333:root" },
"Action": "s3:*", "Resource": [
"arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket",
"arn:aws:s3:::555555555555-us-east-1-amzn-s3-demo-bucket/*"
] } ] }
```
------
## ステップ 2: IAM ポリシーを作成して、それを IAM ロールにアタッチします。
次に、バケットへのアクセスを許可する IAM ポリシーを作成します。次に、リクエスタ支払いバケットへのアクセスに使用されるロールにポリシーをアタッチします。
**リクエスタ支払いバケット用の IAM ポリシーを作成し、そのポリシーをロールにアタッチするには**
1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。
1. IAM コンソールのナビゲーションペインで、**[ポリシー]** を選択します。
1. [**Create policy**] を選択します。
1. **[JSON]** を選択します。
1. **[ポリシーエディタ]** で、以下のポリシーを追加します。
------
#### [ JSON ]
****
```
{ "Version":"2012-10-17", "Statement": [ { "Action": [ "s3:*" ], "Effect": "Allow",
"Resource": [
"arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket",
"arn:aws:s3:::111122223333-us-east-1-amzn-s3-demo-bucket/*"
] } ] }
```
------
1. [**次へ**] を選択します。
1. **[確認と作成]** ページで、ポリシーの 名前とオプションの説明を入力し、**[ポリシーの作成]** を選択します。
1. ナビゲーションペインで **[Roles]** (ロール) を選択してください。
1. **[ロール]** ページで、使用したいロールを見つけて、ロール名のリンクを選択します。
1. **[アクセス許可ポリシー]** で、**[アクセス許可を追加]** と **[ポリシーをアタッチ]** を続けて選択します。
1. **[その他の許可ポリシー]** セクションで、作成したポリシーのチェックボックスをオンにし、**[アクセス許可を追加]** を選択します。
## ステップ 3: Athena for Spark セッションプロパティを追加する
Amazon S3 バケットとリクエスタ支払いに関連するアクセス許可を設定した後、Athena for Spark セッションでこの機能を有効にできます。
**Athena for Spark セッションでリクエスタ支払いバケットを有効にするには**
1. ノートブックエディタで、右上の **[Session]** (セッション) メニューから **[Edit session]** (セッションの編集) を選択します。
1. **[Spark のプロパティ]** を拡張します。
1. **[JSON で編集]** を選択します。
1. JSON テキストエディタで、以下を入力します。
```
{
"spark.hadoop.fs.s3.useRequesterPaysHeader":"true"
}
```
1. **[保存]** を選択します。
# Lake Formation と Athena Spark ワークグループの併用
リリースバージョン Apache Spark バージョン 3.5 では、セッション実行ロールに完全なテーブルアクセス許可がある AWS Glue Data Catalog とともに AWS Lake Formation を活用できます。この機能を使用すると、Athena Spark インタラクティブジョブから Lake Formation によって保護されているテーブルの読み取りと書き込みを実行できます。Lake Formation の詳細と Athena Spark との併用方法については、以降のセクションを参照してください。
## ステップ 1: Lake Formation でフルテーブルアクセスを有効にする
フルテーブルアクセス（FTA）モードを使用するには、AWS Lake Formation で IAM セッションタグの検証を行わずに Athena Spark がデータにアクセスすることを許可する必要があります。有効にするには、「[フルテーブルアクセスのためのアプリケーション統合](https://docs.aws.amazon.com//lake-formation/latest/dg/fta-app-integration.html)」のステップに従います。
### ステップ 1.1：ユーザー定義ロールを使用して Lake Formation にデータロケーションを登録する
AWS Lake Formation でデータロケーションを登録するには、ユーザー定義のロールを使用する必要があります。詳細については、「[ロケーションの登録に使用されるロールの要件](https://docs.aws.amazon.com//lake-formation/latest/dg/registration-role.html)」を参照してください。
## ステップ 2：セッションの実行ロールの IAM アクセス許可を設定する
基盤となるデータへの読み取りアクセス権や書き込みアクセス権については、Lake Formation アクセス許可に加えて、実行ロールに `lakeformation:GetDataAccess` IAM アクセス許可が必要です。この許可があると、Lake Formation がデータにアクセスするための一時的な認証情報のリクエストを承諾します。
以下は、Amazon S3 のスクリプトにアクセスするための IAM 許可、S3 AWS Glue へのログのアップロード、 API 許可、Lake Formation へのアクセス許可を指定する方法に関するポリシーの例です。
### ステップ 2.1: Lake Formation の許可を設定する
+ S3 からデータを読み取る Spark ジョブには、Lake Formation `SELECT` 許可が必要です。
+ S3 でデータの書き込み/削除を行う Spark ジョブには、Lake Formation `ALL (SUPER)` 許可が必要です。
+ AWS Glue Data Catalog を操作する Spark ジョブには、必要に応じて `DESCRIBE`、`ALTER`、`DROP` 許可が必要です。
## ステップ 3: Lake Formation を使用してフルテーブルアクセスのための Spark セッションを初期化する
### 前提条件
AWS Glue Data Catalog は、Lake Formation テーブルにアクセスするためのメタストアとして設定しなければなりません。
AWS Glue Catalog をメタストアとして設定するには、以下の設定を行います。
```
{
"spark.hadoop.glue.catalogid": "ACCOUNT_ID",
"spark.hadoop.hive.metastore.client.factory.class": "com.amazonaws.glue.catalog.metastore.AWSGlueDataCatalogHiveClientFactory",
"spark.hadoop.hive.metastore.glue.catalogid": "ACCOUNT_ID",
"spark.sql.catalogImplementation": "hive"
}
```
AWS Lake Formation に登録されたテーブルにアクセスするには、Spark の初期化中に以下の設定を行い、AWS Lake Formation 認証情報を使用するように Spark を設定する必要があります。
### [Hive]
```
{
"spark.hadoop.fs.s3.credentialsResolverClass": "com.amazonaws.glue.accesscontrol.AWSLakeFormationCredentialResolver",
"spark.hadoop.fs.s3.useDirectoryHeaderAsFolderObject": "true",
"spark.hadoop.fs.s3.folderObject.autoAction.disabled": "true",
"spark.sql.catalog.skipLocationValidationOnCreateTable.enabled": "true",
"spark.sql.catalog.createDirectoryAfterTable.enabled": "true",
"spark.sql.catalog.dropDirectoryBeforeTable.enabled": "true"
}
```
### Apache Iceberg
```
{
"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "org.apache.iceberg.spark.SparkSessionCatalog",
"spark.sql.catalog.spark_catalog.warehouse": "s3://your-bucket/warehouse/",
"spark.sql.catalog.spark_catalog.client.region": "REGION",
"spark.sql.catalog.spark_catalog.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
"spark.sql.catalog.spark_catalog.glue.account-id": "ACCOUNT_ID",
"spark.sql.catalog.spark_catalog.glue.lakeformation-enabled": "true"
}
```
### Amazon S3 Tables
```
{
"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.{catalogName}": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.{catalogName}.warehouse": "arn:aws:s3tables:{region}:{accountId}:bucket/{bucketName}",
"spark.sql.catalog.{catalogName}.catalog-impl": "org.apache.iceberg.aws.glue.GlueCatalog",
"spark.sql.catalog.{catalogName}.glue.id": "{accountId}:s3tablescatalog/{bucketName}",
"spark.sql.catalog.{catalogName}.glue.lakeformation-enabled": "true",
"spark.sql.catalog.{catalogName}.client.region": "REGION",
"spark.sql.catalog.{catalogName}.glue.account-id": "ACCOUNT_ID"
}
```
### Delta Lake
```
{
"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "org.apache.spark.sql.delta.catalog.DeltaCatalog",
"spark.hadoop.fs.s3.credentialsResolverClass": "com.amazonaws.glue.accesscontrol.AWSLakeFormationCredentialResolver",
"spark.hadoop.fs.s3.useDirectoryHeaderAsFolderObject": "true",
"spark.hadoop.fs.s3.folderObject.autoAction.disabled": "true",
"spark.sql.catalog.skipLocationValidationOnCreateTable.enabled": "true",
"spark.sql.catalog.createDirectoryAfterTable.enabled": "true",
"spark.sql.catalog.dropDirectoryBeforeTable.enabled": "true"
}
```
## 考慮事項と制約事項
+ フルテーブルアクセスは、Hive、Iceberg、Amazon S3 Tables、Delta テーブルでサポートされています。Hudi テーブルはフルテーブルアクセスをサポートしていません。
+ アクティブセッションに新しいカタログを追加するには、新規カタログ設定とともに `spark.conf.set` を使用します。
+ カタログ設定はイミュータブルです。カタログ設定をアップデートする場合は、`spark.conf.set` を使用して新しいカタログを作成します。
+ Spark セッションに必要なカタログのみを追加します。
+ デフォルトカタログを変更する方法：`spark.catalog.setCurrentCatalog("s3tablesbucket")`
+ `-` のようにカタログ名に特殊文字がある場合は、次のようにクエリでエスケープしてください。
```
SELECT sales_amount as nums FROM `my-s3-tables-bucket`.`s3namespace`.`daily_sales` LIMIT 100
```
# Apache Spark 暗号化を有効にする
Athena で Apache Spark 暗号化を有効にできます。有効にすると、Spark ノード間で転送中のデータが暗号化され、Spark にローカル保存されている保管中のデータも暗号化されます。このデータのセキュリティを強化するために、Athena では以下の暗号化設定を使用しています。
```
spark.io.encryption.keySizeBits="256"
spark.io.encryption.keygen.algorithm="HmacSHA384"
```
Spark 暗号化を有効にするには、Athena コンソール、AWS CLI、または Athena API を使用できます。
## Athena コンソールを使用して新しいノートブックで Spark 暗号化を有効にする
**Spark 暗号化が有効になっているノートブックを新規作成する方法**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
1. 次のいずれかを行います。
+ **[Notebook explorer]** (ノートブックエクスプローラー) で、**[Create notebook]** (ノートブックの作成) を選択します。
+ **[Notebook editor]** (ノートブックエディタ) で、**[Create notebook]** (ノートブックの作成) を選択するか、プラスアイコン (**[\$1]**) を選択してノートブックを追加します。
1. **[ノートブック名]** に、ノートブックの名前を入力します。
1. **[Spark プロパティ]** オプションを拡張します。
1. **[Spark 暗号化を有効にする]** を選択します。
1. **[作成]** を選択します。
作成したノートブックセッションが暗号化されます。新しいノートブックは、通常どおりに使用してください。後ほど、ノートブックを使用する新しいセッションを起動すると、新しいセッションも暗号化されます。
## Athena コンソールを使用して既存のノートブックの Spark 暗号化を有効にする
また、Athena コンソールを使用して、既存のノートブックの Spark 暗号化を有効にできます。
**既存のノートブックの暗号化を有効にする方法**
1. 以前に作成したノートブックの [[新しいセッションを開く]](notebooks-spark-managing.md#opening-a-previously-created-notebook) を実行します。
1. ノートブックエディタで、右上の **[Session]** (セッション) メニューから **[Edit session]** (セッションの編集) を選択します。
1. **[セッションの詳細の編集]** ダイアログボックスにある **[Spark プロパティ]** を拡張します。
1. **[Spark 暗号化を有効にする]** を選択します。
1. **[保存]** を選択します。
コンソールに、暗号化が有効になっている新しいセッションが起動します。このノートブック用に作成する後続のセッションでも、暗号化が有効になっています。
## AWS CLI を使用して Spark 暗号化を有効にする
AWS CLI を使用して、適切な Spark プロパティを指定することで、セッションを起動するときに暗号化を有効にできます。
**AWS CLI を使用して Spark 暗号化を有効にする**
1. 次のようなコマンドを使用して、Spark 暗号化プロパティを指定するエンジン設定 JSON オブジェクトを作成します。
```
ENGINE_CONFIGURATION_JSON=$(
cat <
Athena API で Spark 暗号化を有効にするには、[StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) アクションとその [EngineConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EngineConfiguration.html) `SparkProperties` パラメータを使用して、`StartSession` リクエスト内の暗号化設定を指定します。
# Athena for Spark でクロスアカウント AWS Glue アクセスを設定する
このトピックでは、コンシューマーアカウント *666666666666* と所有者アカウント *999999999999* を AWS Glue へのクロスアカウントアクセス用に設定する方法を示します。アカウントを設定すると、コンシューマーアカウントで所有者の AWS Glue データベースとテーブルに対して Athena for Spark からのクエリを実行できます。
## ステップ 1: AWS Glue で、コンシューマーロールへのアクセスを提供します。
AWS Glue では、所有者がコンシューマーのロールに所有者の AWS Glue データカタログへのアクセスを許可するポリシーを作成します。
**コンシューマーロールに所有者のデータカタログへのアクセスを許可する AWS Glue ポリシーを追加するには**
1. カタログ所有者のアカウントを使用して、AWS マネジメントコンソール にログインします。
1. [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) で AWS Glue コンソール を開きます。
1. ナビゲーションペインで、**[データカタログ]** を展開し、**[カタログ設定]** を選択します。
1. **[データカタログ設定]** ページの **[アクセス許可]** セクションで、次のようなポリシーを追加します。このポリシーでは、コンシューマーアカウント *666666666666* に、所有者アカウント *999999999999* のデータカタログへのアクセスを許可します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Cataloguers",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::666666666666:role/Admin",
"arn:aws:iam::666666666666:role/AWSAthenaSparkExecutionRole"
]
},
"Action": "glue:*",
"Resource": [
"arn:aws:glue:us-west-2:999999999999:catalog",
"arn:aws:glue:us-west-2:999999999999:database/*",
"arn:aws:glue:us-west-2:999999999999:table/*"
]
}
]
}
```
------
## ステップ 2: アクセス用にコンシューマ アカウントを構成する
コンシューマーアカウントで、所有者の AWS Glue Data Catalog、データベース、テーブルへのアクセスを許可するポリシーを作成し、そのポリシーをロールにアタッチします。次の例では、コンシューマーアカウント *666666666666* を使用しています。
**所有者の AWS Glue Data Catalog にアクセスするための AWS Glue ポリシーを作成するには**
1. コンシューマーアカウントを使用して、AWS マネジメントコンソール にログインします。
1. IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。
1. ナビゲーションペインの **[アクセス管理]** を展開し、**[ポリシー]** を選択します。
1. [**Create policy**] (ポリシーの作成) を選択します。
1. **[アクセス許可の指定]** ページで、**[JSON]** を選択します。
1. **ポリシーエディターで**、所有者アカウントのデータカタログに対する AWS Glue アクションを許可する次のような JSON ステートメントを入力します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "glue:*",
"Resource": [
"arn:aws:glue:us-east-1:999999999999:catalog",
"arn:aws:glue:us-east-1:999999999999:database/*",
"arn:aws:glue:us-east-1:999999999999:table/*"
]
}
]
}
```
------
1. **[次へ]** をクリックします。
1. **[確認と作成]** ページで、**[ポリシー名]** にポリシーの名前を入力します。
1. **[ポリシーを作成]** を選択します。
次に、コンシューマーアカウントの IAM コンソールを使用して、作成したポリシーをIAM ロールまたはコンシューマーアカウントが所有者のデータカタログにアクセスするために使用するロールにアタッチします。
**AWS Glue ポリシーをコンシューマーアカウントのロールにアタッチするには**
1. コンシューマーアカウントの IAM コンソールのナビゲーションペインで **[ロール]** を選択します。
1. **[ロール]** ページで、ポリシーをアタッチしたいロールを探します。
1. **[アクセス許可を追加]**、**[ポリシーをアタッチ]** の順に選択します。
1. 作成したポリシーを見つけます。
1. ポリシーのチェックボックスを選択し、**[アクセス許可を追加]** を選択します。
1. 手順を繰り返して、使用したい他のロールにこのポリシーを追加します。
## ステップ 3: セッションの設定とクエリの作成
Athena Spark のリクエスタアカウントで、指定したロールを使用して[ノートブックの作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook)か、または[現在のセッションを編集する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-editing-session-details)ことで、アクセスをテストするセッションを作成します。[セッションプロパティを設定](notebooks-spark-custom-jar-cfg.md#notebooks-spark-custom-jar-cfg-console)する場合は、次のいずれかを指定します。
+ **AWS Glue カタログ区切り文字** — このアプローチでは、クエリに所有者のアカウント ID を含めます。セッションを使用して別の所有者のデータカタログをクエリする場合は、この方法を使用してください。
+ **AWS Glue カタログ ID** — このアプローチでは、データベースに直接クエリを実行します。この方法は、セッションを使用して 単一の所有者のデータカタログのみをクエリする場合に便利です。
### AWS Glue カタログ区切り文字を使用する
セッションプロパティを編集するときは、以下を追加します。
```
{
"spark.hadoop.aws.glue.catalog.separator": "/"
}
```
セルでクエリを実行するときは、次の例のような構文を使用します。この `FROM` 節では、データベース名の前にカタログ ID と区切り文字が必要であることに注意してください。
```
df = spark.sql('SELECT requestip, uri, method, status FROM `999999999999/mydatabase`.cloudfront_logs LIMIT 5')
df.show()
```
### AWS Glue カタログ ID を使用する
セッションプロパティを編集するときは、次のプロパティを入力します。所有者アカウント ID は *999999999999* に置き換えてください。
```
{
"spark.hadoop.hive.metastore.glue.catalogid": "999999999999"
}
```
セルでクエリを実行するときは、次のような構文を使用します。 この `FROM` 節では、データベース名の前にカタログ ID と区切り文字を挿入する必要がないことに注意してください。
```
df = spark.sql('SELECT * FROM mydatabase.cloudfront_logs LIMIT 10')
df.show()
```
## その他のリソース
[AWS Glue データカタログへのクロスアカウントアクセスを構成する](security-iam-cross-account-glue-catalog-access.md)
「*AWS Lake Formation デベロッパーガイド*」の「[AWS Glue と Lake Formation の両方を使用したクロスアカウント許可の管理](https://docs.aws.amazon.com/lake-formation/latest/dg/hybrid-cross-account.html)」を参照してください。
「*AWS Prescriptive Guidance Patterns*」ガイドの「[Amazon Athena を使用して、共有 AWS Glue Data Catalog へのクロスアカウントアクセスを設定します](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/configure-cross-account-access-to-a-shared-aws-glue-data-catalog-using-amazon-athena.html)」。
# Athena for Spark のサービスクォータを理解する
サービスクォータ (制限とも呼ばれます) とは、AWS アカウントで使用できるサービスリソースまたはオペレーションの最大数のことです。Amazon Athena for Spark と併用できる他の AWS サービスに関するサービスクォータの詳細については、「Amazon Web Services 全般のリファレンス」の「[AWS サービスクォータ](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html)」を参照してください。
**注記**
デフォルト値は、AWS によって設定された初期クォータです。この値は、実際に適用されたクォータ値および適用可能な最大サービスクォータとは異なります。新規の AWS アカウントの低い初期クォータは、経時的に引き上げられる可能性があります。Amazon Athena for Apache Spark は、各 AWS リージョン内のアカウント使用率を常に監視し、使用率に基づいてクォータを自動的に引き上げます。要件が規定の制限を超える場合は、カスタマーサポートにお問い合わせください。
以下の表に Amazon Athena for Apache Spark のサービスクォータを示します。
****
| 名前 | デフォルト | 引き上げ可能 | バージョン | 説明 |
| --- | --- | --- | --- | --- |
| Apache Spark DPU 同時実行 | 160 | いいえ | PySpark バージョン 3 | 現在の AWS リージョンの単一アカウントで Apache Spark の計算で同時に消費できるデータ処理単位 (DPU) の最大数。DPU は処理能力を相対的に測定するもので、4 個の vCPU のコンピューティング性能と 16 GB のメモリで構成されています。 |
| Apache Spark セッション DPU 同時実行 | 60 | いいえ | PySpark バージョン 3 | セッション内の Apache Spark の計算で同時に消費できる DPU の最大数。 |
| オンデマンド DPU | 4 | いいえ | Apache Spark バージョン 3.5 | 現在の AWS リージョン における Apache Spark インタラクティブセッションのために同時に消費できるデータ処理単位 (DPU) の最大数。 |
# Athena Spark API の使用
**注記**
Athena ノートブックと計算 API は、リリースバージョン Pyspark エンジンバージョン 3 で利用できます。ノートブックと計算 API は、リリースバージョン Apache Spark バージョン 3.5 ではサポートされていません。
次のリストには、Athena ノートブック API アクションへの参照リンクが含まれています。データ構造とその他の Athena API アクションについては、「[Amazon Athena API リファレンス](https://docs.aws.amazon.com/athena/latest/APIReference/)」を参照してください。
+ [CreateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateNotebook.html)
+ [CreatePresignedNotebookUrl](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreatePresignedNotebookUrl.html)
+ [DeleteNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_DeleteNotebook.html)
+ [ExportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ExportNotebook.html)
+ [GetCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecution.html)
+ [GetCalculationExecutionCode](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecutionCode.html)
+ [GetCalculationExecutionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetCalculationExecutionStatus.html)
+ [GetNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetNotebookMetadata.html)
+ [GetSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetSession.html)
+ [GetSessionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_GetSessionStatus.html)
+ [ImportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ImportNotebook.html)
+ [ListApplicationDPUSizes](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListApplicationDPUSizes.html)
+ [ListCalculationExecutions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListCalculationExecutions.html)
+ [ListExecutors](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListExecutors.html)
+ [ListNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListNotebookMetadata.html)
+ [ListNotebookSessions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListNotebookSessions.html)
+ [ListSessions](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListSessions.html)
+ [StartCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartCalculationExecution.html)
+ [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html)
+ [StopCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StopCalculationExecution.html)
+ [TerminateSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_TerminateSession.html)
+ [UpdateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebook.html)
+ [UpdateNotebookMetadata](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebookMetadata.html)
# Athena for Spark をトラブルシューティングする
次の情報を使用して、Athena でノートブックとセッションを使用するときに発生する可能性のある問題をトラブルシューティングします。
**Topics**
+ [Athena for Spark で発生している既知の問題について説明します](notebooks-spark-known-issues.md)
+ [Spark 対応ワークグループをトラブルシューティングする](notebooks-spark-troubleshooting-workgroups.md)
+ [Spark EXPLAIN ステートメントを使用して Spark SQL をトラブルシューティングする](notebooks-spark-troubleshooting-explain.md)
+ [Athena での Spark アプリケーションイベントをログに記録する](notebooks-spark-logging.md)
+ [CloudTrail を使用して Athena ノートブック API 呼び出しをトラブルシューティングする](notebooks-spark-troubleshooting-cloudtrail.md)
+ [68,000 というコードブロックサイズの制限に対処する](notebooks-spark-troubleshooting-code-block-size-limit.md)
+ [セッションエラーをトラブルシューティングする](notebooks-spark-troubleshooting-sessions.md)
+ [テーブルエラーをトラブルシューティングする](notebooks-spark-troubleshooting-tables.md)
+ [サポートを受ける](notebooks-spark-troubleshooting-support.md)
# Athena for Spark で発生している既知の問題について説明します
このページでは、Athena for Apache Spark に関する既知の問題についていくつか説明します。
## テーブル作成時の不正な引数の例外
Spark では空のロケーションプロパティを使用して AWS Glue にデータベースを作成することはできませんが、Spark の外部で作成されたデータベースには、空の `LOCATION` プロパティを設定できます。
テーブルを作成し、空の `LOCATION` フィールドがを持つ AWS Glue データベースを指定すると、次の「IllegalArgumentException: Cannot create a path from an empty string」(IllegalArgumentException: 空の文字列からパスを作成することはできません) というような例外が発生する可能性があります。
例えば、次のコマンドは、AWS Glue のデフォルトデータベースに空の `LOCATION` フィールドが含まれている場合に例外をスローします。
```
spark.sql("create table testTable (firstName STRING)")
```
**推奨される解決策 A** - AWS Glue を使用して、使用しているデータベースに場所を追加します。
**AWS Glue データベースに場所を追加するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、**[Databases]** (データベース) を選択します。
1. データベースのリストで、編集するデータベースを選択します。
1. データベースの詳細ページで、**[Edit]** (編集) を選択します。
1. **[Update a database]** (データベースの更新) ページの **[Location]** (場所) に Amazon S3 の場所を入力します。
1. **[Update Database]** (データベースの更新) を選択します。
**推奨される解決策 B** - Amazon S3 に既存の有効な場所がある別の AWS Glue データベースを使用します。例えば、`dbWithLocation` という名前のデータベースがある場合は、コマンド `spark.sql("use dbWithLocation")` を使用してそのデータベースに切り替えます。
**推奨される解決法 C** - Spark SQL を使用してテーブルを作成する場合、次の例のように `location` の値を指定します。
```
spark.sql("create table testTable (firstName STRING)
location 's3://amzn-s3-demo-bucket/'").
```
**推奨される解決策 D** - テーブルを作成したときに場所を指定しても問題が解決しない場合は、指定する Amazon S3 パスの末尾にスラッシュが付いていることを確認してください。例えば、次のコマンドは不正な引数の例外をスローします。
```
spark.sql("create table testTable (firstName STRING)
location 's3://amzn-s3-demo-bucket'")
```
これを修正するには、場所の末尾にスラッシュを追加します (例: `'s3://amzn-s3-demo-bucket/'`)。
## ワークグループの場所に作成されたデータベース
データベースを作成するために、`spark.sql('create database db')` などのコマンドを使用してデータベースの場所を指定しない場合、Athena はワークグループの場所にサブディレクトリを作成し、その場所を新しく作成されたデータベースに使用します。
## AWS Glue デフォルトデータベースの Hive 管理対象テーブルに関する問題
AWS Glue のデフォルトデータベースの `Location` プロパティが空でなく、Amazon S3 内の有効な場所を指定している場合、Athena for Spark を使用して AWS Glue デフォルトデータベースに Hive 管理対象テーブルを作成すると、データは AWS Glue データベースで指定された場所ではなく、Athena Spark ワークグループで指定された Amazon S3 がある場所に書き込まれます。
この問題は、Apache Hive がデフォルトデータベースを処理する方法に起因しています。Apache Hive は、Hive ウェアハウスのルートロケーションにテーブルデータを作成します。このルートロケーションは、実際のデフォルトのデータベースロケーションとは異なる場合があります。
Athena for Spark を使用して AWS Glue のデフォルトデータベース内に Hive 管理対象テーブルを作成すると、AWS Glue テーブルのメタデータが 2 つの異なる場所を指すことがあります。これにより、`INSERT` または `DROP TABLE` 操作を試みたときに、予期しない動作が発生する可能性があります。
問題を再現する手順は次のとおりです。
1. Athena for Spark では、次の方法のうちの 1 つを選択して、Hive 管理対象テーブルを作成または保存します。
+ `CREATE TABLE $tableName` などの SQL ステートメント
+ Dataframe API で `path` オプションを指定しない、`df.write.mode("overwrite").saveAsTable($tableName)` などの PySpark コマンド
この時点で、AWS Glue コンソールに Amazon S3 のテーブルの場所が正しく表示されない場合があります。
1. Athena for Spark では、`DROP TABLE $table_name` ステートメントを使用して作成したテーブルをドロップします。
1. `DROP TABLE` ステートメントを実行すると、Amazon S3 下にあるファイルが依然として存在していることがわかります。
この問題を解決するには、次のいずれかを実行します。
**解決策 A** — Hive 管理対象テーブルを作成するときには、別の AWS Glue データベースを使用します。
**解決策 B** — AWS Glue のデフォルトデータベースに空の場所を指定します。次に、デフォルトのデータベースに管理対象テーブルを作成します。
## Athena for Spark と Athena SQL 間の CSV ファイル形式と JSON ファイル形式の非互換性
オープンソースである Spark に存在する既知の問題により、Athena for Spark で CSV データまたは JSON データのテーブルを作成すると、そのテーブルが Athena SQL からテーブルを読み取ることができない可能性があり、その逆の可能性もあります。
例えば、以下のうちのいずれかの方法で Athena for Spark にテーブルを作成したとします。
+ 次の `USING csv` 構文を使用する:
```
spark.sql('''CREATE EXTERNAL TABLE $tableName (
$colName1 $colType1,
$colName2 $colType2,
$colName3 $colType3)
USING csv
PARTITIONED BY ($colName1)
LOCATION $s3_location''')
```
+ 次の [DataFrame](https://spark.apache.org/docs/latest/api/python/reference/pyspark.sql/dataframe.html) API 構文を使用する:
```
df.write.format('csv').saveAsTable($table_name)
```
オープンソースである Spark には既知の問題があるため、結果テーブルに対して Athena SQL からクエリした場合に成功しない可能性があります。
**推奨される解決策** — Apache Hive 構文を使用して Athena for Spark でテーブルを作成してみてください。詳細については、Apache Hive ドキュメントの「[HIVEFORMAT テーブルを作成する](https://spark.apache.org/docs/latest/sql-ref-syntax-ddl-create-table-hiveformat.html)」を参照してください。
# Spark 対応ワークグループをトラブルシューティングする
次の情報を使用して、Athena の Spark 対応ワークグループのトラブルシューティングを行います。
## 既存の IAM ロールを使用すると、セッションは応答を停止する
Spark 対応のワークグループ用に新しい `AWSAthenaSparkExecutionRole` を作成せず、代わりに既存の IAM ロールを更新または選択した場合、セッションが応答しなくなる可能性があります。この場合、Spark 対応のワークグループ実行ロールに次の信頼ポリシーとアクセス許可ポリシーを追加する必要がある可能性があります。
以下の信頼ポリシーの例を追加します。このポリシーには、実行ロールに混同される代理チェックが含まれています。`111122223333`、`aws-region`、および `workgroup-name` の値を、AWS アカウント ID、AWS リージョン、使用しているワークグループに置き換えます。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "athena.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:athena:us-east-1:111122223333:workgroup/workgroup-name"
}
}
}
]
}
```
------
ノートブック対応のワークグループには、次のデフォルトポリシーのようなアクセス許可ポリシーを追加します。プレースホルダーの Amazon S3 ロケーションと AWS アカウント ID を使用しているロケーションに対応するように変更します。`amzn-s3-demo-bucket`、`aws-region`、`111122223333`、および `workgroup-name` の値を、Amazon S3 バケット、AWS リージョン、AWS アカウント ID および使用しているワークグループに置き換えます。
------
#### [ JSON ]
****
```
{ "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [
"s3:PutObject", "s3:ListBucket", "s3:DeleteObject", "s3:GetObject" ], "Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/*",
"arn:aws:s3:::amzn-s3-demo-bucket" ] }, { "Effect": "Allow",
"Action": [ "athena:GetWorkGroup", "athena:CreatePresignedNotebookUrl",
"athena:TerminateSession", "athena:GetSession", "athena:GetSessionStatus",
"athena:ListSessions", "athena:StartCalculationExecution", "athena:GetCalculationExecutionCode",
"athena:StopCalculationExecution", "athena:ListCalculationExecutions",
"athena:GetCalculationExecution", "athena:GetCalculationExecutionStatus",
"athena:ListExecutors", "athena:ExportNotebook", "athena:UpdateNotebook" ], "Resource":
"arn:aws:athena:us-east-1:111122223333:workgroup/workgroup-name"
}, { "Effect": "Allow", "Action": [ "logs:CreateLogStream", "logs:DescribeLogStreams",
"logs:CreateLogGroup", "logs:PutLogEvents" ], "Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:/aws-athena:*",
"arn:aws:logs:us-east-1:111122223333:log-group:/aws-athena*:log-stream:*"
] }, { "Effect": "Allow", "Action": "logs:DescribeLogGroups", "Resource":
"arn:aws:logs:us-east-1:111122223333:log-group:*"
}, { "Effect": "Allow", "Action": [ "cloudwatch:PutMetricData" ], "Resource": "*", "Condition":
{ "StringEquals": { "cloudwatch:namespace": "AmazonAthenaForApacheSpark" } } } ] }
```
------
# Spark EXPLAIN ステートメントを使用して Spark SQL をトラブルシューティングする
Spark SQL により Spark `EXPLAIN` ステートメントを使用して、Spark コードのトラブルシューティングを行うことができます。次のコードと出力例は、この使用量を示しています。
**Example - Spark SELECT ステートメント**
```
spark.sql("select * from select_taxi_table").explain(True)
```
**出力**
```
Calculation started (calculation_id=20c1ebd0-1ccf-ef14-db35-7c1844876a7e) in
(session=24c1ebcb-57a8-861e-1023-736f5ae55386).
Checking calculation status...
Calculation completed.
== Parsed Logical Plan ==
'Project [*]
+- 'UnresolvedRelation [select_taxi_table], [], false
== Analyzed Logical Plan ==
VendorID: bigint, passenger_count: bigint, count: bigint
Project [VendorID#202L, passenger_count#203L, count#204L]
+- SubqueryAlias spark_catalog.spark_demo_database.select_taxi_table
+- Relation spark_demo_database.select_taxi_table[VendorID#202L,
passenger_count#203L,count#204L] csv
== Optimized Logical Plan ==
Relation spark_demo_database.select_taxi_table[VendorID#202L,
passenger_count#203L,count#204L] csv
== Physical Plan ==
FileScan csv spark_demo_database.select_taxi_table[VendorID#202L,
passenger_count#203L,count#204L]
Batched: false, DataFilters: [], Format: CSV,
Location: InMemoryFileIndex(1 paths)
[s3://amzn-s3-demo-bucket/select_taxi],
PartitionFilters: [], PushedFilters: [],
ReadSchema: struct
```
**Example - Spark データフレーム**
次の例では、Spark データフレームで `EXPLAIN` を使用する方法を示しています。
```
taxi1_df=taxi_df.groupBy("VendorID", "passenger_count").count()
taxi1_df.explain("extended")
```
**出力**
```
Calculation started (calculation_id=d2c1ebd1-f9f0-db25-8477-3effc001b309) in
(session=24c1ebcb-57a8-861e-1023-736f5ae55386).
Checking calculation status...
Calculation completed.
== Parsed Logical Plan ==
'Aggregate ['VendorID, 'passenger_count],
['VendorID, 'passenger_count, count(1) AS count#321L]
+- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,
extra#60,mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet
== Analyzed Logical Plan ==
VendorID: bigint, passenger_count: bigint, count: bigint
Aggregate [VendorID#49L, passenger_count#52L],
[VendorID#49L, passenger_count#52L, count(1) AS count#321L]
+- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,extra#60,
mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet
== Optimized Logical Plan ==
Aggregate [VendorID#49L, passenger_count#52L],
[VendorID#49L, passenger_count#52L, count(1) AS count#321L]
+- Project [VendorID#49L, passenger_count#52L]
+- Relation [VendorID#49L,tpep_pickup_datetime#50,tpep_dropoff_datetime#51,
passenger_count#52L,trip_distance#53,RatecodeID#54L,store_and_fwd_flag#55,
PULocationID#56L,DOLocationID#57L,payment_type#58L,fare_amount#59,extra#60,
mta_tax#61,tip_amount#62,tolls_amount#63,improvement_surcharge#64,
total_amount#65,congestion_surcharge#66,airport_fee#67] parquet
== Physical Plan ==
AdaptiveSparkPlan isFinalPlan=false
+- HashAggregate(keys=[VendorID#49L, passenger_count#52L], functions=[count(1)],
output=[VendorID#49L, passenger_count#52L, count#321L])
+- Exchange hashpartitioning(VendorID#49L, passenger_count#52L, 1000),
ENSURE_REQUIREMENTS, [id=#531]
+- HashAggregate(keys=[VendorID#49L, passenger_count#52L],
functions=[partial_count(1)], output=[VendorID#49L,
passenger_count#52L, count#326L])
+- FileScan parquet [VendorID#49L,passenger_count#52L] Batched: true,
DataFilters: [], Format: Parquet,
Location: InMemoryFileIndex(1 paths)[s3://amzn-s3-demo-bucket/
notebooks/yellow_tripdata_2016-01.parquet], PartitionFilters: [],
PushedFilters: [],
ReadSchema: struct
```
# Athena での Spark アプリケーションイベントをログに記録する
Athena ノートブックエディタでは、Jupyter、Spark、Python の標準ログが可能です。`df.show()` を使用して PySpark DataFrame のコンテンツを表示したり、`print("Output")` を使用してセル出力に値を表示したりできます。計算の `stdout`、`stderr`、および `results` 出力は Amazon S3 のクエリ結果バケットの場所に書き込まれます。
## Amazon CloudWatch への Spark アプリケーションイベントをログに記録する
Athena セッションでは、使用しているアカウントの [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) にログを書き込むこともできます。
### ログストリームとロググループを理解する
CloudWatch は、ログアクティビティをログストリームとロググループに整理します。
**ログストリーム** - CloudWatch ログストリーミングは、同じ出典を共有する一連のログイベントです。CloudWatch Logs でのログの各ソースで各ログストリームが構成されます。
**ロググループ** - CloudWatch ログで、ロググループは保持、モニタリング、アクセス制御について同じ設定を共有するログストリーミングのグループです。
1 つのロググループに属することができるログストリーミングの数に制限はありません。
Athena で初めてノートブックセッションを開始すると、次の例のように、Athena は Spark 対応のワークグループの名前を使用して CloudWatch にロググループを作成します。
```
/aws-athena/workgroup-name
```
このロググループは、少なくとも 1 つのログイベントを生成するセッションのエグゼキューターごとに 1 つのログストリームを受け取ります。エグゼキューターとは、ノートブックセッションが Athena にリクエストできる最小の計算単位です。CloudWatch では、ログストリームの名前はセッション ID とエグゼキューター ID で始まります。
CloudWatch ロググループとログストリームの詳細については、Amazon CloudWatch Logs ユーザーガイドの「[ロググループとログストリームの操作](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)」を参照してください。
### Athena for Spark の標準ロガーオブジェクトを使用する
Athena for Spark セッションでは、次の 2 つのグローバルスタンダードロガーオブジェクトを使用して、Amazon CloudWatch にログを書き込むことができます。
+ **athena\$1user\$1logger** - ログを CloudWatch にのみ送信します。このオブジェクトは、次の例のように、Spark アプリケーションの情報を CloudWatch に直接ログ記録する場合に使用します。
```
athena_user_logger.info("CloudWatch log line.")
```
この例では、次のようにログイベントを CloudWatch に書き込みます。
```
AthenaForApacheSpark: 2022-01-01 12:00:00,000 INFO builtins: CloudWatch log line.
```
+ **athena\$1shared\$1logger** - 同じログをサポート目的で CloudWatch および AWS と両方に送信します。このオブジェクトを使用して、次の例のように、トラブルシューティングのために AWS サービスチームとログを共有できます。
```
athena_shared_logger.info("Customer debug line.")
var = [...some variable holding customer data...]
athena_shared_logger.info(var)
```
この例では、`debug` の行と `var` の変数の値を CloudWatch Logs に記録し、各行のコピーを サポート に送信します。
**注記**
プライバシー保護のため、計算コードと結果は AWS と共有されません。サポート に表示する情報のみを書き込む `athena_shared_logger` への呼び出しを行ってください。
提供されているロガーは、[Apache Log4j](https://logging.apache.org/log4j/) を介してイベントを書き込み、このインターフェイスのログレベルを継承します。指定できるログレベル値は `DEBUG`、`ERROR`、`FATAL`、`INFO`、`WARN`、`WARNING` です。ロガーで対応する名前付き関数を使用して、これらの値を生成できます。
**注記**
名前 `athena_user_logger` または `athena_shared_logger` を再バインドしないでください。これを行うと、ログオブジェクトはセッションの残りの部分で CloudWatch に書き込むことができなくなります。
### 例: CloudWatch へのノートブックイベントをログに記録する
次の手順は、Athena ノートブックイベントを Amazon CloudWatch Logs にログ記録する方法を示しています。
**Athena ノートブックイベントを Amazon CloudWatch Logs にログ記録するには**
1. [Amazon Athena で Apache Spark を開始する](notebooks-spark-getting-started.md) に従って、一意の名前で Spark 対応のワークグループを Athena に作成します。このチュートリアルでは、ワークグループ名 `athena-spark-example` を使用します。
1. [ステップ 7: 独自のノートブックを作成する](notebooks-spark-getting-started.md#notebooks-spark-getting-started-creating-your-own-notebook) の手順に従ってノートブックを作成し、新しいセッションを開始します。
1. Athena ノートブックエディタの新しいノートブックセルに、次のコマンドを入力します。
```
athena_user_logger.info("Hello world.")
```
1. セルを実行します。
1. 次のいずれかを実行して、現在のセッション ID を取得します。
+ セル出力 (例: `... session=72c24e73-2c24-8b22-14bd-443bdcd72de4`) を表示します。
+ 新しいセルで、[マジック](notebooks-spark-magics.md)コマンド `%session_id` を実行します。
1. セッション ID を保存します。
1. ノートブックセッションの実行に使用しているのと同じ AWS アカウント で、[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) にある CloudWatch コンソールを開きます。
1. CloudWatch コンソールのナビゲーションペインで、**[Log groups]** (ロググループ) を選択します。
1. ロググループのリストで、次の例のように Spark 対応の Athena ワークグループの名前を持つロググループを選択します。
```
/aws-athena/athena-spark-example
```
**[Log streams]** (ログストリーム) セクションには、ワークグループの 1 つ以上のログストリームリンクのリストが含まれています。各ログストリーム名には、セッション ID、エグゼキューター ID、および一意の UUID がスラッシュ文字によって区切られています。
例えば、セッション ID が `5ac22d11-9fd8-ded7-6542-0412133d3177` であり、エグゼキューター ID が `f8c22d11-9fd8-ab13-8aba-c4100bfba7e2` の場合、ログストリームの名前は次の例のようになります。
```
5ac22d11-9fd8-ded7-6542-0412133d3177/f8c22d11-9fd8-ab13-8aba-c4100bfba7e2/f012d7cb-cefd-40b1-90b9-67358f003d0b
```
1. セッションのログストリームのログストリームを選択します。
1. **[Log events]** (イベントのログ) ページで、**[Message]** (メッセージ) 列を表示します。
実行したセルのログイベントは次のようになります。
```
AthenaForApacheSpark: 2022-01-01 12:00:00,000 INFO builtins: Hello world.
```
1. Athena ノートブックエディタに戻ります。
1. 新しいセルに、次のコードを入力します。このコードは変数を CloudWatch にログします。
```
x = 6
athena_user_logger.warn(x)
```
1. セルを実行します。
1. 同じログストリームの CloudWatch コンソールの **[Log events]** (ログイベント) ページに戻ります。
1. ログストリームには、次のようなメッセージを含むログイベントエントリが含まれるようになりました。
```
AthenaForApacheSpark: 2022-01-01 12:00:00,000 WARN builtins: 6
```
# CloudTrail を使用して Athena ノートブック API 呼び出しをトラブルシューティングする
ノートブック API 呼び出しのトラブルシューティングを行うため、Athena CloudTrail のログを調べて異常を調査したり、ユーザーが開始したアクションを発見したりできます。Athena での CloudTrail の使用についての詳細は、「[AWS CloudTrail を使用して Amazon Athena API コールのログを記録する](monitor-with-cloudtrail.md)」を参照してください。
次の例は、Athena ノートブック API に関する CloudTrail ログエントリを示しています。
## StartSession
次の例は、ノートブックの [StartSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartSession.html) イベントの CloudTrail ログを示しています。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "EXAMPLE_PRINCIPAL_ID:alias",
"arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
"accountId": "123456789012",
"accessKeyId": "EXAMPLE_KEY_ID",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn:aws:iam::123456789012:role/Admin",
"accountId": "123456789012",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2022-10-14T16:41:51Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2022-10-14T17:05:36Z",
"eventSource": "athena.amazonaws.com",
"eventName": "StartSession",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.10",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
"requestParameters": {
"workGroup": "notebook-workgroup",
"engineConfiguration": {
"coordinatorDpuSize": 1,
"maxConcurrentDpus": 20,
"defaultExecutorDpuSize": 1,
"additionalConfigs": {
"NotebookId": "b8f5854b-1042-4b90-9d82-51d3c2fd5c04",
"NotebookIframeParentUrl": "https://us-east-1.console.aws.amazon.com"
}
},
"notebookVersion": "KeplerJupyter-1.x",
"sessionIdleTimeoutInMinutes": 20,
"clientRequestToken": "d646ff46-32d2-42f0-94d1-d060ec3e5d78"
},
"responseElements": {
"sessionId": "a2c1ebba-ad01-865f-ed2d-a142b7451f7e",
"state": "CREATED"
},
"requestID": "d646ff46-32d2-42f0-94d1-d060ec3e5d78",
"eventID": "b58ce998-eb89-43e9-8d67-d3d8e30561c9",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
},
"sessionCredentialFromConsole": "true"
}
```
## TerminateSession
次の例は、ノートブックの [TerminateSession](https://docs.aws.amazon.com/athena/latest/APIReference/API_TerminateSession.html) イベントの CloudTrail ログを示しています。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "EXAMPLE_PRINCIPAL_ID:alias",
"arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
"accountId": "123456789012",
"accessKeyId": "EXAMPLE_KEY_ID",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn:aws:iam::123456789012:role/Admin",
"accountId": "123456789012",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2022-10-14T16:41:51Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2022-10-14T17:21:03Z",
"eventSource": "athena.amazonaws.com",
"eventName": "TerminateSession",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.11",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
"requestParameters": {
"sessionId": "a2c1ebba-ad01-865f-ed2d-a142b7451f7e"
},
"responseElements": {
"state": "TERMINATING"
},
"requestID": "438ea37e-b704-4cb3-9a76-391997cf42ee",
"eventID": "49026c5a-bf58-4cdb-86ca-978e711ad238",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
},
"sessionCredentialFromConsole": "true"
}
```
## ImportNotebook
次の例は、ノートブック [ImportNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_ImportNotebook.html) イベントの CloudTrail ログを示しています。セキュリティ上、一部のコンテンツは非表示になっています。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "EXAMPLE_PRINCIPAL_ID:alias",
"arn": "arn:aws:sts::123456789012:assumed-role/Admin/alias",
"accountId": "123456789012",
"accessKeyId": "EXAMPLE_KEY_ID",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn:aws:iam::123456789012:role/Admin",
"accountId": "123456789012",
"userName": "Admin"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2022-10-14T16:41:51Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2022-10-14T17:08:54Z",
"eventSource": "athena.amazonaws.com",
"eventName": "ImportNotebook",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.12",
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 Safari/537.36",
"requestParameters": {
"workGroup": "notebook-workgroup",
"name": "example-notebook-name",
"payload": "HIDDEN_FOR_SECURITY_REASONS",
"type": "IPYNB",
"contentMD5": "HIDDEN_FOR_SECURITY_REASONS"
},
"responseElements": {
"notebookId": "05f6225d-bdcc-4935-bc25-a8e19434652d"
},
"requestID": "813e777f-6dac-41f4-82a7-e99b7b33f319",
"eventID": "4abec837-143b-4458-9c1f-fa9fb88ab69b",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
},
"sessionCredentialFromConsole": "true"
}
```
## UpdateNotebook
次の例は、ノートブック [UpdateNotebook](https://docs.aws.amazon.com/athena/latest/APIReference/API_UpdateNotebook.html) イベントの CloudTrail ログを示しています。セキュリティ上、一部のコンテンツは非表示になっています。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "EXAMPLE_PRINCIPAL_ID:AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
"arn": "arn:aws:sts::123456789012:assumed-role/AWSAthenaSparkExecutionRole-om0yj71w5l/AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
"accountId": "123456789012",
"accessKeyId": "EXAMPLE_KEY_ID",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn:aws:iam::123456789012:role/service-role/AWSAthenaSparkExecutionRole-om0yj71w5l",
"accountId": "123456789012",
"userName": "AWSAthenaSparkExecutionRole-om0yj71w5l"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2022-10-14T16:48:06Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2022-10-14T16:52:22Z",
"eventSource": "athena.amazonaws.com",
"eventName": "UpdateNotebook",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.13",
"userAgent": "Boto3/1.24.84 Python/3.8.14 Linux/4.14.225-175.364.amzn2.aarch64 Botocore/1.27.84",
"requestParameters": {
"notebookId": "c87553ff-e740-44b5-884f-a70e575e08b9",
"payload": "HIDDEN_FOR_SECURITY_REASONS",
"type": "IPYNB",
"contentMD5": "HIDDEN_FOR_SECURITY_REASONS",
"sessionId": "9cc1ebb2-aac5-b1ca-8247-5d827bd8232f"
},
"responseElements": null,
"requestID": "baaba1d2-f73d-4df1-a82b-71501e7374f1",
"eventID": "745cdd6f-645d-4250-8831-d0ffd2fe3847",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
}
}
```
## StartCalculationExecution
次の例は、[StartCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartCalculationExecution.html) の CloudTrail ログを示しています。セキュリティ上、一部のコンテンツは非表示になっています。
```
{
"eventVersion": "1.08",
"userIdentity": {
"type": "AssumedRole",
"principalId": "EXAMPLE_PRINCIPAL_ID:AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
"arn": "arn:aws:sts::123456789012:assumed-role/AWSAthenaSparkExecutionRole-om0yj71w5l/AthenaExecutor-9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
"accountId": "123456789012",
"accessKeyId": "EXAMPLE_KEY_ID",
"sessionContext": {
"sessionIssuer": {
"type": "Role",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn:aws:iam::123456789012:role/service-role/AWSAthenaSparkExecutionRole-om0yj71w5l",
"accountId": "123456789012",
"userName": "AWSAthenaSparkExecutionRole-om0yj71w5l"
},
"webIdFederationData": {},
"attributes": {
"creationDate": "2022-10-14T16:48:06Z",
"mfaAuthenticated": "false"
}
}
},
"eventTime": "2022-10-14T16:52:37Z",
"eventSource": "athena.amazonaws.com",
"eventName": "StartCalculationExecution",
"awsRegion": "us-east-1",
"sourceIPAddress": "203.0.113.14",
"userAgent": "Boto3/1.24.84 Python/3.8.14 Linux/4.14.225-175.364.amzn2.aarch64 Botocore/1.27.84",
"requestParameters": {
"sessionId": "9cc1ebb2-aac5-b1ca-8247-5d827bd8232f",
"description": "Calculation started via Jupyter notebook",
"codeBlock": "HIDDEN_FOR_SECURITY_REASONS",
"clientRequestToken": "0111cd63-4fd0-4ad8-a738-fd350115fc21"
},
"responseElements": {
"calculationExecutionId": "82c1ebb4-bd08-e4c3-5631-a662fb2ff2c5",
"state": "CREATING"
},
"requestID": "1a107461-3f1b-481e-b8a2-7fbd524e2373",
"eventID": "b74dbd00-e839-4bd1-a1da-b75fbc70ab9a",
"readOnly": false,
"eventType": "AwsApiCall",
"managementEvent": true,
"recipientAccountId": "123456789012",
"eventCategory": "Management",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "athena.us-east-1.amazonaws.com"
}
}
```
# 68,000 というコードブロックサイズの制限に対処する
Athena for Spark には、計算コードのブロックサイズの上限が 68,000 文字という既知の制限があります。この制限を超えるコードブロックで計算を実行すると、次のエラーメッセージが表示されることがあります。
「codeBlock」の「...」は制約を満たすことができませんでした。メンバーの長さは 68,000 以下である必要があります
このエラーは、Athena コンソールのノートブックエディターで以下の画像のように表示されます。
![\[Athena ノートブックエディター上のコードブロックサイズのエラーメッセージ\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-troubleshooting-code-block-size-limit-1.png)
次の例のように、AWS CLI を使用して大きなコードブロックが含まれる計算を実行した場合にも、同じエラーが発生する場合があります。
```
aws athena start-calculation-execution \
--session-id "{SESSION_ID}" \
--description "{SESSION_DESCRIPTION}" \
--code-block "{LARGE_CODE_BLOCK}"
```
このコマンドでは、次のエラーメッセージが表示されます。
*\$1LARGE\$1CODE\$1BLOCK\$1*「codeBlock」の「...」は制約を満たすことができませんでした。メンバーの長さは 68,000 以下である必要があります
## 回避方法
この問題を回避するには、クエリや計算コードが含まれるファイルを Amazon S3 にアップロードします。次に、boto3 を使用してファイルを読み取り、SQL またはコードを実行します。
以下の例では、SQL クエリまたは Python コードが含まれるファイルが Amazon S3 にすでにアップロードされていることを前提としています。
### SQL 例
以下のコード例では、Amazon S3 バケットから `large_sql_query.sql` ファイルを読み取ってから、ファイルに含まれている大きなクエリを実行しています。
```
s3 = boto3.resource('s3')
def read_s3_content(bucket_name, key):
response = s3.Object(bucket_name, key).get()
return response['Body'].read()
# SQL
sql = read_s3_content('bucket_name', 'large_sql_query.sql')
df = spark.sql(sql)
```
### PySpark 例
以下のコード例では、Amazon S3 から `large_py_spark.py` ファイルを読み取ってから、ファイルに含まれている大きなコードブロックを実行しています。
```
s3 = boto3.resource('s3')
def read_s3_content(bucket_name, key):
response = s3.Object(bucket_name, key).get()
return response['Body'].read()
# PySpark
py_spark_code = read_s3_content('bucket_name', 'large_py_spark.py')
exec(py_spark_code)
```
# セッションエラーをトラブルシューティングする
このセクションの情報を使用して、セッションの問題をトラブルシューティングします。
セッション開始時にカスタム設定エラーが発生すると、Athena for Spark コンソールにエラーメッセージバナーが表示されます。セッション開始エラーをトラブルシューティングするには、セッション状態の変更やログ情報を確認できます。
## セッション状態の変更に関する情報を表示する
セッション状態の変更に関する詳細は、Athena ノートブックエディタまたは Athena API から取得できます。
**Athena コンソールでセッション状態情報を表示する方法**
1. Athena ノートブックエディタの右上にある **[セッション]** メニューから **[詳細を表示]** を選択します。
1. **[現在のセッション]** タブを表示します。**[セッション情報]** セクションには、セッション ID、ワークグループ、ステータス、状態変更理由などの情報が表示されます。
次の画面キャプチャ例は、Athena の Spark セッションエラーに関連して、**[セッション情報]** ダイアログボックスの **[状態変更の理由]** セクションに表示される情報を示しています。
![\[Athena for Spark コンソールで、セッション状態情報を確認します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/notebooks-spark-custom-jar-cfg-1.jpeg)
**Athena API を使用してセッション状態情報を表示する方法**
+ Athena API では、[SessionStatus](https://docs.aws.amazon.com/athena/latest/APIReference/API_SessionStatus.html) オブジェクトの `StateChangeReason` フィールドでセッション状態の変更情報を確認できます。
**注記**
セッションを手動で停止した後、またはアイドルタイムアウト (デフォルトは 20 分) 後にセッションが停止した場合には、**[StateChangeReason]** の値が [リクエストに従ってセッションを終了済み] に変わります。
## ログ記録を使用してセッション開始エラーをトラブルシューティングする
セッション開始時に発生するカスタム設定エラーは [Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) にログとして記録されます。CloudWatch Logs 内で `AthenaSparkSessionErrorLogger` からのエラーメッセージを検索し、失敗したセッションの開始をトラブルシューティングします。
Spark ログ記録の詳細については、「[Athena での Spark アプリケーションイベントをログに記録する](notebooks-spark-logging.md)」を参照してください。
Athena for Spark のトラブルシューティングセッションの詳細については、「[セッションエラーをトラブルシューティングする](#notebooks-spark-troubleshooting-sessions)」を参照してください。
## 特定のセッションの問題
このトピックの情報を使用して、一部の特定のセッションの問題をトラブルシューティングします。
### 異常状態のセッション
「Session in unhealthy state」(セッションが異常な状態です) というエラーメッセージが表示された場合。「Please create a new session」(新しいセッションを作成してください)、既存のセッションを終了してから、新しいセッションを作成してください。
### ノートブックサーバーへの接続を確立できませんでした
ノートブックを開くと、次のエラーメッセージが表示されることがあります。
```
A connection to the notebook server could not be established.
The notebook will continue trying to reconnect.
Check your network connection or notebook server configuration.
```
#### 原因
Athena がノートブックを開くと、Athena はセッションを作成し、署名済みのノートブックの URL を使用してノートブックに接続します。ノートブックへの接続には、WSS ([WebSocket セキュア](https://en.wikipedia.org/wiki/WebSocket)) プロトコルを使用します。
エラーは、次の原因で発生することがあります。
+ ローカルファイアウォール (会社全体のファイアウォールなど) が WSS トラフィックをブロックしています。
+ ローカルコンピュータ上のプロキシまたはアンチウイルスソフトウェアが WSS 接続をブロックしています。
#### ソリューション
`us-east-1` リージョンに次のような WSS 接続があるとします。
```
wss://94c2bcdf-66f9-4d17-9da6-7e7338060183.analytics-gateway.us-east-1.amazonaws.com/
api/kernels/33c78c82-b8d2-4631-bd22-1565dc6ec152/channels?session_id=
7f96a3a048ab4917b6376895ea8d7535
```
エラーを解決するには、次の戦略のいずれかを使用します。
+ ワイルドカードパターン構文を使用すると、AWS リージョン とAWS アカウント を経由するポート `443` の WSS トラフィックを一覧表示できます。
```
wss://*amazonaws.com
```
+ ワイルドカードパターン構文を使用すると、指定した AWS リージョン で 1 つの AWS リージョン と AWS アカウント を経由するポート `443` で WSS トラフィックを一覧表示できます。次の例では `us-east-1` を使用しています。
```
wss://*analytics-gateway.us-east-1.amazonaws.com
```
# テーブルエラーをトラブルシューティングする
このセクションの情報を使用して、Athena for Spark テーブルエラーのトラブルシューティングを行います。
## テーブルの作成時にパスエラーを作成できない
**エラーメッセージ**:「IllegalArgumentException: Cannot create a path from an empty string.」(IllegalArgumentException: 空の文字列からパスを作成することはできません)
**原因**: このエラーは、Athena の Apache Spark を使用してデータベースにテーブルを作成したときに、AWS Glue データベースのプロパティが空の `LOCATION` である場合に発生する可能性があります。
**推奨される解決策**: 詳細と解決策については、「[テーブル作成時の不正な引数の例外](notebooks-spark-known-issues.md#notebooks-spark-known-issues-illegal-argument-exception)」を参照してください。
## AWS Glue テーブルをクエリする場合の AccessDeniedException
**エラーメッセージ**:「pyspark.sql.utils.AnalysisException: Unable to verify existence of default database: com.amazonaws.services.glue.model.AccessDeniedException: User: arn:aws:sts::*aws-account-id*:assumed-role/AWSAthenaSparkExecutionRole-*unique-identifier*/AthenaExecutor-*unique-identifier* is not authorized to perform: glue:GetDatabase on resource: arn:aws:glue:*aws-region*:*aws-account-id*:catalog because no identity-based policy allows the glue:GetDatabase action (Service: AWSGlue; Status Code: 400; Error Code: AccessDeniedException; Request ID: *request-id*; Proxy: null)」(pyspark.sql.utils.AnalysisException: 次のデフォルトデータベースの存在を確認できません: com.amazonaws.services.glue.model.AccessDeniedException: ユーザー: arn:aws:sts::aws-account-id:assumed-role/AWSAthenaSparkExecutionRole-unique-identifier/AthenaExecutor-unique-identifier は実行を許可されていません: リソース上の glue:GetDatabase: arn:aws:glue:aws-region:aws-account-id:catalog ID ベースのポリシーでは glue:GetDatabase アクションが許可されていないため (サービス: AWSGlue、ステータスコード: 400、エラーコード: AccessDeniedException、リクエスト ID: request-id、プロキシ: null))
**原因**: Spark 対応ワークグループの実行ロールに、AWS Glue リソースにアクセスする許可がありません。
**推奨される解決策**: この問題を解決するには、実行ロールに AWS Glue リソースへのアクセスを許可し、Amazon S3 バケットポリシーを編集して実行ロールへのアクセスを許可します。
以下の手順では、これらのステップがさらに詳しく説明されています。
**実行ロールに AWS Glue リソースへのアクセス権を付与するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. コンソールのナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
![\[展開メニューを選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/nav-pane-expansion.png)
1. Athena コンソールのナビゲーションペインで、**[Workgroups]** (ワークグループ) をクリックします。
1. **[Workgroups]** (ワークグループ) ページで、表示するワークグループのリンクを選択します。
1. ワークグループの **[Overview Details]** (概要詳細) ページで、**[Role ARN]** (ロール ARN) リンクを選択します。このリンクは、IAM コンソールで Spark 実行ロールを開きます。
1. **[Permissions policies]** (アクセス許可ポリシー) セクションで、リンクされたロールポリシー名を選択します。
1. **[Edit policy]** (ポリシーの編集)、**[JSON]** の順に選択します。
1. ロールに AWS Glue アクセス許可を追加します。通常は、`glue:GetDatabase` および `glue:GetTable` アクションに対してアクセス許可を追加します。IAM ロールの設定の詳細については、IAM ユーザーガイドの「[IAM ID アクセス許可の追加と削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)」を参照してください。
1. [**ポリシーの確認**] を選択し、[**変更の保存**] を選択します。
1. Amazon S3 バケットポリシーを編集して、実行ロールへのアクセスを許可します。ロールには、バケットおよびバケット内のオブジェクトの両方へのアクセスを許可する必要があることに注意してください。手順については、Amazon Simple Storage Service ユーザーガイドの「[Amazon S3 コンソールを使用してバケットポリシーを追加する](https://docs.aws.amazon.com/AmazonS3/latest/userguide/add-bucket-policy.html)」を参照してください。
# サポートを受ける
AWS からの支援については、AWS マネジメントコンソール から **[Support]** (サポート)、**[Support Center]** (サポートセンター) の順に選択します。体験を円滑に進めるため、次の情報をご用意ください。
+ Athena クエリ ID
+ セッション ID
+ 計算 ID