# データソースに接続する
Amazon Athena を使用して、*データセット*内のさまざまな場所にさまざまな形式で保存されているデータをクエリすることができます。このデータセットは、CSV、JSON、Avro、Parquet、またはその他の形式である可能性があります。
クエリを実行するために Athena で使用するテーブルとデータベースは、*メタデータ*に基づいています。メタデータは、データセット内の基になるデータに関するデータです。このメタデータがデータセットを記述する方法を*スキーマ*と呼びます。たとえば、テーブル名、テーブル内の列名、各列のデータ型はメタデータとして保存され、基になるデータセットを記述するスキーマです。Athena では、メタデータを整理するためのシステムを、*データカタログ*または*メタストア*と呼んでいます。データセットとそれを記述するデータカタログの組み合わせを*データソース*と呼びます。
メタデータと基になるデータセットとの関係は、使用するデータソースの種類によって異なります。MySQL、PostgreSQL、SQL Server などのリレーショナルデータソースは、メタデータをデータセットと緊密に統合します。多くの場合これらのシステムでは、データが書き込まれるときにメタデータが書き込まれます。[Hive](https://hive.apache.org) を使用して構築されたものなどの他のデータソースでは、データセットを読み込むときにその場でメタデータを定義できます。データセットは、CSV、JSON、Parquet、または Avro など、さまざまな形式にすることができます。
Athena は AWS Glue Data Catalog をネイティブにサポートします。AWS Glue Data Catalog は、Amazon S3、Amazon Redshift、Amazon DynamoDB などの他のデータセットとデータソースの上に構築されたデータカタログです。Athena は、さまざまなコネクタを使用して他のデータソースに接続することも可能です。
**Topics**
+ [AWS Glue Data Catalog を使用してデータに接続する](data-sources-glue.md)
+ [Amazon Athena フェデレーティッドクエリを使用する](federated-queries.md)
+ [Athena で Amazon DataZone を使用する](datazone-using.md)
+ [外部の Hive メタストアを使用する](connect-to-data-source-hive.md)
+ [データソースを管理する](data-sources-managing.md)
# AWS Glue Data Catalog を使用してデータに接続する
Athena は、Amazon S3 に保存されているデータのテーブルおよび列の名前などのメタデータを保存するために AWS Glue Data Catalog を使用します。このメタデータ情報は、Athena クエリエディタに表示されるデータベース、テーブル、ビューになります。
Athena で AWS Glue Data Catalog を使用するときは、AWS Glue を使用して Athena でクエリされるデータベースとテーブル (スキーマ) を作成するか、Athena を使用してスキーマを作成してから AWS Glue や関連サービスでそれらを使用することができます。
AWS Glue のスキーマ情報を定義するには、Athena コンソールでフォームを使用するか、Athena でクエリエディタを使用するか、または AWS Glue コンソールで AWS Glue クローラーを作成します。AWS Glue クローラーは、Amazon S3 のデータからデータベースとテーブルスキーマを自動的に推論します。フォームを使用すると、よりカスタマイズできます。独自の `CREATE TABLE` ステートメントを記述するには、より多くの労力が必要ですが、最も強力なコントロールが得られます。詳細については、「[CREATE TABLE](create-table.md)」を参照してください。
## その他のリソース
+ AWS Glue Data Catalog に関する詳細については、「*AWS Glue デベロッパーガイド*」の「[AWS Glue のデータカタログおよびクローラー](https://docs.aws.amazon.com/glue/latest/dg/catalog-and-crawler.html)」を参照してください。
+ AWS Glue と Athena を使用して XML データを処理する方法については、「AWS Big Data Blog」の記事「[Process and analyze highly nested and large XML files using AWS Glue and Amazon Athena](https://aws.amazon.com/blogs/big-data/process-and-analyze-highly-nested-and-large-xml-files-using-aws-glue-and-amazon-athena/)」を参照してください。
+ AWS Glue には別料金が適用されます。詳細については、「[AWS Glue 料金表](https://aws.amazon.com/glue/pricing)」を参照してください。
**Topics**
+ [その他のリソース](#glue-additional-resources)
+ [Athena でデータカタログを登録して使用する](gdc-register.md)
+ [別のアカウントからデータカタログを登録する](data-sources-glue-cross-account.md)
+ [IAM ポリシーを使用してデータカタログへのアクセスを制御する](datacatalogs-iam-policy.md)
+ [Athena コンソールでフォームを使用して AWS Glue テーブルを追加する](data-sources-glue-manual-table.md)
+ [クローラーを使用してテーブルを追加する](schema-crawlers.md)
+ [AWS Glue パーティションのインデックス作成とフィルタリングでクエリを最適化する](glue-best-practices-partition-index.md)
+ [AWS CLI を使用して AWS Glue データベースとそのテーブルを再度作成する](glue-recreate-db-and-tables-cli.md)
+ [ETL ジョブのテーブルを作成する](schema-classifier.md)
+ [AWS Glue で CSV データを使用する](schema-csv.md)
+ [AWS Glue で地理空間データを使用する](schema-geospatial.md)
# Athena でデータカタログを登録して使用する
Athena は、複数のデータカタログへのマウントと接続をサポートしています。
+ Amazon Redshift データを AWS Glue Data Catalog にマウントし、データをコピーすることも移動することもなく Athena からクエリを実行できます。詳細については、「[Amazon Redshift データの AWS Glue Data Catalog への取り込み](https://docs.aws.amazon.com/lake-formation/latest/dg/managing-namespaces-datacatalog.html)」を参照してください。
+ AWS Glue 接続を使用して AWS Glue Data Catalog を外部データソースに接続し、フェデレーティッドカタログを作成して、Lake Formation を使用してきめ細かなアクセスコントロールでデータへのアクセス許可を一元管理します。詳細については、「[接続を Glue データカタログとして登録する](register-connection-as-gdc.md)」を参照してください。
+ Amazon S3 テーブルバケットからカタログを作成し、Lake Formation を使用してアクセス許可を一元管理し、テーブルバケット内のオブジェクトへのユーザーアクセスを制限します。詳細については、「Amazon S3 ユーザーガイド」の「[Amazon S3 Tables とテーブルバケットの使用](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables.html)」を参照してください。
**注記**
Glue カタログでは、`123412341234:my_catalog/my_child` のようなマルチレベルカタログのみを登録できます。`123412341234:linkcontainer` や `my_catalog` などの単一レベルのカタログを登録することはできません。単一レベルのカタログをクエリするには、Athena クエリで Glue データカタログを直接使用します。詳細については、「[Athena で AWS Glue データカタログをクエリする](gdc-register-query-the-data-source.md)」を参照してください。
**Topics**
+ [Redshift データカタログを Athena に登録する](gdc-register-rs.md)
+ [Athena でフェデレーティッドカタログを登録する](gdc-register-federated.md)
+ [Athena から S3 テーブルのバケットカタログを登録し、テーブルをクエリする](gdc-register-s3-table-bucket-cat.md)
+ [Athena で AWS Glue データカタログをクエリする](gdc-register-query-the-data-source.md)
# Redshift データカタログを Athena に登録する
Athena は、AWS Glue Data Catalog に登録されている Redshift クラスターまたはサーバーレス名前空間に保存されているデータの読み取りと書き込みができます。これは、AWS Lake Formation と連携して機能します。このサービスは、一元化されたセキュリティとガバナンスを提供し、さまざまなクエリエンジン間でデータアクセスが一貫して管理され、共有 Redshift データのきめ細かなアクセスコントロールを維持します。
## 考慮事項と制限事項
+ **マテリアライズドビュー** – Amazon Redshift マテリアライズドビューは Athena からクエリ可能ですが、Athena または Spark を使用したマテリアライズドビューの作成はサポートされていません。
+ AWS Glue Data Catalog の設定や Amazon Redshift マネージドストレージテーブルでのオペレーションを含む DDL オペレーションはサポートされていません。
## 前提条件
以下のタスクを完了するまでは、Athena から AWS Glue データカタログをクエリできません。
1. Amazon Redshift クラスターまたはサーバーレス名前空間を作成して AWS Glue Data Catalog に登録します。詳細については、「Amazon Redshift 管理ガイド」の「[クラスターを AWS Glue Data Catalog に登録する](https://docs.aws.amazon.com/redshift/latest/mgmt/register-cluster.html)」または「[名前空間を AWS Glue Data Catalog に登録する](https://docs.aws.amazon.com/redshift/latest/mgmt/serverless_datasharing-register-namespace.html)」を参照してください。
1. 登録された名前空間から AWS Lake Formation にデータカタログを作成します。詳細については、「AWS Lake Formation デベロッパーガイド」の「[Amazon Redshift フェデレーティッドカタログの作成](https://docs.aws.amazon.com/lake-formation/latest/dg/create-ns-catalog.html)」を参照してください。
1. (オプション) Lake Formation を使用して、カタログにきめ細かなアクセスコントロールを設定します。詳細については、「AWS Lake Formation デベロッパーガイド」の「[AWS Glue Data Catalog へのデータの取り込み](https://docs.aws.amazon.com/lake-formation/latest/dg/bring-your-data-overview.html)」を参照してください。
## Athena コンソールで Redshift データカタログを登録する
Redshift データカタログを Athena コンソールに登録するには、次の手順を実行します。
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) で Athena コンソールを開きます。
1. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. **[データソースを選択]** で、**[Amazon S3 - AWS Glue Data Catalog]** を選択します。
1. **[AWS Glue Data Catalog]** セクションの **[データソースアカウント]** で、**[このアカウントの AWS Glue Data Catalog]** を選択します。
1. **[テーブルの作成またはカタログの登録]** で、**[新しい AWS Glue カタログを登録]** を選択します。
1. **[データソースの詳細]** セクションの **[データソース名]** に、SQL クエリでデータソースを指定するために使用する名前を入力するか、生成されたデフォルト名を使用します。
1. **[カタログ]** で、**[参照]** を選択して、同じアカウントの AWS Glue カタログのリストを検索します。既存のカタログが表示されない場合は、[AWS Glue コンソール](https://console.aws.amazon.com/glue/)で作成します。
1. **[AWS Glue カタログを参照]** ダイアログボックスで、使用するカタログを選択し、**[選択]** を選択します。
1. (オプション) **[タグ]** では、データソースと関連付けるキーと値のペアがあれば入力します。
1. [**次へ**] を選択します。
1. **[確認と作成]** ページで、入力した情報が正しいことを確認し、**[データソースを作成]** を選択します。
# Athena でフェデレーティッドカタログを登録する
フェデレーティッドデータソースへの接続を作成したら、フェデレーティッドデータカタログとして登録してデータ検出を簡素化し、Lake Formation を使用してきめ細かなアクセス許可でデータアクセスを管理できます。詳細については、「[接続を Glue データカタログとして登録する](register-connection-as-gdc.md)」を参照してください。
## 考慮事項と制限事項
+ DDL オペレーションは、フェデレーティッドカタログではサポートされていません。
+ 次のコネクタを登録して AWS Glue と統合し、きめ細かなアクセスコントロールを行うことができます。
+ [Azure Data Lake Storage](connectors-adls-gen2.md)
+ [Azure Synapse](connectors-azure-synapse.md)
+ [BigQuery](connectors-bigquery.md)
+ [CMDB](connectors-cmdb.md)
+ [Db2](connectors-ibm-db2.md)
+ [Db2 iSeries](connectors-ibm-db2-as400.md)
+ [DocumentDB](connectors-docdb.md)
+ [DynamoDB](connectors-dynamodb.md)
+ [Google Cloud Storage](connectors-gcs.md)
+ [HBase](connectors-hbase.md)
+ [MySQL](connectors-mysql.md)
+ [OpenSearch](connectors-opensearch.md)
+ [Oracle](connectors-oracle.md)
+ [[PostgreSQL]](connectors-postgresql.md)
+ [Redshift](connectors-redshift.md)
+ [SAP HANA](connectors-sap-hana.md)
+ [Snowflake](connectors-snowflake.md)
+ [SQL Server](connectors-microsoft-sql-server.md)
+ [Timestream](connectors-timestream.md)
+ [TPC-DS](connectors-tpcds.md)
+ Glue 接続フェデレーションのリソースリンクを作成する場合、[リソースリンク](https://docs.aws.amazon.com/lake-formation/latest/dg/create-resource-link-database.html)の名前はプロデューサーのデータベース名と同じである必要があります。
+ 現在、データソースで大文字と小文字が区別されていない場合でも、小文字のテーブル名と列名のみが認識されます。
# Athena から S3 テーブルのバケットカタログを登録し、テーブルをクエリする
Amazon S3 テーブルバケットは、Amazon S3 のバケットの一種で、Apache Iceberg テーブルに表形式データを保存するために専用に構築されています。テーブルバケットは、圧縮、スナップショット管理、ガベージコレクションなどのテーブル管理タスクを自動化して、クエリのパフォーマンスを継続的に最適化し、コストを最小限に抑えます。Iceberg 環境を始めたばかりの場合でも、Iceberg 環境に何千ものテーブルがある場合でも、テーブルバケットはあらゆる規模でデータレイクを簡素化します。詳細については、「[Table buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets.html)」を参照してください。
## 考慮事項と制限事項
+ Iceberg テーブルでサポートされているすべての DDL オペレーションは、S3 Tables でもサポートされていますが、以下の例外があります。
+ `ALTER TABLE RENAME`、`CREATE VIEW`、`ALTER DATABASE` はサポートされていません。
+ `OPTIMIZE` および `VACUUM` – S3 で圧縮とスナップショットの管理を行うことができます。詳細については、「[S3 Tables のメンテナンスドキュメント](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-maintenance.html)」を参照してください。
+ Athena データソースとして登録された S3 Tables での DDL クエリはサポートされていません。
+ クエリ結果の再利用はサポートされていません。
+ SSE-KMS、CSE-KMS 暗号化が有効になっているワークグループでは、`INSERT`、`UPDATE`、`DELETE`、または `MERGE` などの書き込みオペレーションを S3 Tables で実行することはできません。
+ S3 リクエスタ支払いオプションが有効になっているワークグループでは、S3 Tables で DML オペレーションを実行できません。
## Athena から S3 Tables をクエリする
**Athena で S3 Tables をクエリする前に、以下の前提条件となる手順を実行する**
1. S3 テーブルバケットを作成します。詳細については、「Amazon Simple Storage Service ユーザーガイド」の「[テーブルバケットの作成](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets-create.html)」を参照してください。
1. テーブルバケットと AWS Glue Data Catalog の統合が成功していることを確認します。必要なアクセス許可とセットアップ手順については、「AWS Glue デベロッパーガイド」の「[S3 Tables 統合の前提条件](https://docs.aws.amazon.com/glue/latest/dg/s3tables-catalog-prerequisites.html)」および「[S3 Tables と Glue Data Catalog の統合の有効化](https://docs.aws.amazon.com/glue/latest/dg/enable-s3-tables-catalog-integration.html)」を参照してください。
1. Athena でクエリを実行するために使用されるプリンシパルには、次のいずれかのアプローチを使用して S3 Table カタログに対するアクセス許可を付与します。
**オプション 1: IAM アクセス許可を使用する**
IAM アクセスコントロールを使用する場合、プリンシパルには AWS Glue Data Catalog リソースと Amazon S3 Tables リソースの両方に対するアクセス許可が必要です。
次のリストには、Athena の S3 テーブルに対してサポートされている DDL または DML オペレーションを実行する上で必要なすべての `s3tables` アクセス許可が含まれています。
+ `s3tables:GetTableBucket`
+ `s3tables:GetNamespace`
+ `s3tables:GetTable`
+ `s3tables:GetTableData`
+ `s3tables:PutTableData`
+ `s3tables:ListNamespaces`
+ `s3tables:ListTables`
+ `s3tables:DeleteNamespace`
+ `s3tables:DeleteTable`
+ `s3tables:CreateNamespace`
+ `s3tables:CreateTable`
+ `s3tables:UpdateTableMetadataLocation`
これらのアクセス許可を特定の S3 テーブルバケットと S3 テーブルリソースに適用するか、`*` をリソースとして使用して、アカウント内のすべてのテーブルバケットとテーブルへのアクセスを許可します。これらのアクセス許可を [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 管理ポリシーと組み合わせて、完全な機能を有効にできます。
**オプション 2: Lake Formation アクセス許可を使用する**
または、きめ細かなアクセスコントロールを有効にするには、Lake Formation コンソールまたは AWS CLI を使用して、S3 Table カタログに対する Lake Formation アクセス許可を付与できます。これには、S3 テーブルバケットを Lake Formation データロケーションとして登録する必要があります。詳細については、「Lake Formation デベロッパーガイド」の「[AWS Glue Data Catalog での Amazon S3 Tables カタログの作成](https://docs.aws.amazon.com/lake-formation/latest/dg/create-s3-tables-catalog.html)」を参照してください。
------
#### [ AWS マネジメントコンソール ]
1. [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/) で AWS Lake Formation コンソールを開き、データレイク管理者としてサインインします。データレイク管理者の作成方法の詳細については、「[データレイク管理者を作成する](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)」を参照してください。
1. ナビゲーションペインで、**[データアクセス許可]**、**[付与]** の順に選択します。
1. **[アクセス許可の付与]** ページの **[プリンシパル]** で、Athena からクエリを送信するために使用するプリンシパルを選択します。
1. **[LF タグまたはカタログリソース]** で、**[名前付きのデータカタログリソース]** を選択します。
1. **[カタログ]** では、テーブルバケットの統合から作成したグルーデータカタログを選択します。例えば、**:s3tablescatalog/*amzn-s3-demo-bucket* です。
1. **[Catalog のアクセス許可]** で、**[Super]** を選択します。
1. **[付与]** を選択します。
------
#### [ AWS CLI ]
Lake Formation データレイク管理者ロールで次のコマンドを実行して、Athena からクエリを送信するために使用するプリンシパルへのアクセスを許可します。
```
aws lakeformation grant-permissions \
--region \
--cli-input-json \
'{
"Principal": {
"DataLakePrincipalIdentifier": ":role/ExampleRole>"
},
"Resource": {
"Catalog": {
"Id":":s3tablescatalog/amzn-s3-demo-bucket"
}
},
"Permissions": ["ALL"]
}'
```
------
**S3 Tables のクエリを送信する**
1. 上記で付与されたユーザー/ロールを使用して、Athena から `CREATE DATABASE` クエリを送信します。この例では、`s3tablescatalog` は統合から作成された親 Glue データカタログで、` s3tablescatalog/amzn-s3-demo-bucket` は各 S3 テーブルバケット用に作成された子 Glue データカタログです。クエリを実行する方法は 2 つあります。
------
#### [ Option 1 ]
コンソールまたは AWS CLI から直接、子 Glue データカタログ (`s3tablescatalog/amzn-s3-demo-bucket`) を指定します。
**AWS マネジメントコンソール の使用**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) で Athena コンソールを開きます。
1. 左側のナビゲーションで、**[データソース名]** に **[AwsDataCatalog]** を選択します。
1. **[カタログ]** に、**[s3tablescatalog/*amzn-s3-demo-bucket*]** を選択します。
1. クエリエディタで、`CREATE DATABASE test_namespace` のようなクエリを入力します。
**AWS CLI の使用**
以下のコマンドを実行してください。
```
aws athena start-query-execution \
--query-string 'CREATE DATABASE `test_namespace`' \
--query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket"}' \
--work-group "primary"
```
------
#### [ Option 2 ]
Athena コンソールで子 Glue データカタログから Athena データカタログを作成し、クエリでカタログとして指定します。詳細については、「[Athena データソースとして S3 テーブルバケットカタログを登録する](#gdc-register-s3-table-console-steps)」を参照してください。
------
1. 前のステップで作成したデータベースで、`CREATE TABLE` を使用してテーブルを作成します。次の例では、`s3tablescatalog/amzn-s3-demo-bucket` Glue カタログで以前に作成した *`test_namespace`* データベースにテーブルを作成します。
------
#### [ AWS マネジメントコンソール ]
1. 左側のナビゲーションで、**[データソース名]** に **[AwsDataCatalog]** を選択します。
1. **[カタログ]** に、**[s3tablescatalog/*amzn-s3-demo-bucket*]** を選択します。
1. **[データベース]** で **[test\$1namespace]** を選択します。
1. クエリエディタで、次のクエリを実行します。
```
CREATE TABLE daily_sales (
sale_date date,
product_category
string, sales_amount double)
PARTITIONED BY (month(sale_date))
TBLPROPERTIES ('table_type' = 'iceberg')
```
------
#### [ AWS CLI ]
以下のコマンドを実行してください。
```
aws athena start-query-execution \
--query-string "CREATE TABLE daily_sales (
sale_date date,
product_category
string, sales_amount double)
PARTITIONED BY (month(sale_date))
TBLPROPERTIES ('table_type' = 'iceberg')" \
--query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket", "Database":"test_namespace"}' \
--work-group "primary"
```
------
1. 前のステップで作成したテーブルにデータを挿入します。
------
#### [ AWS マネジメントコンソール ]
1. 左側のナビゲーションで、**[データソース名]** に **[AwsDataCatalog]** を選択します。
1. **[カタログ]** に、**[s3tablescatalog/*amzn-s3-demo-bucket*]** を選択します。
1. **[データベース]** で **[test\$1namespace]** を選択します。
1. クエリエディタで、次のクエリを実行します。
```
INSERT INTO daily_sales
VALUES
(DATE '2024-01-15', 'Laptop', 900.00),
(DATE '2024-01-15', 'Monitor', 250.00),
(DATE '2024-01-16', 'Laptop', 1350.00),
(DATE '2024-02-01', 'Monitor', 300.00);
```
------
#### [ AWS CLI ]
以下のコマンドを実行してください。
```
aws athena start-query-execution \
--query-string "INSERT INTO \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales
VALUES
(DATE '2024-01-15', 'Laptop', 900.00),
(DATE '2024-01-15', 'Monitor', 250.00),
(DATE '2024-01-16', 'Laptop', 1350.00),
(DATE '2024-02-01', 'Monitor', 300.00)"\
--work-group "primary"
```
------
1. テーブルにデータを挿入したら、クエリを実行できます。
------
#### [ AWS マネジメントコンソール ]
1. 左側のナビゲーションで、**[データソース名]** に **[AwsDataCatalog]** を選択します。
1. **[カタログ]** に、**[s3tablescatalog/*amzn-s3-demo-bucket*]** を選択します。
1. **[データベース]** で **[test\$1namespace]** を選択します。
1. クエリエディタで、次のクエリを実行します。
```
SELECT
product_category,
COUNT(*) AS units_sold,
SUM(sales_amount) AS total_revenue,
AVG(sales_amount) AS average_price
FROM
daily_sales
WHERE
sale_date BETWEEN DATE '2024-02-01'
AND DATE '2024-02-29'
GROUP BY
product_category
ORDER BY
total_revenue DESC
```
------
#### [ AWS CLI ]
以下のコマンドを実行してください。
```
aws athena start-query-execution \
--query-string "SELECT product_category,
COUNT(*) AS units_sold,
SUM(sales_amount) AS total_revenue,
AVG(sales_amount) AS average_price
FROM \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales
WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29'
GROUP BY product_category
ORDER BY total_revenue DESC"\
--work-group "primary"
```
------
## Athena で S3 Tables を作成する
Athena では、既存の S3 テーブル名前空間でのテーブルの作成、または Athena で `CREATE DATABASE` ステートメントを使用して作成された名前空間の作成がサポートされています。Athena から S3 テーブルを作成するには、次の例に示すように、`LOCATION` を指定しない点を除いて、[通常の Iceberg テーブルを作成する](querying-iceberg-creating-tables.md)場合と同じ構文を使用します。
```
CREATE TABLE
[db_name.]table_name (col_name data_type [COMMENT col_comment] [, ...] )
[PARTITIONED BY (col_name | transform, ... )]
[TBLPROPERTIES ([, property_name=property_value] )]
```
CREATE TABLE AS SELECT (CTAS) ステートメントを使用して S3 テーブルを作成することもできます。詳細については、「[S3 テーブル向けの CTAS](#ctas-s3-tables)」を参照してください。
## Athena データソースとして S3 テーブルバケットカタログを登録する
S3 テーブルバケットカタログを Athena コンソールに登録するには、次の手順を実行します。
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) で Athena コンソールを開きます。
1. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. **[データソースを選択]** で、**[Amazon S3 - AWS Glue Data Catalog]** を選択します。
1. **[AWS Glue Data Catalog]** セクションの **[データソースアカウント]** で、**[このアカウントの AWS Glue Data Catalog]** を選択します。
1. **[テーブルの作成またはカタログの登録]** で、**[新しい AWS Glue カタログを登録]** を選択します。
1. **[データソースの詳細]** セクションの **[データソース名]** に、SQL クエリでデータソースを指定するために使用する名前を入力するか、生成されたデフォルト名を使用します。
1. **[カタログ]** で、**[参照]** を選択して、同じアカウントの AWS Glue カタログのリストを検索します。既存のカタログが表示されない場合は、[AWS Glue コンソール](https://console.aws.amazon.com/glue/)で作成します。
1. **[AWS Glue カタログを参照]** ダイアログボックスで、使用するカタログを選択し、**[選択]** を選択します。
1. (オプション) **[タグ]** では、データソースと関連付けるキーと値のペアがあれば入力します。
1. [**次へ**] を選択します。
1. **[確認と作成]** ページで、入力した情報が正しいことを確認し、**[データソースを作成]** を選択します。
## S3 テーブル向けの CTAS
Amazon Athena で S3 テーブル向けの CREATE TABLE AS SELECT (CTAS) オペレーションが現在サポートされています。この機能を使用すると、SELECT クエリの結果に基づいて新しい S3 テーブルを作成できます。
S3 テーブルの CTAS クエリを作成する際には、標準の Athena テーブルと比べていくつかの重要な違いがあります。
+ S3 Tables は独自のストレージロケーションを自動的に管理するため、ロケーションプロパティを省略する必要があります。
+ `table_type` プロパティはデフォルトで `ICEBERG` になるため、クエリで明示的に指定する必要はありません。
+ 形式を指定しない場合、システムは自動的にデータのデフォルト形式として `PARQUET` を使用します。
+ 他のすべてのプロパティは、通常の Iceberg テーブルと同じ構文に従います。
CTAS を使用して S3 Tables を作成する前に、IAM または AWS Lake Formation で必要なアクセス許可が設定されていることを確認してください。具体的には、S3 Tables カタログにテーブルを作成するためのアクセス許可が必要です。これらのアクセス許可がないと、CTAS オペレーションは失敗します。
**注記**
CTAS クエリが失敗した場合、クエリを再実行する前に [S3 Tables API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-delete.html) を使用してテーブルの削除が必要な場合があります。Athena `DROP TABLE` ステートメントを使用して、クエリによって部分的に作成されたテーブルを削除することはできません。
**例**
```
CREATE TABLE "s3tablescatalog/amzn-s3-demo-bucket"."namespace"."s3-table-name"
WITH (
format = 'PARQUET'
)
AS SELECT *
FROM source_table;
```
# Athena で AWS Glue データカタログをクエリする
Athena からデータカタログをクエリするには、次のいずれかを実行します。
+ カタログをデータソースとして Athena に登録し、データソース名を使用してカタログをクエリします。この使用では、次のクエリは同等です。
```
SELECT * FROM my_data_source.my_database.my_table
```
+ Athena データソースとして登録されていないカタログをクエリする場合は、次の例のように、`SELECT` クエリでカタログへのフルパスを指定できます。
```
SELECT * FROM "my_catalog/my_subcatalog".my_database.my_table
```
+ これは、AWS マネジメントコンソール から実行することもできます。
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) で Athena コンソールを開きます。
1. クエリエディタの **[データソース]** で、**[AwsDataCatalog]** を選択します。
1. **[カタログ]** で、使用するカタログの名前を選択します。
1. **[データベース]** で、クエリするテーブルを含むデータベースを選択します。
1. `SELECT * FROM my_table` のようなクエリを入力し、**[実行]** を選択します。
# 別のアカウントからデータカタログを登録する
Athena のクロスアカウント AWS Glue カタログ機能を使用して、所有するアカウント以外のアカウントから AWS Glue カタログを登録できます。AWS Glue に必要な IAM アクセス許可を設定して、カタログを Athena `DataCatalog` リソースとして登録したら、Athena を使用してクロスアカウントクエリを実行できます。必要な許可の設定については、「[AWS Glue データカタログへのクロスアカウントアクセスを構成する](security-iam-cross-account-glue-catalog-access.md)」を参照してください。
以下の手順では、Athena を使用して、所有する Amazon Web Services アカウント以外のアカウントの AWS Glue Data Catalog をデータソースとして設定する方法を説明します。
## コンソールから登録する
1. 「[AWS Glue データカタログへのクロスアカウントアクセスを構成する](security-iam-cross-account-glue-catalog-access.md)」のステップに従って、他のアカウントのデータカタログをクエリする許可があることを確認します。
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. **[データソースとカタログ]** を選択します。
1. コンソールの右上で、**[Create data source]** (データソースの作成) を選択します。
1. **[Choose a data source]** (データソースを選択) ページの **[Data sources]** (データソース) で、**[S3 - AWS Glue Data Catalog]** (S3 – AWS Glue Data Catalog データカタログ) を選択してから、**[Next]** (次へ) を選択します。
1. **[Enter data source details]** (データソースの詳細を入力) ページの **[AWS Glue Data Catalog]** (AWS Glue Data Catalog データカタログ) セクションにある **[Choose an AWS Glue Data Catalog]** (AWS Glue Data Catalog データカタログを選択) で、**[AWS Glue Data Catalog in another account]** (別のアカウントの AWS Glue Data Catalog データカタログ) を選択します。
1. **[Data source details]** (データソースの詳細) に、以下の情報を入力します。
+ **[Data source name]** (データソース名) – 他のアカウントにあるデータカタログを参照するために SQL クエリで使用する名前を入力します。
+ **Description** (説明) – (オプション) 他のアカウントにあるデータカタログの説明を入力します。
+ **カタログ ID** – データカタログが属する Amazon Web Services アカウントの 12 桁のアカウント ID を入力します。Amazon Web Services アカウント ID はカタログ ID です。
1. (オプション) **[Tags]** (タグ) では、データソースと関連付けるキーと値のペアを入力します。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**次へ**] を選択します。
1. **[Review and create]** (確認と作成) ページで入力した情報を確認してから、**[Create data source]** (データソースの作成) を選択します。**[Data source details]** (データソースの詳細) ページに、登録したデータカタログのデータベースとタグがリストされます。
1. **[データソースとカタログ]** を選択します。登録したデータカタログは、**[Data source name]** (データソース名) 列にリストされています。
1. データカタログに関する情報を表示または編集するには、カタログを選択してから、**[Actions]** (アクション)、**[Edit]** (編集) の順に選択します。
1. 新しいデータカタログを削除するには、カタログを選択してから、**[Actions]** (アクション)、**[Delete]** (削除する) の順に選択します。
## API オペレーションを使用して登録する
1. 以下の `CreateDataCatalog` リクエストボディは、クロスアカウントアクセス用に AWS Glue カタログを登録します。
```
# Example CreateDataCatalog request to register a cross-account Glue catalog:
{
"Description": "Cross-account Glue catalog",
"Name": "ownerCatalog",
"Parameters": {"catalog-id" : "" # Owner's account ID
},
"Type": "GLUE"
}
```
1. 以下のサンプルコードは、Java クライアントを使用して `DataCatalog` オブジェクトを作成します。
```
# Sample code to create the DataCatalog through Java client
CreateDataCatalogRequest request = new CreateDataCatalogRequest()
.withName("ownerCatalog")
.withType(DataCatalogType.GLUE)
.withParameters(ImmutableMap.of("catalog-id", ""));
athenaClient.createDataCatalog(request);
```
これらのステップの後、借用者が [ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API オペレーションを呼び出すと、*`ownerCatalog`* が表示されます。
## AWS CLI を使用して登録する
次の CLI コマンド例を使用して、別のアカウントから AWS Glue Data Catalog を登録します。
```
aws athena create-data-catalog \
--name cross_account_catalog \
--type GLUE \
--description "Cross Account Catalog" \
--parameters catalog-id=
```
詳細については、*AWS Big Data Blog* の「[Query cross-account AWS Glue Data Catalogs using Amazon Athena](https://aws.amazon.com/blogs/big-data/query-cross-account-aws-glue-data-catalogs-using-amazon-athena/)」を参照してください。
# IAM ポリシーを使用してデータカタログへのアクセスを制御する
データカタログへのアクセスを制御するには、リソースレベルの IAM アクセス許可、またはアイデンティティベースの IAM ポリシーを使用します。
以下の手順は、Athena に固有の手順です。
IAM 固有の情報については、このセクションの最後に表示されているリンク先を参照してください。JSON データカタログポリシーの例については、「[データカタログポリシーの例](datacatalogs-example-policies.md)」を参照してください。
**IAM コンソールのビジュアルエディタを使用してデータカタログポリシーを作成する**
1. AWS マネジメントコンソール にサインインして、IAM コンソール ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)) を開きます。
1. 左側のナビゲーションペインで、[**Policies**] (ポリシー)、[**Create policy**] (ポリシーの作成) の順にクリックします。
1. [**Visual editor**] (ビジュアルエディタ) タブで、[**Choose a service**] (サービスの選択) をクリックします。次に、ポリシーに追加する Athena を選択します。
1. **[Select actions]** (アクションの選択) を選択し、ポリシーに追加するアクションを選択します。ビジュアルエディタが Athena で利用できるアクションを表示します。詳細については、「*サービス承認リファレンス*」の「[Amazon Athena のアクション、リソース、および条件キー](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)」を参照してください。
1. **[Add actions]** (アクションの追加) をクリックして特定のアクションを入力、またはワイルドカード (\$1) を使用して複数のアクションを指定します。
デフォルトでは、作成しているポリシーが選択するアクションを許可します。Athena 内の `datacatalog` リソースに対するリソースレベルのアクセス許可をサポートするアクションを 1 つ、または複数選択すると、エディタが `datacatalog` リソースをリストします。
1. **[リソース]** (リソース) をクリックして、ポリシーの特定のデータカタログを指定します。JSON データカタログポリシーの例については、「[データカタログポリシーの例](datacatalogs-example-policies.md)」を参照してください。
1. 以下のように `datacatalog` リソースを指定します。
```
arn:aws:athena:::datacatalog/
```
1. **[Review policy]** (ポリシーの確認) をクリックして、作成するポリシーの **[Name]** (名前) と **[Description**] (説明) (オプション) を入力します。ポリシー概要を確認して、意図したアクセス許可を付与したことを確認します。
1. [**Create Policy**] (ポリシーの作成) をクリックして、新しいポリシーを保存します。
1. このアイデンティティベースのポリシーをユーザー、グループ、またはロールにアタッチし、それらのユーザー、グループ、またはロールがアクセスできる `datacatalog` リソースを指定します。
詳細については、「*Service Authorization Reference*」と「*IAM ユーザーガイド*」に記載されている以下のトピックを参照してください。
+ [Amazon Athena のアクション、リソース、および条件キー](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonathena.html)
+ [ビジュアルエディタでのポリシーの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)
+ [IAM ポリシーの追加と削除](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
+ [リソースへのアクセスの制御](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html#access_controlling-resources)
JSON データカタログポリシーの例については、「[データカタログポリシーの例](datacatalogs-example-policies.md)」を参照してください。
AWS Glue のアクセス許可および AWS Glue クローラーのアクセス許可の詳細については、「*AWS Glue デベロッパーガイド*」の「[AWS Glue 用の IAM アクセス許可のセットアップ](https://docs.aws.amazon.com/glue/latest/dg/getting-started-access.html)」および「[クローラーの前提条件](https://docs.aws.amazon.com/glue/latest/dg/crawler-prereqs.html)」を参照してください。
Amazon Athena アクションの完全なリストについては、「[Amazon Athena API リファレンス](https://docs.aws.amazon.com/athena/latest/APIReference/)」の API アクション名を参照してください。
# データカタログポリシーの例
このセクションには、データカタログに対するさまざまなアクションを有効にするために使用できるポリシーの例が含まれています。
データカタログは、Athena によって管理されている IAM リソースです。そのため、データカタログポリシーで `datacatalog` を入力として取るアクションを使用する場合、データカタログの ARN を次のように指定する必要があります。
```
"Resource": [arn:aws:athena:::datacatalog/]
```
`` は、データカタログの名前です。例えば、`test_datacatalog` という名前のデータカタログの場合は、次のようにリソースとして指定します。
```
"Resource": ["arn:aws:athena:us-east-1:123456789012:datacatalog/test_datacatalog"]
```
Amazon Athena アクションの完全なリストについては、「[Amazon Athena API リファレンス](https://docs.aws.amazon.com/athena/latest/APIReference/)」の API アクション名を参照してください。IAM ポリシーの詳細については、「*IAM ユーザーガイド*」で「[ビジュアルエディタでのポリシーの作成](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-visual-editor)」を参照してください。ワークグループ用の IAM ポリシーの作成に関する詳細については、「[IAM ポリシーを使用してデータカタログへのアクセスを制御する](datacatalogs-iam-policy.md)」を参照してください。
+ [Example Policy for Full Access to All Data Catalogs](#datacatalog-policy-full-access-to-all-data-catalogs)
+ [Example Policy for Full Access to a Specified Data Catalog](#datacatalog-policy-full-access-to-a-specified-catalog)
+ [Example Policy for Querying a Specified Data Catalog](#datacatalog-policy-querying-a-specified-data-catalog)
+ [Example Policy for Management Operations on a Specified Data Catalog](#datacatalog-policy-management-operations-on-a-specified-catalog)
+ [Example Policy for Listing Data Catalogs](#datacatalog-policy-listing-data-catalogs)
+ [Example Policy for Metadata Operations on Data Catalogs](#datacatalog-policy-metadata-operations)
**Example すべてのデータカタログへの完全なアクセスのためのポリシー例**
以下のポリシーは、アカウントに存在している可能性があるすべてのデータカタログリソースへの完全なアクセスを許可します。アカウントの他のすべてのユーザーのデータカタログを管理する必要があるユーザーにこのポリシーを使用することをお勧めします。
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"athena:*"
],
"Resource":[
"*"
]
}
]
}
```
**Example 指定されたデータカタログへの完全なアクセスのためのポリシー例**
次のポリシーでは、`datacatalogA` という名前の 1 つの特定のデータカタログリソースへのフルアクセスを許可します。特定のデータカタログを完全に制御しているユーザーにこのポリシーを使用できます。
****
```
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[
"athena:ListDataCatalogs", "athena:ListWorkGroups", "athena:GetDatabase", "athena:ListDatabases",
"athena:ListTableMetadata", "athena:GetTableMetadata" ], "Resource":"*" }, { "Effect":"Allow",
"Action":[ "athena:StartQueryExecution", "athena:GetQueryResults", "athena:DeleteNamedQuery",
"athena:GetNamedQuery", "athena:ListQueryExecutions", "athena:StopQueryExecution",
"athena:GetQueryResultsStream", "athena:ListNamedQueries", "athena:CreateNamedQuery",
"athena:GetQueryExecution", "athena:BatchGetNamedQuery", "athena:BatchGetQueryExecution",
"athena:DeleteWorkGroup", "athena:UpdateWorkGroup", "athena:GetWorkGroup",
"athena:CreateWorkGroup" ], "Resource":[
"arn:aws:athena:us-east-1:123456789012:workgroup/*"
] }, { "Effect":"Allow", "Action":[ "athena:CreateDataCatalog", "athena:DeleteDataCatalog",
"athena:GetDataCatalog", "athena:GetDatabase", "athena:GetTableMetadata", "athena:ListDatabases",
"athena:ListTableMetadata", "athena:UpdateDataCatalog" ],
"Resource":"arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"
} ] }
```
**Example 指定されたデータカタログをクエリするためのポリシー例**
次のポリシーでは、ユーザーは指定した `datacatalogA` に対してクエリを実行することを許可されています。ユーザーは、データカタログの更新や削除など、データカタログ自体の管理タスクを実行することはできません。
****
```
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Action":[
"athena:StartQueryExecution" ], "Resource":[
"arn:aws:athena:us-east-1:123456789012:workgroup/*"
] }, { "Effect":"Allow", "Action":[ "athena:GetDataCatalog" ], "Resource":[
"arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"
] } ] }
```
**Example 指定されたデータカタログに対する管理オペレーションのためのポリシー例**
次のポリシーでは、ユーザーはデータカタログ `datacatalogA` の作成、削除、詳細の取得、および更新を許可されています。
****
```
{ "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [
"athena:CreateDataCatalog", "athena:GetDataCatalog", "athena:DeleteDataCatalog",
"athena:UpdateDataCatalog" ], "Resource": [
"arn:aws:athena:us-east-1:123456789012:datacatalog/datacatalogA"
] } ] }
```
**Example データカタログをリスト化するためのポリシー例**
以下のポリシーは、すべてのユーザーがすべてのデータカタログをリストアップすることを許可します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:ListDataCatalogs"
],
"Resource": "*"
}
]
}
```
**Example データカタログでのメタデータオペレーションのためのポリシー例**
以下のポリシーは、データカタログに対するメタデータオペレーションを許可します。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"athena:GetDatabase",
"athena:GetTableMetadata",
"athena:ListDatabases",
"athena:ListTableMetadata"
],
"Resource": "*"
}
]
}
```
# Athena コンソールでフォームを使用して AWS Glue テーブルを追加する
以下の手順で、テーブルの追加のために、Athena コンソールの **[Create Table From S3 bucket data]** (S3 バケットデータからテーブルを作成) フォームを使用する方法を説明します。
**フォームによりテーブルを追加してスキーマ情報を入力するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. クエリエディタで、**[Tables and views]** (テーブルとビュー) の横にある **[Create]** (作成) をクリックし、次に **[S3 bucket data]** (S3 バケットデータ) をクリックします。
1. **[Create Table From S3 bucket data]** (S3 バケットデータからテーブルを作成) フォームで、**[Table name]** (テーブル名) にテーブルの名前を入力します。Athena のデータベース名、テーブル名、および列名で使用できる文字については、「[データベース、テーブル、列に名前を付ける](tables-databases-columns-names.md)」を参照してください。
1. **[Database configuration]** (データベース設定) で既存のデータベースを選択するか、新しいデータベースを作成します。
1. **[Location of Input Data Set]** (入力データセットの場所) に、処理するデータセットが含まれるフォルダへの Amazon S3 のパスを指定します。パスにはファイル名を含めないでください。Athena で、指定したフォルダ内のすべてのファイルがスキャンされます。データが既に分割されている場合 (例:
s3://amzn-s3-demo-bucket/logs/year=2004/month=12/day=11/)、ベースパスのみを入力します (例: s3://amzn-s3-demo-bucket/logs/)。
1. **[Data Format]** (データ形式) で、次のオプションから選択します。
+ **[Table type]** (テーブルタイプ) には、**[Apache Hive]** (アパッチハイブ)、**[Apache Iceberg]** (アパッチアイスバーグ)、または **[Delta Lake]** (デルタレイク) を選択してください。Athena では Apache Hive テーブルタイプがデフォルトとして使用されます。Athena での Apache Iceberg テーブルのクエリについては、「[Apache Iceberg テーブルをクエリする](querying-iceberg.md)」を参照してください。Athena での Delta Lake テーブルの使用に関する情報は、「[Linux Foundation Delta Lake テーブルをクエリする](delta-lake-tables.md)」を参照してください。
+ **[File format]** (ファイル形式) で、データに適用されているファイル形式またはログ形式を選択します。
+ [**Text File with Custom Delimiters (カスタム区切り記号のあるテキストファイル)**] オプションでは、[**Field terminator (フィールドターミネータ)**]（列区切り記号）を指定します。オプションで、配列型の終わりを示す **[Collection terminator]** (コレクションターミネータ) またはマッピングデータタイプの終わりを示す **[Collection terminator]** (コレクションターミネータ) を指定できます。
+ **[SerDe library]** (SerDe ライブラリ) – SerDe (シリアライザー/デシリアライザー) ライブラリは特定のデータ形式を解析して、Athena でそのデータ形式のテーブルを作成できるようにします。ほとんどの形式では、デフォルトの SerDe ライブラリが自動的に選択されます。次の形式については、要件に応じてライブラリを選択してください。
+ **[Apache Web Logs]** (Apache ウェブログ) – **[RegexSerDe]** または **[GrokSerDe]** ライブラリのどちらかを選択します。RegexSerDe の場合は、**[Regex definition]** (Regex の定義) ボックスに正規表現を入力します。GrokSerDe の場合は、`input.format` SerDe プロパティに一連の名前付き正規表現を入力します。名前付き正規表現は、正規表現よりも読みやすく、管理しやすいです。詳細については、「[Amazon S3 に保存されている Apache ログをクエリする](querying-apache-logs.md)」を参照してください。
+ **[CSV]** – カンマ区切り (CSV) データに二重引用符で囲まれた値が含まれていない場合、または `java.sql.Timestamp` 形式を使用している場合は、**[LazySimpleSerDe]** を選択します。引用符で囲まれた部分がデータに含まれている場合や、`TIMESTAMP` に UNIX の数値形式 (例: `1564610311`) を使用している場合は、**[OpenCSVSerDe]** を選択します。詳細については、「[CSV、TSV、カスタム区切りファイル用の Lazy Simple SerDe](lazy-simple-serde.md)」および「[CSV を処理するための Open CSV SerDe](csv-serde.md)」を参照してください。
+ **[JSON]** – **[OpenX]** または **[Hive]** JSON SerDe ライブラリのどちらかを選択します。どちらの形式でも、各 JSON ドキュメントが、1 行のテキストに存在し、フィールドが改行文字で区切られていないことが想定されます。OpenX SerDe にはいくつかの追加プロパティがあります。これらのプロパティの詳細については、「[OpenX JSON SerDe](openx-json-serde.md)」を参照してください。Hive SerDe については、「[Hive JSON SerDe](hive-json-serde.md)」を参照してください。
Athena で SerDe ライブラリを使用する方法の詳細については、「[データ用に SerDe を選択する](supported-serdes.md)」を参照してください。
1. **[SerDe properties]** (SerDe プロパティ) で、使用している SerDe ライブラリと要件に従って、プロパティと値を追加、編集、または削除します。
+ SerDe プロパティを追加するには、**[Add SerDe property]** (SerDe プロパティを追加) を選択します。
+ **[Name]** (名前) フィールドに、プロパティの名前を入力します。
+ **[Value]** (値) フィールドに、プロパティの値を入力します。
+ SerDe プロパティを削除するには、**[Remove]** (削除) を選択します。
1. **[Table properties]** (テーブルプロパティ) で、要件に従ってテーブルプロパティを選択または編集します。
+ **[Write compression]** (書き込み圧縮) で、圧縮オプションを選択します。書き込み圧縮オプションが使用可能かどうかと、使用可能な圧縮オプションは、データ形式によって異なります。詳細については、「[Athena で圧縮を使用する](compression-formats.md)」を参照してください。
+ **[Encryption]** (暗号化) で、元のデータが Amazon S3 で暗号化されていれば **[Encrypted data set]** (暗号化されたデータセット) を選択します。このオプションで、`CREATE TABLE` ステートメント内の `has_encrypted_data` テーブルプロパティが true に設定されます。
1. **[Column details]** (列の詳細) に、テーブルに追加する列の名前とデータ型を入力します。
+ 列を 1 つずつ追加するには、[**Add a column (列の追加)**] を選択します。
+ すばやく列を追加するには、[**Bulk add columns (列を一括追加)**] を選択します。テキストボックスに、列のカンマ区切りのリストを *column\$1name**data\$1type*, *column\$1name**data\$1type*[, ...], の形式で入力し、**[Add]** (追加) を選択します。
1. (オプション) **[Partition details]** (パーティションの詳細) に、1 つ以上の列名とデータ型をそれぞれ追加します。パーティションでは、関連するデータが列の値に基づいてまとめられるため、クエリごとにスキャンされるデータ量を減らすことができます。パーティショニングについては、「[データのパーティション化](partitions.md)」を参照してください。
1. (オプション) **[Bucketing]** (バケット化) で、グループ化する行を含む 1 つまたは複数の列を指定し、それらの行を複数のバケットに入れることができます。これにより、バケット化された列の値が指定されている場合に、読み込むバケットのみをクエリできます。
+ **[Buckets]** (バケット) で、一意の値 (プライマリキーなど) が多く、クエリ内のデータのフィルタリングによく使用される列を 1 つまたは複数選択します。
+ **[Number of buckets]** (バケット数) に、ファイルを最適なサイズにすることができる数値を入力します。詳細については、AWS Big Data ブログの「[Amazon Athena のパフォーマンスチューニング Tips トップ 10](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)」を参照してください。
+ バケット列を指定するには、`CREATE TABLE` ステートメントで次の構文を使用します。
```
CLUSTERED BY (bucketed_columns) INTO number_of_buckets BUCKETS
```
**注記**
**[Bucketing]** (バケット化) オプションは、**[Iceberg]** テーブルタイプでは使用できません。
1. **[Preview table query]** (テーブルクエリのプレビュー) ボックスに、フォームで入力した情報を基に生成された `CREATE TABLE` ステートメントが表示されます。プレビューでのステートメントを、直接編集することはできません。ステートメントを変更するには、プレビューの上にあるフォームのフィールドを変更します。あるいは、フォームを使用する代わりに、クエリエディタで[ステートメントを直接作成](creating-tables-how-to.md#to-create-a-table-using-hive-ddl)します。
1. **[Create table]** (テーブルの作成) をクリックして、そこで生成されたステートメントをクエリエディタ内で実行し、テーブルを作成します。
# クローラーを使用してテーブルを追加する
AWS Glue クローラを使用すると、データセットのスキーマを検出して AWS Glue Data Catalog に登録できます。クローラは、データを参照しスキーマの判定を行います。さらに、パーティションを検出して登録することもできます。詳細については、「AWS Glue デベロッパーガイド」の「[クローラの定義](https://docs.aws.amazon.com/glue/latest/dg/add-crawler.html)」を参照してください。正常にクロールされたデータのテーブルは Athena からクエリできます。
**注記**
Athena は、AWS Glue クローラに指定した[除外パターン](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)を認識しません。例えば、`.csv` と `.json` ファイルの両方が含まれる Amazon S3 バケットがある場合、`.json` ファイルをクローラーから除外しても、Athena は両方のファイルのグループをクエリします。これを回避するには、除外するファイルを別の場所に配置します。
## AWS Glue クローラーを作成する
クローラの作成には、まず Athena コンソールを起動し、それと合わせて AWS Glue コンソールを使用します。クローラーを作成する際には、Amazon S3 内にあるクロール対象のデータの場所を指定します。
**Athena コンソールから AWS Glue のクローラを作成するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. クエリエディタの **[Tables and views]** (テーブルとビュー) の横にある **[Create]** (作成) を選択し、その後 **[AWS Glue crawler]** を選択します。
1. **AWS Glue** コンソールの [**Add crawler (クローラの追加)**] ページで、次の手順に従いクローラを作成します。詳細については、このガイドの「[AWS Glue クローラの使用](#schema-crawlers)」、ならびに「*AWS Glue デベロッパーガイド*」の「[AWS Glue Data Catalog の入力](https://docs.aws.amazon.com/glue/latest/dg/populate-catalog-methods.html)」を参照してください。
**注記**
Athena は、AWS Glue クローラに指定した[除外パターン](https://docs.aws.amazon.com/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)を認識しません。例えば、`.csv` と `.json` ファイルの両方が含まれる Amazon S3 バケットがある場合、`.json` ファイルをクローラーから除外しても、Athena は両方のファイルのグループをクエリします。これを回避するには、除外するファイルを別の場所に配置します。
AWS Glue クローラは、クロール後に、Apache Hive、Presto、Spark などの他の外部テクノロジーに準拠するために特定のテーブルメタデータを自動的に割り当てます。時折、このクローラが割り当てるメタデータプロパティが正しくないことがあります。正しくないプロパティは、Athena でテーブルをクエリする前に、AWS Glue で手動で修正してください。詳細については、「AWS Glue デベロッパーガイド」の「[テーブルの詳細の表示と編集](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)」を参照してください。
CSV ファイルの各データフィールドが引用符で囲まれている場合、AWS Glue は `serializationLib` プロパティを誤解してメタデータの割り当てを間違える場合があります。詳細については、「[引用符で囲まれた CSV データの処理](schema-csv.md#schema-csv-quotes)」を参照してください。
# クローラーで複数のデータソースを使用する
AWS Glue クローラが Amazon S3 をスキャンして複数のディレクトリを検出すると、ヒューリスティックを使用してテーブルのルートがディレクトリ構造内のどこにあり、どのディレクトリがテーブルのパーティションであるかを判断します。複数のディレクトリで同様のスキーマが検出されると、クローラは、これらを個別のテーブルではなくパーティションとみなす場合があります。クローラで個別のテーブルを検出しやすくするには、1 つの方法として各テーブルのルートディレクトリをクローラのデータストアとして追加します。
以下の Amazon S3 のパーティションは、その一例です。
```
s3://amzn-s3-demo-bucket/folder1/table1/partition1/file.txt
s3://amzn-s3-demo-bucket/folder1/table1/partition2/file.txt
s3://amzn-s3-demo-bucket/folder1/table1/partition3/file.txt
s3://amzn-s3-demo-bucket/folder1/table2/partition4/file.txt
s3://amzn-s3-demo-bucket/folder1/table2/partition5/file.txt
```
`table1` と `table2` のスキーマが類似し、AWS Glue のデータソースが `s3://amzn-s3-demo-bucket/folder1/` に対して 1 つのみ設定されている場合、クローラは 1 つのテーブルを 2 つのパーティション列で作成することがあります。1 つのパーティション列に `table1` と `table2` が入り、別のパーティション列に `partition1`〜`partition5` が入ります。
AWS Glue クローラで 2 つのテーブルを別個に作成するには、クローラに 2 つのデータソース (`s3://amzn-s3-demo-bucket/folder1/table1/` と `s3://amzn-s3-demo-bucket/folder1/table2`) を設定します。以下に手順を示します。
**AWS Glue で既存のクローラーに S3 データストアを追加するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、[**Crawlers (クローラ) **] を選択します。
1. クローラーへのリンクを選択してから、[**編集**] を選択します。
1. [**ステップ 2: データソースと分類子を選択する**] で、[**編集**] を選択します。
1. **[データソースとカタログ]** で、**[データソースを追加]** を選択します。
1. [**Add data source**] (データソースの追加) ダイアログボックスの [**S3 path**] (S3 パス) で、[**Browse**] (ブラウズ) を選択します。
1. 使用したいバケットを選択し、[**Choose**] (選択) を選択します。
追加したデータソースは、[**Data sources** ] (データソース) リストに表示されます。
1. [**次へ**] を選択します。
1. [**Configure security settings**] (セキュリティ設定の構成) ページで、クローラーの IAM ロールを選択してから、[**Next**] (次へ) を選択します。
1. S3 パスの末尾がスラッシュで終わっていることを確認し、[**Add an S3 data source**] (S3 データソースの追加) を選択します。
1. [**Set output and scheduling**] (出力とスケジュールの設定) ページの、[**Output configuration**] (出力の設定) で、ターゲットデータベースを選択します。
1. [**次へ**] を選択します。
1. [**Review and update**] (確認と更新) ページで、選択した内容を確認します。ステップを編集するには、[**Edit**] (編集) を選択します。
1. **[更新]** を選択します。
# クローラーをスケジュールして、AWS Glue Data Catalog と Amazon S3 の同期を保つ
AWS Glue クローラは、スケジュールに従って実行するか、オンデマンドで実行するように設定できます。詳細については、「AWS Glue デベロッパーガイド」の「[ジョブとクローラの時間ベースのスケジュール](https://docs.aws.amazon.com/glue/latest/dg/monitor-data-warehouse-schedule.html)」を参照してください。
パーティションテーブルのデータが定時に着信する場合は、スケジュールに従って実行するように AWS Glue クローラを設定し、テーブルのパーティションを検出して更新できます。これにより、時間と費用がかかる可能性がある `MSCK REPAIR` コマンドを実行したり、`ALTER TABLE ADD PARTITION` コマンドの手動で実行したりする必要がなくなります。詳細については、「AWS Glue デベロッパーガイド」の「[テーブルパーティション](https://docs.aws.amazon.com/glue/latest/dg/tables-described.html#tables-partition)」を参照してください。
# AWS Glue パーティションのインデックス作成とフィルタリングでクエリを最適化する
Athena は、パーティション分割されたテーブルに対しクエリを実行する際、クエリに関連するサブセットに使用可能なテーブルパーティションの取得とフィルタリングを行います。新しいデータとパーティションが追加されると、パーティションの処理に時間がかかり、クエリの実行時間が長くなる可能性があります。時間の経過とともに多数のテーブルが増加するパーティションの場合は、AWS Glue パーティションのインデックス作成とフィルタリングを使用することを検討してください。パーティションのインデックス作成により、Athena によるパーティション処理が最適化され、高度にパーティション化されたテーブルでのクエリパフォーマンスを向上させることができます。テーブルのプロパティでのパーティションフィルタリングの設定は、以下 2 つのステップで行います。
1. AWS Glue でのパーティションインデックスの作成。
1. テーブルのパーティションフィルタリングの有効化。
## パーティションインデックスの作成
AWS Glue でのパーティションインデックス作成のステップについては、「AWS Glue デベロッパーガイド」の「[パーティションインデックスの使用](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html)」を参照してください。AWS Glue でのパーティションインデックスの制限については、同じページの「[パーティションインデックスについて](https://docs.aws.amazon.com/glue/latest/dg/partition-indexes.html#partition-index-1)」セクションを参照してください。
## パーティションフィルタリングの有効化
テーブルのパーティションフィルタリングを有効にするには、AWS Glue で新しくテーブルのプロパティを設定する必要があります。AWS Glue でテーブルプロパティを設定する方法については、「[パーティション射影のセットアップ](https://docs.aws.amazon.com/athena/latest/ug/partition-projection-setting-up.html)」ページを参照してください。AWS Glue でテーブルの詳細設定を編集する際、**[Table properties]** (テーブルのプロパティ) セクションに、以下のキーと値のペアを追加します。
+ **[Key]** (キー) に `partition_filtering.enabled` を追加します。
+ **[Value]** (値) に `true` を追加します。
値 `partition_filtering.enabled` に `false` を設定することで、このテーブルのパーティションフィルタリングをいつでも無効にすることができます。
上記の各ステップを完了したら、Athena コンソールに戻ってデータをクエリできます。
パーティションのインデックス作成のフィルタリングの使用の詳細については、*AWS Big Data Blog* の「[Improve Amazon Athena query performance using AWS Glue Data Catalog partition indexes](https://aws.amazon.com/blogs/big-data/improve-amazon-athena-query-performance-using-aws-glue-data-catalog-partition-indexes/)」を参照してください。
# AWS CLI を使用して AWS Glue データベースとそのテーブルを再度作成する
AWS Glue データベースの名前を直接変更することはできませんが、その定義をコピーして定義を変更し、その定義を使用してデータベースを別の名前で再度作成することができます。同様に、古いデータベースのテーブルの定義をコピーして、その定義を変更し、変更した定義を使用して新しいデータベースにテーブルを再度作成することができます。
**注記**
ここで示した方法では、テーブルのパーティショニングはコピーされません。
次の Windows での手順では、お客様の AWS CLI に JSON 出力が設定されていることを前提としています。AWS CLI のデフォルトの出力形式を変更するには、`aws configure` を実行します。
**AWS CLI を使用して AWS Glue データベースをコピーする方法**
1. コマンドプロンプトで次の AWS CLI コマンドを実行し、コピーする AWS Glue データベースの定義を取得します。
```
aws glue get-database --name database_name
```
`get-database` コマンドの詳細については、「[get-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-database.html)」を参照してください。
1. JSON 出力を、新しいデータベースの名前が付けられたファイル (例: `new_database_name.json`) としてデスクトップに保存します。
1. テキストエディタで `new_database_name.json` ファイルを開きます。
1. JSON ファイルで以下の手順を実行します。
1. 外側の `{ "Database":` エントリと、ファイルの最後にある対応する閉じ括弧 `}` を削除します。
1. `Name` エントリを新しいデータベース名に変更します。
1. `CatalogId` フィールドを削除します。
1. ファイルを保存します。
1. コマンドプロンプトで次の AWS CLI コマンドを実行し、変更したデータベース定義ファイルを使用して、新しい名前でデータベースを作成します。
```
aws glue create-database --database-input "file://~/Desktop\new_database_name.json"
```
`create-database` コマンドの詳細については、「[create-database](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-database.html)」を参照してください。ファイルから AWS CLI パラメータを読み込む方法の詳細については、「AWS Command Line Interface ユーザーガイド」の「[ファイルから AWS CLI パラメータを読み込む](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-file.html)」を参照してください。
1. 新しいデータベースが AWS Glue に作成されたことを確認するには、次のコマンドを実行します。
```
aws glue get-database --name new_database_name
```
これで、新しいデータベースにコピーするテーブルの定義を取得し、定義を変更して、変更した定義を使用して新しいデータベースにテーブルを再度作成する準備ができました。この手順でテーブル名は変更されません。
**AWS CLI を使用して AWS Glue テーブルをコピーする方法**
1. コマンドプロンプトで、次の AWS CLI コマンドを実行します。
```
aws glue get-table --database-name database_name --name table_name
```
`get-table` コマンドの詳細については、「[get-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/get-table.html)」を参照してください。
1. JSON 出力を、テーブルの名前が付けられたファイル (例: *table\$1name*.json) として Windows デスクトップに保存します。
1. テキストエディタで ファイルを開きます。
1. JSON ファイルで、外部 `{"Table": ` エントリとファイルの最後にあるそれに対応する閉じ括弧 `}` を削除します。
1. JSON ファイルで、次のエントリとその値を削除します。
+ `DatabaseName` — `create-table` CLI コマンドは `--database-name` パラメータを使用するため、このエントリは必要ありません。
+ `CreateTime`
+ `UpdateTime`
+ `CreatedBy`
+ `IsRegisteredWithLakeFormation`
+ `CatalogId`
+ `VersionId`
1. テーブル定義ファイルを保存します。
1. コマンドプロンプトで次の AWS CLI コマンドを実行し、新しいデータベースにテーブルを再度作成します。
```
aws glue create-table --database-name new_database_name --table-input "file://~/Desktop\table_name.json"
```
`create-table` コマンドの詳細については、「[create-table](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/glue/create-table.html)」を参照してください。
これで、テーブルが AWS Glue の新しいデータベースに表示され、Athena からクエリできるようになりました。
1. 手順を繰り返して、追加する各テーブルを AWS Glue の新しいデータベースにコピーします。
# ETL ジョブのテーブルを作成する
Athena を使用して、AWS Glue が ETL ジョブに使用できるテーブルを作成できます。AWS Glue ジョブは ETL オペレーションを実行します。AWS Glue ジョブは、ソースからデータを抽出し、そのデータを変換してターゲット内にロードするためのスクリプトを実行します。詳細については、[AWS デベロッパーガイド](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)の「*AWS Glue Glue でのジョブの作成*」を参照してください。
## AWS Glue ETL ジョブ用の Athena テーブルの作成
Athena 内で作成するテーブルには、データの形式を識別する `classification` と呼ばれるテーブルプロパティが追加されている必要があります。これにより、AWS Glue はテーブルを ETL ジョブに使用できます。分類値は `avro`、`csv`、`json`、`orc`、`parquet` または `xml` です。Athena での `CREATE TABLE` ステートメントの例は、以下のとおりです。
```
CREATE EXTERNAL TABLE sampleTable (
column1 INT,
column2 INT
) STORED AS PARQUET
TBLPROPERTIES (
'classification'='parquet')
```
`classification` テーブルプロパティは、テーブルの作成時に追加しなかった場合、AWS Glue コンソールを使用して追加できます。
**AWS Glue コンソールを使用して分類テーブルプロパティを追加するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. コンソールのナビゲーションペインで、[**Tables**] (テーブル) を選択します。
1. 編集するテーブルのリンクを選択した後、**[Action]** (アクション)、**[Edit table]** (テーブルの編集) の順に選択します。
1. [**Table properties**] (テーブルプロパティ) セクションまで、下にスクロールします。
1. **[Add]** (追加) を選択します。
1. **[Key]** (キー) に「**classification**」と入力します。
1. [**Value**] (値) に、データタイプを入力します（例:**json**)。
1. **[保存]** を選択します。
[**Table details**] (テーブルの詳細) セクションで、入力したデータタイプがテーブルの [**Classification**] (分類) フィールドに表示されます。
詳細については、「AWS Glue デベロッパーガイド」の「[テーブルの使用](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html)」を参照してください。
## ETL ジョブを使用してクエリパフォーマンスを最適化する
AWS Glue ジョブは、Athena でのクエリパフォーマンスが最適化されるような形式にデータを変換するのに役立ちます。データの形式は、Athena でのクエリパフォーマンスとクエリコストに大きな影響を及ぼします。
AWS Glue は、Parquet および ORC データ形式への書き込みをサポートしています。この機能を使用して、Athena で利用するためにデータを変換できます。Parquet と ORC の使用、および Athena でパフォーマンスを改善する他の方法の詳細については、「[Amazon Athena のパフォーマンスチューニング Tips トップ 10](https://aws.amazon.com/blogs/big-data/top-10-performance-tuning-tips-for-amazon-athena/)」を参照してください。
**注記**
Athena が AWS Glue ETL ジョブによって生成された `SMALLINT` および `TINYINT` データ型を読み取れなくなる可能性を低くするには、データを ORC に変換する ETL ジョブを作成する際に `SMALLINT` と `TINYINT` を `INT` に変換します。
## ETL のために AWS Glue ジョブを自動化する
AWS Glue ETL ジョブは、トリガーに基づいて自動的に実行するように設定できます。この機能は、AWS 外からのデータが、Athena でのクエリのために最適とは言えない形式で Amazon S3 バケットにプッシュされている場合に適しています。詳細については、「AWS Glue デベロッパーガイド」の「[AWS Glue ジョブのトリガー](https://docs.aws.amazon.com/glue/latest/dg/trigger-job.html)」を参照してください。
# AWS Glue で CSV データを使用する
このページでは、AWS Glue を使用して、各列のデータ値を引用符で囲んだ CSV ファイルまたはヘッダー値を含む CSV ファイルからスキーマを作成する方法について説明します。
## 引用符で囲まれた CSV データの処理
次の例のように、CSV ファイルに二重引用符で囲まれたデータフィールドがあるとします。
```
"John","Doe","123-555-1231","John said \"hello\""
"Jane","Doe","123-555-9876","Jane said \"hello\""
```
引用符で囲まれた値を持つ CSV ファイルから作成されたテーブルに対して Athena でクエリを実行するには、AWS Glue で、OpenCSVSerDe を使用するようにテーブルプロパティを変更する必要があります。OpenCSV SerDe の詳細については、「[CSV を処理するための Open CSV SerDe](csv-serde.md)」を参照してください。
**AWS Glue コンソールでテーブルプロパティを編集するには**
1. AWS Glue コンソールのナビゲーションペインで、[**テーブル**] を選択します。
1. 編集するテーブルのリンクを選択した後、**[Action]** (アクション)、**[Edit table]** (テーブルの編集) の順に選択します。
1. [**Edit table**] (テーブルを編集) ページで、以下の変更を行います。
+ [**Serialization lib**] (シリアル化ライブラリ) には `org.apache.hadoop.hive.serde2.OpenCSVSerde` を入力します。
+ **[Serde parameters]** (Serde パラメータ) には、`escapeChar`、`quoteChar`、および `separatorChar` の各キーに以下の値を入力します。
+ `escapeChar` には、バックスラッシュ (**\$1**) を入力します。
+ `quoteChar` には、二重引用符 (**"**) を入力します。
+ `separatorChar` には、カンマ (**,**) を入力します。
1. [**Save**] を選択します。
詳細については、「AWS Glue デベロッパーガイド」の「[テーブルの詳細の表示と編集](https://docs.aws.amazon.com/glue/latest/dg/console-tables.html#console-tables-details)」を参照してください。
AWS Glue テーブルプロパティをプログラムで更新することもできます。次の JSON 例にあるように、テーブル定義内の `SerDeInfo` ブロックを変更するために、AWS Glue の [UpdateTable](https://docs.aws.amazon.com/glue/latest/webapi/API_UpdateTable.html) API オペレーション、または [update-table](https://docs.aws.amazon.com/cli/latest/reference/glue/update-table.html) AWS CLI コマンドを使用します。
```
"SerDeInfo": {
"name": "",
"serializationLib": "org.apache.hadoop.hive.serde2.OpenCSVSerde",
"parameters": {
"separatorChar": ","
"quoteChar": "\""
"escapeChar": "\\"
}
},
```
## ヘッダーを使用した CSV ファイルの処理
`CREATE TABLE` ステートメントを使用して Athena でテーブルを定義するときは、以下の例にあるように、`skip.header.line.count` テーブルプロパティを使用して CSV データ内のヘッダーを無視することができます。
```
...
STORED AS TEXTFILE
LOCATION 's3://amzn-s3-demo-bucket/csvdata_folder/';
TBLPROPERTIES ("skip.header.line.count"="1")
```
または、CSV のヘッダーを事前に削除して、ヘッダー情報が Athena のクエリ結果に含まれないようにすることもできます。そのためには、1 つの方法として AWS Glue ジョブを使用して ETL (抽出、変換、ロード) スクリプトを実行します。必要なスクリプトは、AWS Glue で PySpark Python ダイアレクトの拡張言語を使用して作成できます。詳細については、AWS Glue デベロッパーガイドの「[AWS Glue でのジョブの作成](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)」を参照してください。
次の例に示す AWS Glue スクリプトの関数では、`from_options` を使用して動的フレームを作成し、`writeHeader` フォーマットオプションを false に設定することで、ヘッダー情報を削除しています。
```
glueContext.write_dynamic_frame.from_options(frame = applymapping1, connection_type = "s3", connection_options = {"path": "s3://amzn-s3-demo-bucket/MYTABLEDATA/"}, format = "csv", format_options = {"writeHeader": False}, transformation_ctx = "datasink2")
```
# AWS Glue で地理空間データを使用する
AWS Glue は、Well-known Text (WKT)、Well-Known Binary (WKB)、またはその他の PostGIS データ型をネイティブにサポートしていません。AWS Glue 分類子は地理空間データを解析し、CSV 用の `varchar` など、形式でサポートされているデータ型を使用して分類します。他の AWS Glue テーブルと同様に、Athena がこれらのデータ型をそのまま解析できるよう、地理空間データから作成されたテーブルのプロパティ更新が必要になる場合があります。詳細については、「[クローラーを使用してテーブルを追加する](schema-crawlers.md)」および「[AWS Glue で CSV データを使用する](schema-csv.md)」を参照してください。Athena は、AWS Glue テーブルの一部の地理空間データ型をそのまま解析できない場合があります。Athena での地理空間データの操作の詳細については、「[地理空間データをクエリする](querying-geospatial-data.md)」を参照してください。
# Amazon Athena フェデレーティッドクエリを使用する
Amazon S3 以外のソースにデータがある場合は、Athena のフェデレーティッドクエリを使用してインプレースでデータをクエリしたり、複数のデータソースからデータを抽出して Amazon S3 に保存するパイプラインを構築したりすることができます。Athena のフェデレーティッドクエリでは、リレーショナル、非リレーショナル、オブジェクト、およびカスタムデータソースに保存されているデータの全体で SQL クエリを実行することができます。
Athena はフェデレーティッドクエリを実行するために、AWS Lambda で実行される*データソースコネクタ*を使用します。データソースコネクタは、ターゲットデータソースと Athena 間での変換を実行できるコードです。コネクタは、Athena のクエリエンジンの拡張機能として考えることができます。事前構築された Athena データソースコネクタは、Amazon CloudWatch Logs、Amazon DynamoDB、Amazon DocumentDB、Amazon RDS、および MySQL や Apache 2.0 ライセンスに基づく PostgreSQL などの JDBC 準拠のリレーショナルデータソースといったデータソース用のものです。Athena Query Federation SDK を使用してカスタムコネクタを記述することもできます。データソースコネクタを選択し、設定し、アカウントにデプロイするには、Athena および Lambda コンソールまたは AWS Serverless Application Repository を使用できます。データソースコネクタをデプロイした後、コネクタは SQL クエリで指定できるカタログに関連付けられます。複数のカタログの SQL ステートメントを組み合わせて、1 つのクエリの範囲に複数のデータソースを入れることができます。
データソースに対してクエリが送信されると、Athena が対応するコネクタを呼び出して、読み取る必要があるテーブルの箇所を特定し、並列処理を管理して、フィルター述語をプッシュダウンします。クエリを送信するユーザーに基づいて、コネクタは特定のデータ要素へのアクセスを提供または制限できます。コネクタは、クエリで要求されたデータを返す形式として Apache Arrow を使用します。これにより、コネクタを C、C\$1\$1、Java、Python、Rust などの言語で実装できます。コネクタは Lambda で処理されるため、Lambda からアクセスできる、クラウドまたはオンプレミスの任意のデータソースからのデータへのアクセスに使用できます。
独自のデータソースコネクタを記述するには、Athena Query Federation SDK を使用して、Amazon Athena が提供し、維持する事前構築されたコネクタの 1 つをカスタマイズできます。[GitHub リポジトリ](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)からのソースコードのコピーを変更し、[コネクタ公開ツール](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)を使用して独自の AWS Serverless Application Repository パッケージを作成できます。
**注記**
サードパーティーデベロッパーは、データソースコネクタの記述に Athena Query Federation SDK を使用している可能性があります。これらのデータソースコネクタのサポート、またはライセンスに関する問題については、コネクタプロバイダーにお問い合わせください。AWS はこれらのコネクタをテストしておらず、サポートも提供しません。
Athena によって記述され、テストされたデータソースコネクタのリストについては、「[使用可能なデータソースコネクタ](connectors-available.md)」を参照してください。
独自のデータソースコネクタの記述については、GitHub の「[Example Athena connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)」(Example Athena コネクタ) を参照してください。
## 考慮事項と制限事項
+ **エンジンバージョン** – Athena のフェデレーティッドクエリは、Athena エンジンバージョン 2 以降でのみサポートされています。Athena エンジンバージョンの詳細については、「[Athena エンジンのバージョニング](engine-versions.md)」を参照してください。
+ **ビュー** – フェデレーティッドデータソースでビューを作成してクエリできるようになりました。フェデレーティッドビューは、基盤となるデータソースではなく、AWS Glue に格納されます。詳細については、「[フェデレーテッドビューをクエリする](running-federated-queries.md#running-federated-queries-federated-views)」を参照してください。
+ **区切り記号付き識別子** – 区切り記号付き識別子 (引用符で囲まれた識別子とも言う) の両端は、二重引用符 (") です。現在、Athena のフェデレーティッドクエリでは、区切り記号付き識別子はサポートされていません。
+ **書き込み操作** — [INSERT INTO](insert-into.md) などの書き込み操作はサポートされていません。これを試みた場合、「This operation is currently not supported for external catalogs (この操作は現在、外部カタログではサポートされていません)」というエラーメッセージが表示されることがあります。
+ **料金** – 料金の情報については、「[Amazon Athena の料金](https://aws.amazon.com/athena/pricing/)」を参照してください。
+ **JDBC ドライバー** – フェデレーティッドクエリや[外部 Hive メタストア](connect-to-data-source-hive.md)で JDBC ドライバーを使用するには、JDBC 接続文字列に `MetadataRetrievalMethod=ProxyAPI` を含めてください。JDBC ドライバーの詳細については、「[JDBC で Amazon Athena に接続する](connect-with-jdbc.md)」を参照してください。
+ **Secrets Manager** – AWS Secrets Manager で Athena フェデレーティッドクエリ機能を使用するには、Secrets Manager に Amazon VPC プライベートエンドポイントを設定する必要があります。詳細については、「*AWS Secrets Manager ユーザーガイド*」の「[Secrets Manager VPC プライベートエンドポイントを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)」を参照してください。
## 必要なアクセス許可
データソースコネクタは、正しく機能するために、次のリソースへのアクセスが必要になる場合があります。事前に構築されたコネクタを使用する場合は、コネクタの情報を確認して、VPC が正しく設定されていることを確認してください。また、クエリを実行し、コネクタを作成する IAM プリンシパルに、必要なアクションに対する許可があることを確認してください。詳細については、「[Athena Federated Query へのアクセスを許可する: ポリシーの例](federated-query-iam-access.md)」を参照してください。
+ **Simple Storage Service (Amazon S3)** – データコネクタは、Athena のクエリ結果が保存される Amazon S3 内の場所にクエリ結果を書き込むほか、Amazon S3 のスピルバケットにも書き込みます。この Amazon S3 の場所に対する接続と許可が必要です。各コネクタと [S3 ライフサイクル設定](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)にディスクへのスピル暗号化を使用して、不要になったスピルデータを期限切れにすることをお勧めします。
+ **Athena** – データソースには、クエリステータスのチェックとオーバースキャンの防止のために、Athena への (または Athena からの) 接続が必要です。
+ **AWS Glue Data Catalog** – コネクタが補足メタデータまたはプライマリメタデータのためにデータカタログを使用する場合は、接続とアクセス許可が必要です。
+ **Amazon ECR** – データソースコネクタ Lambda 関数は、Amazon ECR リポジトリの Amazon ECR イメージを使用します。コネクタをデプロイするユーザーには、 `ecr:BatchGetImage` と `ecr:GetDownloadUrlForLayer` のアクセス許可が必要です。詳細については、「*AWS Lambda 開発者ガイド*」の「[Amazon ECR のアクセス許可](https://docs.aws.amazon.com/lambda/latest/dg/images-create.html#gettingstarted-images-permissions)」を参照してください。
## 動画
次の動画を視聴して、Athena のフェデレーティッドクエリの使用に関する詳細を確認してください。
**動画: Quick で Amazon Athena フェデレーティッドクエリの結果を分析する**
次の動画は、Athena フェデレーティッドクエリの結果を Quick で分析する方法を説明します。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/HyM5d0TmwAQ)
**動画: Gaming Analytics Pipeline**
以下の動画は、Amazon Athena のフェデレーティッドクエリを使用して、ゲームやサービスからのテレメトリデータの取り込み、保存、および分析を実行するためのスケーラブルなサーバーレスデータパイプラインをデプロイする方法を紹介しています。
[](http://www.youtube.com/watch?v=https://www.youtube.com/embed/xcS-flUMVbs)
# 使用可能なデータソースコネクタ
このセクションでは、Amazon S3 外部のさまざまなデータソースをクエリするために使用できる、事前構築された Athena データソースコネクタをリストします。Athena クエリでコネクタを使用するには、コネクタを設定してアカウントにデプロイします。
## 考慮事項と制限事項
+ 一部の事前構築されたコネクタでは、コネクタを使用する前に VPC とセキュリティグループを作成する必要があります。VPC の作成方法の詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
+ AWS Secrets Manager で Athena フェデレーティッドクエリ機能を使用するには、Secrets Manager に Amazon VPC プライベートエンドポイントを設定する必要があります。詳細については、「AWS Secrets Manager ユーザーガイド」の「[Secrets Manager VPC プライベートエンドポイントを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)」を参照してください。
+ 述語のプッシュダウンをサポートしていないコネクタの場合、述語を含むクエリの実行には時間がかかります。小規模なデータセットの場合、スキャンされるデータはほとんどなく、クエリは平均約 2 分で終わります。しかし、大規模なデータセットでは、多くのクエリがタイムアウトする可能性があります。
+ 一部のフェデレーティッドデータソースでは、データオブジェクトを参照する用語に、Athena とは異なるものが使用されています。詳細については、「[フェデレーテッドテーブル名修飾子を理解する](tables-qualifiers.md)」を参照してください。
+ データベースまたはデータソースプロバイダーからのアップグレードに基づいて、コネクタを定期的に更新します。サポートが終了するデータソースはサポートされていません。
+ テーブルを一覧表示するときにページ分割をサポートしないコネクタでは、データベースに多数のテーブルとメタデータがある場合にウェブサービスがタイムアウトする可能性があります。次のコネクタは、テーブルの一覧表示のページ分割をサポートします。
+ DocumentDB
+ DynamoDB
+ MySQL
+ OpenSearch
+ Oracle
+ PostgreSQL
+ Redshift
+ SQL Server
## Federation SDK ケース解決モード
Federation SDK は、スキーマ名とテーブル名に対して次の標準化されたケース解決モードをサポートしています。
+ `NONE` – 指定したスキーマ名とテーブル名の文字の大小を変更しません。
+ `LOWER` – 指定したすべてのスキーマ名とテーブル名を小文字にします。
+ `UPPER` – 指定したすべてのスキーマ名とテーブル名を大文字にします。
+ `ANNOTATION` – このモードは下位互換性のためにのみ維持され、既存の Snowflake および SAP HANA コネクタでのみサポートされています。
+ `CASE_INSENSITIVE_SEARCH` – スキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。
## ケース解決モードのコネクタサポート
### 基本モードのサポート
すべての JDBC コネクタは、次の基本モードをサポートしています。
+ `NONE`
+ `LOWER`
+ `UPPER`
### 注釈モードのサポート
以下のコネクタのみが `ANNOTATION` モードをサポートしています。
+ Snowflake
+ SAP HANA
**注記**
ANNOTATION の代わりに CASE\$1INSENSITIVE\$1SEARCH を使用することをお勧めします。
### 大文字と小文字を区別しない検索のサポート
以下のコネクタは `CASE_INSENSITIVE_SEARCH` をサポートしています。
+ DataLake Gen2
+ Snowflake
+ Oracle
+ Synapse
+ MySQL
+ PostgreSQL
+ Redshift
+ ClickHouse
+ SQL Server
+ DB2
## ケース解決の制限事項
ケース解決モードを使用する場合は、次の制限事項に注意してください。
+ `LOWER` モードを使用する場合、スキーマ名とスキーマ内のすべてのテーブルは小文字にする必要があります。
+ `UPPER` モードを使用する場合、スキーマ名とスキーマ内のすべてのテーブルは大文字にする必要があります。
+ `CASE_INSENSITIVE_SEARCH` を使用する場合:
+ スキーマ名は一意であることが必要です。
+ スキーマ内のテーブル名は一意である必要があります (例えば、「Apple」と「APPLE」の両方を使用することはできません）
+ Glue 統合の制限事項：
+ Glue は小文字の名前のみをサポートします。
+ Lambda 関数を GlueDataCatalog/LakeFormation に登録すると、`NONE` または `LOWER` モードのみが機能します。
## 追加情報
+ Athena データソースコネクタのデプロイについては、「[Amazon Athena フェデレーティッドクエリを使用する](federated-queries.md)」を参照してください。
+ Athena データソースコネクタを使用するクエリについては、「[フェデレーティッドクエリを実行する](running-federated-queries.md)」を参照してください。
**Topics**
+ [考慮事項と制限事項](#connectors-available-considerations)
+ [Federation SDK ケース解決モード](#case-resolver-modes)
+ [ケース解決モードのコネクタサポート](#connector-support-matrix)
+ [ケース解決の制限事項](#case-resolver-limitations)
+ [追加情報](#connectors-available-additional-resources)
+ [Azure Data Lake Storage](connectors-adls-gen2.md)
+ [Azure Synapse](connectors-azure-synapse.md)
+ [Cloudera Hive](connectors-cloudera-hive.md)
+ [Cloudera Impala](connectors-cloudera-impala.md)
+ [CloudWatch](connectors-cloudwatch.md)
+ [CloudWatch メトリクス](connectors-cwmetrics.md)
+ [CMDB](connectors-cmdb.md)
+ [Db2](connectors-ibm-db2.md)
+ [Db2 iSeries](connectors-ibm-db2-as400.md)
+ [DocumentDB](connectors-docdb.md)
+ [DynamoDB](connectors-dynamodb.md)
+ [Google BigQuery](connectors-bigquery.md)
+ [Google Cloud Storage](connectors-gcs.md)
+ [HBase](connectors-hbase.md)
+ [Hortonworks](connectors-hortonworks.md)
+ [Kafka](connectors-kafka.md)
+ [MSK](connectors-msk.md)
+ [MySQL](connectors-mysql.md)
+ [Neptune](connectors-neptune.md)
+ [OpenSearch](connectors-opensearch.md)
+ [Oracle](connectors-oracle.md)
+ [PostgreSQL](connectors-postgresql.md)
+ [Redis OSS](connectors-redis.md)
+ [Redshift](connectors-redshift.md)
+ [SAP HANA](connectors-sap-hana.md)
+ [Snowflake](connectors-snowflake.md)
+ [SQL Server](connectors-microsoft-sql-server.md)
+ [Teradata](connectors-teradata.md)
+ [Timestream](connectors-timestream.md)
+ [TPC-DS](connectors-tpcds.md)
+ [Vertica](connectors-vertica.md)
**注記**
[AthenaJdbcConnector](https://serverlessrepo.aws.amazon.com/applications/us-east-1/292517598671/AthenaJdbcConnector) (最新バージョン 2022.4.1) は廃止されました。代わりに、[MySQL](connectors-mysql.md)、[Redshift](connectors-redshift.md)、[PostgreSQL](connectors-postgresql.md) などのデータベース専用のコネクタを使用してください。
# Amazon Athena Azure Data Lake Storage (ADLS) Gen2 コネクタ
[Azure Data Lake Storage (ADLS) Gen2](https://docs.microsoft.com/en-us/azure/databricks/data/data-sources/azure/adls-gen2/) 用の Amazon Athena コネクタを使用すれば、Amazon Athena で ADLS に保存されたデータに SQL クエリを実行できます。Athena は、データレイクに保存されているファイルに直接アクセスすることはできません。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
+ **ワークフロー** – このコネクタは、`com.microsoft.sqlserver.jdbc.SQLServerDriver` ドライバーを使用する JDBC インターフェイスを実装します。このコネクタが Azure Synapse エンジンにクエリを渡し、その後、Azure Synapse エンジンがデータレイクにアクセスします。
+ **データ処理と S3** – 通常、Lambda コネクタは、Amazon S3 に転送することなく、データを直接クエリします。ただし、Lambda 関数から返されたデータが Lambda の制限を超えると、そのデータは、Athena が超過分を読み取れるように指定した Amazon S3 スピルバケットに書き込まれます。
+ **AAD 認証** – AAD は、Azure Synapse コネクタの認証方法として使用できます。AAD を使用するには、コネクタが使用する JDBC 接続文字列に、`authentication=ActiveDirectoryServicePrincipal`、`AADSecurePrincipalId`、および `AADSecurePrincipalSecret` の URL パラメータが含まれている必要があります。これらのパラメータは、直接渡すことも、Secrets Manager から渡すこともできます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件における日付とタイムスタンプのデータ型は、適切なデータ型にキャストする必要があります。
## 用語
次の用語は、Azure Data Lake Storage Gen2 コネクタに関連しています。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Azure Data Lake Storage Gen2 コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Azure Data Lake Storage Gen2 コネクタを設定することをお勧めします。そのためには、Azure Data Lake Storage Gen2 コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DATALAKEGEN2
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Azure Data Lake Storage Gen2 コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Azure Data Lake Storage Gen2 コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
datalakegentwo://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | DataLakeGen2MuxCompositeHandler |
| メタデータハンドラー | DataLakeGen2MuxMetadataHandler |
| レコードハンドラー | DataLakeGen2MuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mydatalakegentwocatalog の場合、環境変数の名前は mydatalakegentwocatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
以下は、2 つのデータベースインスタンス (デフォルト値の `datalakegentwo1`、および `datalakegentwo2`) をサポートする、DataLakeGen2 MUX Lambda 関数のプロパティ例です。
****
| プロパティ | 値 |
| --- | --- |
| default | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 |
| datalakegentwo\$1catalog1\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo1.hostname:port;databaseName=database\$1name;\$1\$1secret1\$1name\$1 |
| datalakegentwo\$1catalog2\$1connection\$1string | datalakegentwo://jdbc:sqlserver://adlsgentwo2.hostname:port;databaseName=database\$1name;\$1\$1secret2\$1name\$1 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${secret1_name}` が含まれています。
```
datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;${secret1_name}
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=database_name;user=user_name;password=password
```
#### 単一接続ハンドラーの使用
単一の Azure Data Lake Storage Gen2 インスタンスに接続するには、次の単一接続メタデータとレコードハンドラーを使用します。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | DataLakeGen2CompositeHandler |
| メタデータハンドラー | DataLakeGen2MetadataHandler |
| レコードハンドラー | DataLakeGen2RecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Azure Data Lake Storage Gen2 インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | datalakegentwo://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表では、ADLS Gen2 と Arrow に対応させてデータ型を示しています。
****
| ADLS Gen2 | Arrow |
| --- | --- |
| bit | TINYINT |
| tinyint | SMALLINT |
| smallint | SMALLINT |
| int | INT |
| bigint | BIGINT |
| decimal | DECIMAL |
| numeric | FLOAT8 |
| smallmoney | FLOAT8 |
| money | DECIMAL |
| float[24] | FLOAT4 |
| float[53] | FLOAT8 |
| real | FLOAT4 |
| datetime | Date(MILLISECOND) |
| datetime2 | Date(MILLISECOND) |
| smalldatetime | Date(MILLISECOND) |
| date | Date(DAY) |
| 時間 | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
## パーティションと分割
Azure Data Lake Storage Gen2 は、データファイルの保存に Hadoop 互換の Gen2 ブロブストレージを使用します。これらのファイルからのデータは、Azure Synapse エンジンによりクエリされます。Azure Synapse エンジンは、ファイルシステムに保存されている Gen2 データを外部テーブルとして扱います。パーティションはデータの型に基づいて実装されます。データがすでにパーティション化されており、Gen 2 ストレージシステム内で分散されている場合、コネクタは、データを単一のスプリットとして取得します。
## パフォーマンス
Azure Data Lake Storage Gen2 コネクタは、複数のクエリを一度に実行するとクエリのパフォーマンスが遅くなり、スロットリングの対象となります。
Athena Azure Data Lake Storage Gen2 コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。単純な述語と複雑な式はコネクタにプッシュダウンされるため、スキャンされるデータ量が減少し、クエリ実行のランタイムが短縮されます。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Azure Data Lake Storage Gen2 コネクタは、これらの式を組み合わせて Azure Data Lake Storage Gen2 に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Azure Data Lake Storage Gen2 コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## パススルークエリ
Azure Data Lake Storage Gen2 コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Azure Data Lake Storage Gen2 でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Azure Data Lake Storage Gen2 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
JDBC ドライバーの最新バージョンの情報については、GitHub.com で、Azure Data Lake Storage Gen2 コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-datalakegen2/pom.xml) ファイルを確認してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-datalakegen2)を参照してください。
# Amazon Athena Azure Synapse コネクタ
[Azure Synapse Analytics](https://docs.microsoft.com/en-us/azure/synapse-analytics/overview-what-is) 用の Amazon Athena コネクタを使用すると、Amazon Athena で Azure Synapse データベースに JDBC を使用した SQL クエリを実行できます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件では、`Date` と `Timestamp` データ型を適切なデータ型に型変換する必要があります。
+ `Real` および `Float` 型の負の値を検索するには、`<=` または `>=` 演算子を使用します。
+ `binary`、`varbinary`、`image`、および `rowversion` データ型はサポートされていません。
## 用語
Synapse コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Synapse コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Synapse コネクタを設定することをお勧めします。そのためには、Oracle コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type SYNAPSE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Synapse コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Synapse コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続 (推奨)
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
synapse://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では次のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | SynapseMuxCompositeHandler |
| メタデータハンドラー | SynapseMuxMetadataHandler |
| レコードハンドラー | SynapseMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysynapsecatalog の場合、環境変数の名前は mysynapsecatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`synapse1` (デフォルト) と `synapse2` の 2 つのデータベースインスタンスをサポートする Synapse MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| synapse\$1catalog1\$1connection\$1string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| synapse\$1catalog2\$1connection\$1string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列はシークレット名 \$1\$1secret\$1name\$1 を含んでいます。
```
synapse://jdbc:synapse://hostname:port;databaseName=;${secret_name}
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
synapse://jdbc:synapse://hostname:port;databaseName=;user=;password=
```
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Synapse インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | SynapseCompositeHandler |
| メタデータハンドラー | SynapseMetadataHandler |
| レコードハンドラー | SynapseRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Synapse インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | synapse://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### Active Directory 認証の設定
Amazon Athena Azure Synapse コネクタは Microsoft Active Directory 認証をサポートしています。開始する前に、Microsoft Azure ポータルで管理ユーザーを設定し、AWS Secrets Manager を使用してシークレットを作成する必要があります。
**Active Directory 管理者ユーザーを設定するには**
1. 管理者権限を持つアカウントを使用して、[https://portal.azure.com/](https://portal.azure.com/) で Microsoft Azure ポータルにサインインします。
1. 検索ボックスに**Azure Synapse Analytics** と入力し、**[Azure Synapse Analytics]** を選択します。
![\[alt text not found\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-azure-synapse-1.png)
1. 左側のメニューを開きます。
![\[Azure ポータルメニューを選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-azure-synapse-2.png)
1. ナビゲーションペインで、**[Azure Active Directory]** を選択します。
1. **[管理者の設定]** タブで、**Active Directory 管理者**を新規ユーザーまたは既存のユーザーに設定します。
![\[[管理者の設定] タブを使用します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-azure-synapse-3.png)
1. AWS Secrets Manager に、管理者のユーザー名とパスワードの認証情報を保存します。Secrets Manager でのシークレットの作成については、「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。
**Secrets Manager で自分のシークレットを確認するには**
1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/) から Secrets Manager コンソールを開きます。
1. ナビゲーションペインで **[Secrets]** (シークレット) を選択します。
1. **[Secrets]** (シークレット) ページで、自分のシークレットを選択します。
1. 自分のシークレットの詳細ページで、**[Retrieve secret value]** (シークレットの値を取得する) を選択します。
![\[AWS Secrets Manager のシークレットを表示します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-azure-synapse-4.png)
##### 接続文字列の変更
コネクタの Active Directory 認証を有効にするには、次の構文を使用して接続文字列を変更します。
```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryPassword;{secret_name}
```
##### ActiveDirectoryServicePrincipal の使用
Amazon Athena Azure Synapse コネクタも `ActiveDirectoryServicePrincipal` をサポートしています。これを有効にするには、接続文字列を次のように変更します。
```
synapse://jdbc:synapse://hostname:port;databaseName=database_name;authentication=ActiveDirectoryServicePrincipal;{secret_name}
```
`secret_name` の場合、ユーザー名にはアプリケーション ID またはクライアント ID を指定し、パスワードにはサービスプリンシパル ID のシークレットを指定します。
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、Synapse と Apache Arrow に対応するデータ型を示します。
****
| Synapse | Arrow |
| --- | --- |
| bit | TINYINT |
| tinyint | SMALLINT |
| smallint | SMALLINT |
| int | INT |
| bigint | BIGINT |
| decimal | DECIMAL |
| numeric | FLOAT8 |
| smallmoney | FLOAT8 |
| money | DECIMAL |
| float[24] | FLOAT4 |
| float[53] | FLOAT8 |
| real | FLOAT4 |
| datetime | Date(MILLISECOND) |
| datetime2 | Date(MILLISECOND) |
| smalldatetime | Date(MILLISECOND) |
| date | Date(DAY) |
| 時間 | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
| nchar[n] | VARCHAR |
| nvarchar[n/max] | VARCHAR |
## パーティションと分割
パーティションは、`varchar` 型の単一パーティション列で表されます。Synapse は範囲によるパーティションをサポートしているため、パーティションは Synapse メタデータテーブルからパーティション列とパーティション範囲を抽出することによって実装されます。これらの範囲の値はスプリットの作成に使用されます。
## パフォーマンス
列のサブセットを選択すると、クエリランタイムが大幅に遅くなります。同時実行が原因で、コネクタに著しいスロットリングが発生しています。
Athena Synapse コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。単純な述語と複雑な式はコネクタにプッシュダウンされるため、スキャンされるデータ量が減少し、クエリ実行のランタイムが短縮されます。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Synapse コネクタは、これらの式を組み合わせて Synapse に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Synapse コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## パススルークエリ
Synapse コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Synapse でパススルークエリを使用するには、次の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
次のクエリ例は、Synapse 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
+ Quick と Amazon Athena のフェデレーティッドクエリを使用して、Microsoft Azure Synapse データベースに保存されているデータに関するダッシュボードとビジュアライゼーションを構築する方法の記事については、*AWS Big Data Blog* の「[Perform multi-cloud analytics using Amazon Quick, Amazon Athena Federated Query, and Microsoft Azure Synapse](https://aws.amazon.com/blogs/business-intelligence/perform-multi-cloud-analytics-using-amazon-quicksight-amazon-athena-federated-query-and-microsoft-azure-synapse/)」を参照してください。
+ 最新の JDBC ドライバーのバージョン情報については、GitHub.com の Synapse コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-synapse/pom.xml) ファイルを参照してください。
+ このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-synapse)を参照してください。
# Amazon Athena Cloudera Hive コネクタ
Cloudera Hive 用の Amazon Athena コネクタを使用すると、Athena で [Cloudera Hive](https://www.cloudera.com/products/open-source/apache-hadoop/apache-hive.html) Hadoop 分散に SQL クエリを実行できます。コネクタによって Athena SQL クエリは同等の HiveQL 構文に変換されます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
## 用語
以下に、Cloudera Hive コネクタに関連する用語を示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Cloudera Hive コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Cloudera Hive コネクタを設定することをお勧めします。そのためには、Cloudera Hive コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type CLOUDERAHIVE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Cloudera Hive コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Cloudera Hive コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
hive://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | HiveMuxCompositeHandler |
| メタデータハンドラー | HiveMuxMetadataHandler |
| レコードハンドラー | HiveMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myhivecatalog の場合、環境変数の名前は myhivecatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
以下に、2 つのデータベースインスタンス (デフォルト値の `hive1`、および `hive2`) をサポートする、Hive MUX Lambda 関数のプロパティ例を示します。
****
| プロパティ | 値 |
| --- | --- |
| default | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 |
| hive2\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default;\$1\$1Test/RDS/hive1\$1 |
| hive2\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default;UID=sample&PWD=sample |
##### 認証情報の提供
JDBC 接続文字列でデータベースのユーザー名とパスワードを指定するには、Cloudera Hive コネクタに AWS Secrets Manager からのシークレットが必要です。Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/hive1}` が含まれています。
```
hive://jdbc:hive2://hive1:10000/default;...&${Test/RDS/hive1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
hive://jdbc:hive2://hive1:10000/default;...&UID=sample2&PWD=sample2&...
```
現在のところ、Cloudera Hive コネクタは、`UID` および `PWD` の JDBC プロパティを認識します。
#### 単一接続ハンドラーの使用
以下の単一接続メタデータ、およびレコードハンドラーを使用すると、単一の Cloudera Hive インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | HiveCompositeHandler |
| メタデータハンドラー | HiveMetadataHandler |
| レコードハンドラー | HiveRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
次は、Lambda 関数でサポートされている単一の Cloudera Hive インスタンス用のプロパティ例です。
****
| プロパティ | 値 |
| --- | --- |
| デフォルト | hive://jdbc:hive2://hive1:10000/default;secret=\$1\$1Test/RDS/hive1\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表では、JDBC、Cloudera Hive、および Arrow に対応させて、各データ型を示しています。
****
| JDBC | Cloudera Hive | Arrow |
| --- | --- | --- |
| ブール値 | ブール値 | Bit |
| 整数 | TINYINT | Tiny |
| ショート | SMALLINT | Smallint |
| 整数 | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| ダブル | float8 | Float8 |
| 日付 | date | DateDay |
| タイムスタンプ | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| バイト | bytes | Varbinary |
| BigDecimal | 10 進数 | 10 進数 |
| 配列 | 該当なし (注記を参照) | リスト |
**注記**
現在のところ、Cloudera Hive では、集計型 `ARRAY`、`MAP`、`STRUCT`、および `UNIONTYPE` はサポートされません。集計型の列は、SQL における `VARCHAR` 列のように扱われます。
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
Cloudera Hive は静的パーティションをサポートしています。Athena Cloudera Hive コネクタは、これらのパーティションからデータを並列に取得できます。パーティション分散が一様で非常に大きなデータセットをクエリする場合は、静的パーティショニングの使用を強くお勧めします。Cloudera Hive コネクタは、同時実行によるスロットリングに強いです。
Athena Cloudera Hive コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Cloudera Hive コネクタは、これらの式を組み合わせて Cloudera Hive に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Cloudera Hive コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
Cloudera Hive コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Cloudera Hive でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Cloudera Hive 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
JDBC ドライバーの最新バージョンの情報については、GitHub.com で Cloudera Hive コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-hive/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-hive)を参照してください。
# Amazon Athena Cloudera Impala コネクタ
Amazon Athena Cloudera Impala コネクタは、Athena が [Cloudera Impala](https://docs.cloudera.com/cdw-runtime/cloud/impala-overview/topics/impala-overview.html) ディストリビューションで SQL クエリを実行することを可能にします。このコネクタは、Athena SQL クエリを同等の Impala 構文に変換します。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
## 用語
以下に、Cloudera Impala コネクタに関連する用語を示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Cloudera Impala コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Cloudera Impala コネクタを設定することをお勧めします。そのためには、Cloudera Impala コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type CLOUDERAIMPALA
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Cloudera Impala コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Cloudera Impala コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、Impalaクラスターに接続します。
```
impala://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | ImpalaMuxCompositeHandler |
| メタデータハンドラー | ImpalaMuxMetadataHandler |
| レコードハンドラー | ImpalaMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。Athena カタログの Impala クラスター接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myimpalacatalog の場合、環境変数の名前は myimpalacatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
以下に、2 つのデータベースインスタンス (デフォルトの `impala1`、および `impala2`) をサポートする Impala MUX Lambda 関数におけるプロパティ例を示します。
****
| プロパティ | 値 |
| --- | --- |
| default | impala://jdbc:impala://some.impala.host.name:21050/?\$1\$1Test/impala1\$1 |
| impala\$1catalog1\$1connection\$1string | impala://jdbc:impala://someother.impala.host.name:21050/?\$1\$1Test/impala1\$1 |
| impala\$1catalog2\$1connection\$1string | impala://jdbc:impala://another.impala.host.name:21050/?UID=sample&PWD=sample |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/impala1host}` が含まれています。
```
impala://jdbc:impala://Impala1host:21050/?...&${Test/impala1host}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
impala://jdbc:impala://Impala1host:21050/?...&UID=sample2&PWD=sample2&...
```
現在のところ Cloudera Impala は、`UID` および `PWD` の JDBC プロパティを認識します。
#### 単一接続ハンドラーの使用
以下の単一接続メタデータとレコードハンドラーを使用すると、単一の Cloudera Impala インスタンスに接続することが可能です。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | ImpalaCompositeHandler |
| メタデータハンドラー | ImpalaMetadataHandler |
| レコードハンドラー | ImpalaRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
次は、Lambda 関数でサポートされている単一の Cloudera Impala インスタンスのためのプロパティ例です。
****
| プロパティ | 値 |
| --- | --- |
| default | impala://jdbc:impala://Impala1host:21050/?secret=\$1\$1Test/impala1host\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表では、JDBC、Cloudera Impala、および Arrow と対応させて各データ型を示しています。
****
| JDBC | Cloudera Impala | Arrow |
| --- | --- | --- |
| ブール値 | ブール値 | Bit |
| 整数 | TINYINT | Tiny |
| ショート | SMALLINT | Smallint |
| 整数 | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| ダブル | float8 | Float8 |
| 日付 | date | DateDay |
| タイムスタンプ | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| バイト | bytes | Varbinary |
| BigDecimal | 10 進数 | 10 進数 |
| 配列 | 該当なし (注記を参照) | リスト |
**注記**
現在のところ、Cloudera Impala では集計型 (`ARRAY`、`MAP`、`STRUCT`、および `UNIONTYPE`) はサポートされません。集計型の列は、SQL における `VARCHAR` 列のように扱われます。
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
Cloudera Impala では静的パーティションが利用できます。Athena Cloudera Impala コネクタは、これらのパーティションからデータを並列に取得できます。パーティション分散が一様で非常に大きなデータセットをクエリする場合は、静的パーティショニングの使用を強くお勧めします。Cloudera Impala コネクタは、同時実行によりスロットリングに強いです。
Athena Cloudera Impala コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Cloudera Impala コネクタは、これらの式を組み合わせて Cloudera Impala に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Cloudera Impala コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
Cloudera Impala コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Cloudera Impala でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Cloudera Impala 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
JDBC ドライバーの最新バージョンの情報については、GitHub.com の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudera-impala/pom.xml) ファイルで、Cloudera Impala コネクタを確認してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudera-impala)を参照してください。
# Amazon Athena CloudWatch コネクタ
Amazon Athena CloudWatch コネクタは、Amazon Athena が CloudWatch とやり取りすることを可能にして、ログデータを SQL でクエリできるようにします。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
このコネクタは、LogGroups をスキーマとして、および各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な `all_log_streams` ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して CloudWatch コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して CloudWatch コネクタを設定することをお勧めします。そのためには、CloudWatch コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type CLOUDWATCH
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された CloudWatch コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された CloudWatch コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
コネクタでは、CloudWatch から [Amazon Athena クエリフェデレーション SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) の `ThrottlingInvoker` コンストラクトを介してスロットリングされるイベントの処理用として、[AIMD の輻輳 (ふくそう) 制御](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease) もサポートしています。以下のオプションの環境変数のいずれかを設定することで、デフォルトのスロットリング動作を微調整できます。
+ **throttle\$1initial\$1delay\$1ms** – 最初の輻輳イベントの後に適用される最初の呼び出し遅延。デフォルト値は 10 ミリ秒です。
+ **throttle\$1max\$1delay\$1ms** – 呼び出し間の最大遅延。これを 1000 ミリ秒で除算することで、TPS を算出できます。デフォルト値は 1000 ミリ秒です。
+ **throttle\$1decrease\$1factor** – Athena が呼び出しのレートを低減する要因。デフォルトは 0.5 です。
+ **throttle\$1increase\$1ms** – Athena がコール遅延を低減させた際のレート。デフォルト値は 10 ミリ秒です。
## データベースとテーブル
このコネクタは、LogGroups をスキーマ (つまりデータベース) として、また、各 LogStream をテーブルとしてマップします。また、コネクタにより、LogGroup 内のすべての LogStream が含まれている特別な `all_log_streams` ビューもマップされます。このビューでは、各 LogStream を個別に検索するのではなく、LogGroup 内のすべてのログを一度にクエリできます。
Athena CloudWatch コネクタによってマッピングされるすべてのテーブルには、次のスキーマが含まれています。このスキーマにより、CloudWatch Logs が提供するフィールドとのマッチングが行われます。
+ **log\$1stream** – 対象の行を提供する LogStream の名前が含まれている `VARCHAR`。
+ **time** – ログ行が生成されたエポックタイムを含む `INT64`。
+ **message** – ログメッセージを含む `VARCHAR`。
**例**
以下の例では、指定された LogStream に対する `SELECT` クエリの実行方法を示しています
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name"
LIMIT 100
```
以下の例では、`all_log_streams`ビューを使用して、指定された LogGroup 内のすべての LogStreams に対してクエリを実行する方法を示しています。
```
SELECT *
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams"
LIMIT 100
```
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細は、[athena-cloudwatch.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/athena-cloudwatch.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **CloudWatch Logs Read/Write** – コネクタは、ログデータの読み取りと診断ログの書き込みのために、このアクセス許可を使用します。
## パフォーマンス
Athena CloudWatch コネクタは、クエリが必要とするログストリームのスキャンを並列化することで、CloudWatch に対するクエリの最適化を試みます。フィルタで特定の期間を指定する場合、Lambda 関数内と CloudWatch Logs 内の両方で述語のプッシュダウンが実行されます。
最高のパフォーマンスを得るには、ロググループ名とログストリーム名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。
**注記**
CloudWatch コネクタは、大文字のデータベース名をサポートしていません。
## パススルークエリ
CloudWatch コネクタは、[CloudWatch Logs Insights クエリ構文](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html)を使用する[パススルークエリ](federated-query-passthrough.md)をサポートします。CloudWatch Logs Insights の詳細については、「Amazon CloudWatch Logs ユーザーガイド」の「[CloudWatch Logs Insights でログデータを分析する](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html)」を参照してください。
CloudWatch でパススルークエリを作成するには、以下の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
STARTTIME => 'start_time',
ENDTIME => 'end_time',
QUERYSTRING => 'query_string',
LOGGROUPNAMES => 'log_group-names',
LIMIT => 'max_number_of_results'
))
```
次の CloudWatch パススルークエリの例では、`duration` フィールドの値が 1000 でない場合にフィルターが適用されてます。
```
SELECT * FROM TABLE(
system.query(
STARTTIME => '1710918615308',
ENDTIME => '1710918615972',
QUERYSTRING => 'fields @duration | filter @duration != 1000',
LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1',
LIMIT => '2'
))
```
## ライセンス情報
Amazon Athena CloudWatch コネクタプロジェクトは、[Apache-2.0 ライセンス](https://www.apache.org/licenses/LICENSE-2.0.html)の下で使用許諾されています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch)を参照してください。
# Amazon Athena CloudWatch Metrics コネクタ
Amazon Athena CloudWatch メトリクスコネクタを使用すると、Amazon Athena は SQL を使用して CloudWatch メトリクスデータをクエリできます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
Athena 自体から CloudWatch にクエリメトリクスを公開する方法については、「[CloudWatch と EventBridge を使用してクエリをモニタリングし、コストを管理する](workgroups-control-limits.md)」を参照してください。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して CloudWatch Metrics コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して CloudWatch Metrics コネクタを設定することをお勧めします。そのためには、CloudWatch Metrics コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type CLOUDWATCHMETRICS
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された CloudWatch Metrics コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された CloudWatch Metrics コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
コネクタでは、CloudWatch から [Amazon Athena クエリフェデレーション SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) の `ThrottlingInvoker` コンストラクトを介してスロットリングされるイベントの処理用として、[AIMD の輻輳 (ふくそう) 制御](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease) もサポートしています。以下のオプションの環境変数のいずれかを設定することで、デフォルトのスロットリング動作を微調整できます。
+ **throttle\$1initial\$1delay\$1ms** – 最初の輻輳イベントの後に適用される最初の呼び出し遅延。デフォルト値は 10 ミリ秒です。
+ **throttle\$1max\$1delay\$1ms** – 呼び出し間の最大遅延。これを 1000 ミリ秒で除算することで、TPS を算出できます。デフォルト値は 1000 ミリ秒です。
+ **throttle\$1decrease\$1factor** – Athena が呼び出しのレートを低減する要因。デフォルトは 0.5 です。
+ **throttle\$1increase\$1ms** – Athena がコール遅延を低減させた際のレート。デフォルト値は 10 ミリ秒です。
## データベースとテーブル
Athena CloudWatch Metrics コネクタは、名前空間、ディメンション、メトリクス、およびメトリクスの値を、`default` という単一のスキーマ内で 2 つのテーブルにマッピングします。
### メトリクステーブル
`metrics` テーブルは、名前空間、セット、名前の組み合わせによって一意に定義された、使用可能なメトリクスで構成されています。この `metrics` テーブルには次の列が含まれます。
+ **namespacee** – `VARCHAR` は名前空間を含みます。
+ **metric\$1name** – `VARCHAR` はメトリクス名を含みます。
+ **ディメンション** – `dim_name (VARCHAR)` および `dim_value (VARCHAR)` から構成される `STRUCT` オブジェクトの `LIST`。
+ **statistic** – メトリクスで使用が可能な、`VARCH` 統計情報の `LIST` (例: `p90`、`AVERAGE`、...)。
### metric\$1samples テーブル
`metric_samples` テーブルには、`metrics` テーブルで使用可能な各メトリクスのサンプルが含まれています。この `metric_samples` テーブルには次の列が含まれます。
+ **namespace** – 名前空間が含まれている `VARCHAR`。
+ **metric\$1name** – メトリクス名が含まれている `VARCHAR`。
+ **ディメンション** – `dim_name (VARCHAR)` および `dim_value (VARCHAR)` から構成される `STRUCT` オブジェクトの `LIST`。
+ **dim\$1name** – 単一のディメンション名により簡単にフィルタリングできる、`VARCHAR` のコンビニエンスフィールド。
+ **dim\$1value** – 単一のディメンション値により簡単にフィルタリングできる、`VARCHAR` のコンビニエンスフィールド。
+ **period** – メトリクスの「期間」を、秒単位 (60 秒間メトリクスなど) で表す `INT` フィールド。
+ **timestamp** – メトリクスがサンプリングを行うエポックタイムを、秒単位で表す `BIGINT` フィールド。
+ **value** – サンプルされた値を含む `FLOAT8` フィールド。
+ **statistic** – サンプル値の統計タイプ (例: `AVERAGE`、`p90`) が含まれている `VARCHAR` 。
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-cloudwatch-metrics.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch-metrics/athena-cloudwatch-metrics.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **CloudWatch Metrics ReadOnly** – コネクタは、メトリクスのデータをクエリするために、このアクセス許可を使用します。
+ **CloudWatch Logs Write** – コネクタは、このアクセスを使用して診断ログへの書き込みを行います。
## パフォーマンス
Athena CloudWatch Metrics コネクタは、クエリに必要なログストリームに対し並列化したスキャンを行うことで、CloudWatch Metrics へのクエリを最適化しようとします。特定の期間や、メトリクス、名前空間、ディメンションフィルタに対しては、Lambda 関数内と CloudWatch Logs 内の両方で述語のプッシュダウンが実行されます。
## ライセンス情報
Amazon Athena CloudWatch Metrics コネクタプロジェクトは、[Apache-2.0 ライセンス](https://www.apache.org/licenses/LICENSE-2.0.html)の下で使用許諾されています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch-metrics)を参照してください。
# Amazon Athena AWS CMDB コネクタ
Amazon Athena AWS CMDB コネクタは、Amazon Athena と AWS のさまざまなサービスとの通信を可能にし、それらに対し SQL によりクエリできるようにします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して AWS CMDB コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して AWS CMDB コネクタを設定することをお勧めします。そのためには、AWS CMDB コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type CMDB
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された AWS CMDB コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された AWS CMDB コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **default\$1ec2\$1image\$1owner** – (オプション) 設定されている場合、[Amazon マシンイメージ (AMI)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) をフィルタリングする、デフォルトの Amazon EC2 イメージ所有者を管理します。この値が設定されておらず、EC2 イメージテーブルに対するクエリが所有者に対するフィルタを含まない場合は、すべてのパブリックイメージが結果に含まれます。
## データベースとテーブル
Athena AWS CMDB コネクタは、次のデータベースとテーブルが、AWS のリソースインベントリーをクエリできるようにします。各テーブルで使用できる列の詳細は、Athena コンソールまたは API から、`DESCRIBE database.table` ステートメントを実行すると確認できます。
+ **ec2** – このデータベースには、以下をはじめとした Amazon EC2 の関連リソースが含まれています。
+ **ebs\$1volumes** – Amazon EBS ボリュームの詳細が含まれます。
+ **ec2\$1instances** – EC2 インスタンスの詳細が含まれます。
+ **ec2\$1images** – EC2 インスタンスイメージの詳細が含まれます。
+ **routing\$1tables** – VPC ルートテーブルの詳細が含まれます。
+ **security\$1groups** – セキュリティグループの詳細が含まれます。
+ **subnets** – VPC サブネットの詳細が含まれます。
+ **vpcs** – VPC の詳細が含まれます。
+ **emr** – このデータベースは、以下をはじめとした Amazon EMR 関連のリソースを含みます。
+ **emr\$1clusters** – EMR クラスターの詳細が含まれます。
+ **rds** – このデータベースは、以下をはじめとした Amazon RDS 関連のリソースを含みます。
+ **rds\$1instances** – RDS インスタンスの詳細が含まれます。
+ **s3** – このデータベースは、以下をはじめとした RDS 関連のリソースを含みます。
+ **buckets** – Amazon S3 バケットの詳細が含まれます。
+ **objects** – Amazon S3 オブジェクトの詳細を含みますが、オブジェクトの内容は含みません。
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細は、[athena-aws-cmdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-aws-cmdb/athena-aws-cmdb.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **S3 List** – コネクタは、このアクセス許可を使用して Amazon S3 のバケットとオブジェクトをリストします。
+ **EC2 Describe** – コネクタは、Amazon EC2 インスタンス、セキュリティグループ、VPC、Amazon EBS ボリュームなどのリソースを詳細表示する際に、このアクセス許可を使用します。
+ **EMR Describe / List** – コネクタは、EMR クラスターの詳細を表示する際に、このアクセス許可を使用します。
+ **RDS Describe** – コネクタは、RDS インスタンスの詳細を表示する際に、このアクセス許可を使用します。
## パフォーマンス
現在のところ、Athena AWS CMDB コネクタでは、並列スキャンはサポートされません。述語のプッシュダウンは Lambda 関数内で実行されます。可能な場合、部分述語はクエリ対象のサービスにプッシュされます。例えば、特定の Amazon EC2 インスタンスの詳細についてのクエリでは、目的の詳細表示オペレーションを実行するために、特定のインスタンス ID を使用して EC2 API を呼び出します。
## ライセンス情報
Amazon Athena AWS CMDB コネクタプロジェクトは、[Apache-2.0 ライセンス](https://www.apache.org/licenses/LICENSE-2.0.html)の下で使用許諾されています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-aws-cmdb)を参照してください。
# Amazon Athena IBM Db2 コネクタ
Db2 用 Amazon Athena コネクタは、Amazon Athena で JDBC を使用して IBM Db2 データベースの SQL クエリを実行できるようにします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件における日付とタイムスタンプのデータ型は、適切なデータ型にキャストする必要があります。
## 用語
Db2 コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Db2 コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Db2 コネクタを設定することをお勧めします。そのためには、Db2 コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DB2
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Db2 コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Db2 コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
dbtwo://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | Db2MuxCompositeHandler |
| メタデータハンドラー | Db2MuxMetadataHandler |
| レコードハンドラー | Db2MuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mydbtwocatalog の場合、環境変数の名前は mydbtwocatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`dbtwo1` (デフォルト) と `dbtwo2` の 2 つのデータベースインスタンスをサポートする Db2 MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 |
| dbtwo\$1catalog1\$1connection\$1string | dbtwo://jdbc:db2://dbtwo1.hostname:port/database\$1name:\$1\$1secret1\$1name\$1 |
| dbtwo\$1catalog2\$1connection\$1string | dbtwo://jdbc:db2://dbtwo2.hostname:port/database\$1name:\$1\$1secret2\$1name\$1 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${secret_name}` が含まれています。
```
dbtwo://jdbc:db2://hostname:port/database_name:${secret_name}
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
dbtwo://jdbc:db2://hostname:port/database_name:user=user_name;password=password;
```
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Db2 インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | Db2CompositeHandler |
| メタデータハンドラー | Db2MetadataHandler |
| レコードハンドラー | Db2RecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Db2 インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | dbtwo://jdbc:db2://hostname:port/database\$1name:\$1\$1secret\$1name\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Arrow に対応するデータ型を示します。
****
| Db2 | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| DATE | DATEDAY |
| TIME | VARCHAR |
| TIMESTAMP | DATEMILLI |
| DATETIME | DATEMILLI |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | DECIMAL |
| REAL | FLOAT8 |
| DOUBLE | FLOAT8 |
| DECFLOAT | FLOAT8 |
## パーティションと分割
パーティションは、1 つまたは複数のタイプ `varchar` のパーティション列で表されます。Db2 コネクタは、次の組織スキームを使用してパーティションを作成します。
+ ハッシュによる分散
+ 範囲によるパーティション
+ ディメンションによる整理
コネクタは、1 つ以上の Db2 メタデータテーブルから、パーティションの数や列名などのパーティションの詳細を取得します。スプリットは、特定されたパーティションの数に基づいて作成されます。
## パフォーマンス
Athena Db2 コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Db2 コネクタは、これらの式を組み合わせて Db2 に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Db2 コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
Db2 コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Db2 でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Db2 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Db2 コネクタ用の「[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2/pom.xml)」ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2)を参照してください。
# Amazon Athena IBM Db2 AS/400 (Db2 iSeries) コネクタ
Db2 AS/400 用の Amazon Athena コネクタは、Amazon Athena が JDBC を使用して IBM Db2 AS/400 (Db2 iSeries) データベースで SQL クエリを実行することを可能にします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件における日付とタイムスタンプのデータ型は、適切なデータ型にキャストする必要があります。
## 用語
以下は、Db2 AS/400 コネクタに関連する用語です。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Db2 AS/400 コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Db2 AS/400 コネクタを設定することをお勧めします。そのためには、Db2 AS/400 コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DB2AS400
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Db2 AS/400 コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Db2 AS/400 コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
db2as400://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | Db2MuxCompositeHandler |
| メタデータハンドラー | Db2MuxMetadataHandler |
| レコードハンドラー | Db2MuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mydb2as400catalog の場合、環境変数の名前は mydb2as400catalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`db2as4001` (デフォルト) と `db2as4002` の 2 つのデータベースインスタンスをサポートする Db2 MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | db2as400://jdbc:as400://;;:\$1\$1\$1; |
| db2as400\$1catalog1\$1connection\$1string | db2as400://jdbc:as400://db2as4001.hostname/:\$1\$1secret1\$1name\$1 |
| db2as400\$1catalog2\$1connection\$1string | db2as400://jdbc:as400://db2as4002.hostname/:\$1\$1secret2\$1name\$1 |
| db2as400\$1catalog3\$1connection\$1string | db2as400://jdbc:as400://;user=;password=;; |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${secret_name}` が含まれています。
```
db2as400://jdbc:as400://;;:${};
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
db2as400://jdbc:as400://;user=;password=;;
```
#### 単一接続ハンドラーの使用
以下の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Db2 AS/400 インスタンスに接続することができます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | Db2CompositeHandler |
| メタデータハンドラー | Db2MetadataHandler |
| レコードハンドラー | Db2RecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
以下は、Lambda 関数がサポートする単一の Db2 AS/400 用のプロパティ例です。
****
| プロパティ | 値 |
| --- | --- |
| default | db2as400://jdbc:as400://;;:\$1\$1\$1; |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Apache Arrow に対応するデータ型を示します。
****
| Db2 AS/400 | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| DATE | DATEDAY |
| TIME | VARCHAR |
| TIMESTAMP | DATEMILLI |
| DATETIME | DATEMILLI |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | DECIMAL |
| REAL | FLOAT8 |
| DOUBLE | FLOAT8 |
| DECFLOAT | FLOAT8 |
## パーティションと分割
パーティションは、1 つまたは複数のタイプ `varchar` のパーティション列で表されます。Db2 AS/400 コネクタは、以下の組織スキームを使用してパーティションを作成します。
+ ハッシュによる分散
+ 範囲によるパーティション
+ ディメンションによる整理
コネクタは、1 つ、または複数の Db2 AS/400 メタデータテーブルから、パーティションの数や列名などのパーティションの詳細情報を取得します。スプリットは、特定されたパーティションの数に基づいて作成されます。
## パフォーマンス
パフォーマンスを向上させるには、以下の例にあるように、述語のプッシュダウンを使用して Athena からクエリを実行してください。
```
SELECT * FROM "lambda:"."".""
WHERE integercol = 2147483647
```
```
SELECT * FROM "lambda: "."".""
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## パススルークエリ
Db2 AS/400 コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Db2 AS/400 でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Db2 AS/400 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーバージョンの情報については、GitHub.com で Db2 AS/400 コネクタ用の「[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-db2-as400/pom.xml)」ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-db2-as400)を参照してください。
# Amazon Athena DocumentDB コネクタ
Amazon Athena DocumentDB コネクタは、Athena と DocumentDB インスタンスとの通信を可能にします。これにより、DocumentDB データを SQL でクエリできるようになります。また、このコネクタは、MongoDB と互換性のある任意のエンドポイントでも機能します。
従来のリレーショナルデータストアとは異なり、Amazon DocumentDB コレクションには設定されたスキーマがありません。DocumentDB にはメタデータストアはありません。DocumentDB コレクションの各エントリには、さまざまな種類のフィールドとデータ型を含めることが可能です。
DocumentDB コネクタは、テーブルのスキーマ情報を生成するための 2 つのメカニズム (基本スキーマ推論と AWS Glue Data Catalog メタデータ) をサポートしています。
デフォルトでは、スキーマ推論が選択されます。このオプションは、コレクション内で少数のドキュメントをスキャンした上で、すべてのフィールドを結合して、重複しないデータ型を持つフィールドのみを選択的に使用します。このオプションは、ほとんどのエントリが同一であるコレクションに適しています。
より多くのデータ型を持つコレクションに対して、このコネクタでは、AWS Glue Data Catalog からのメタデータの取得をサポートします。DocumentDB データベースとコレクションの名前と一致する AWS Glue データベースおよびテーブルを認識した場合、このコネクタは、対応する AWS Glue テーブルからスキーマ情報を取得します。AWS Glue テーブルを作成する際には、DocumentDB コレクションからのアクセス対象となる、すべてのフィールドのスーパーセットを作成することをお勧めします。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス許可が必要です。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して DocumentDB コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して DocumentDB コネクタを設定することをお勧めします。そのためには、DocumentDB コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DOCUMENTDB
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された DocumentDB コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された DocumentDB コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (例えば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
+ **default\$1docdb** – これが存在する場合は、カタログ固有の環境変数が存在しない場合に使用する、DocumentDB の接続文字列を指定します。
+ **disable\$1projection\$1and\$1casing** – (オプション) プロジェクションおよび大文字と小文字の区別を無効にします。大文字と小文字が区別される列名を使用する Amazon DocumentDB テーブルをクエリする場合に使用します。`disable_projection_and_casing` パラメータは、次の値を使用して大文字と小文字の区別、および列のマッピングに関する動作を指定します。
+ **false** – これは、デフォルトの設定です。プロジェクションが有効になっていて、コネクタはすべての列の名前が小文字であると想定します。
+ **true** – プロジェクションおよび大文字と小文字の区別を無効にします。`disable_projection_and_casing` パラメータを使用する場合は、次の点に注意してください。
+ このパラメータを使用すると、帯域幅の使用量が増加する可能性があります。さらに、Lambda 関数がデータソースと同じ AWS リージョン にない場合、帯域幅の使用量が増えるため、標準の AWS クロスリージョン転送コストが高くなります。クロスリージョン転送コストの詳細については、「AWS Partner Network ブログ」の「[サーバーアーキテクチャおよびサーバーレスアーキテクチャの AWS データ転送料金](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)」を参照してください。
+ 転送されるバイト数が増えたため、またバイト数が多いと逆シリアル化により時間がかかるため、全体のレイテンシーが増える可能性があります。
+ **enable\$1case\$1insensitive\$1match** – (オプション) `true` の場合、Amazon DocumentDB 内のスキーマ名とテーブル名に対して大文字と小文字を区別する検索を実行します。デフォルトは `false` です。クエリに大文字のスキーマ名またはテーブル名が含まれる場合に使用します。
#### 接続文字列の指定
コネクタで使用する DocumentDB インスタンスの DocumentDB 接続の詳細を定義するために、複数のプロパティを指定できます。そのためには、Athena で使用するカタログ名と対応した Lambda の環境変数を設定します。例えば、2 つの異なる DocumentDB インスタンスに対し、Athena から次のクエリを実行するとします。
```
SELECT * FROM "docdb_instance_1".database.table
```
```
SELECT * FROM "docdb_instance_2".database.table
```
これら 2 つの SQL ステートメントを使用する際には、Lambda 関数 (`docdb_instance_1` および `docdb_instance_2`) に、2 つの環境変数を追加しておく必要があります。それぞれの値は、次の形式の DocumentDB 接続文字列にする必要があります。
```
mongodb://:@:/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0
```
##### シークレットの使用
オプションで、接続文字列の詳細の一部またはすべての値について、AWS Secrets Manager を使用できます。Athena フェデレーティッドクエリ機能を Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
Secrets Manager が提供するシークレット名を接続文字列に入れるために `${my_secret}` 構文を使用する場合、コネクタは `${my_secret}` を Secrets Manager のプレーンテキスト値にそのまま置き換えます。シークレットは、`:` 値付きのプレーンテキストのシークレットとして保存する必要があります。`{username:,password:}` として保存されたシークレットは接続文字列に正しく渡されません。
シークレットは接続文字列全体に使用することもでき、ユーザー名とパスワードはシークレット内で定義できます。
例えば、`docdb_instance_1` で Lambda 環境変数を次の値に設定した場合を考えます。
```
mongodb://${docdb_instance_1_creds}@myhostname.com:123/?ssl=true&ssl_ca_certs=rds-combined-ca-bundle.pem&replicaSet=rs0
```
Athena Query Federation SDK は、自動的に `docdb_instance_1_creds` という名前のシークレットを Secrets Manager から取得しよう試み、取得した値は `${docdb_instance_1_creds}` の場所に挿入します。接続文字列の中で、`${ }` 文字の組み合わせにより囲まれている任意の部分は、Secrets Manager から提供されたシークレットとして認識されます コネクタにより Secrets Manager 内で検出されないシークレット名を指定した場合、コネクタはテキストを置き換えません。
## 補足メタデータの取得
補足メタデータを取得するには、以下の手順に従って Glue データベースとテーブルを設定します。
### Glue データベースをセットアップする
1. DocumentDB コレクションと同じ名前の Glue データベースを作成します。
1. [ロケーション URI] フィールドに「`docdb-metadata-flag`」と入力します。
### Glue テーブルを設定する
Glue テーブルに次のパラメータを追加します。
+ `docdb-metadata-flag = true`
+ `columnMapping = apple=APPLE`
この例では、`apple` は Glue 内の小文字の列名を表し、`APPLE` は DocumentDB コレクション内の実際の大文字と小文字が区別される列名を表します。
### メタデータの取得を検証する
1. クエリを実行します。
1. メタデータの取得が成功したかどうかは、Lambda 関数の CloudWatch ログで確認します。取得に成功すると、次のログエントリが表示されます。
```
doGetTable: Retrieved schema for table[TableName{schemaName=test, tableName=profiles}] from AWS Glue.
```
**注記**
テーブルに既に `columnMapping` フィールドが設定されている場合は、テーブルプロパティに `docdb-metadata-flag = true` パラメータを追加するだけで済みます。
## AWS Glue でのデータベースとテーブルのセットアップ
コネクタに組み込まれているスキーマ推論機能がスキャンするドキュメント数には制限があり、また、データ型のサブセットのみをサポートするため、メタデータ用としては AWS Glue の使用が適しています。
Amazon DocumentDB で使用するために AWS Glue テーブルを有効にするには、DocumentDB データベース向けの AWS Glue データベーステーブルと、補足メタデータを提供する先のコレクションを用意しておく必要があります。
**補足メタデータのために AWS Glue を使用するには**
1. AWS Glue コンソールを使用して、Amazon DocumentDB データベース名と同じ名前の AWS Glue データベースを作成します。
1. **docdb-metadata-flag** が含まれるようにデータベースの URI プロパティを設定します。
1. (オプション) **sourceTable** テーブルプロパティを追加します。このプロパティは、Amazon DocumentDB 内にあるソーステーブル名を定義します。AWS Glue テーブルの名前が Amazon DocumentDB のテーブル名と異なる場合は、このプロパティを使用します。AWS Glue と Amazon DocumentDB の命名規則の違いにより、これが必要になる場合があります。例えば、AWS Glue テーブルの名前には大文字が使用できませんが、Amazon DocumentDB テーブル名としては使用が可能です。
1. (オプション) **columnMapping** テーブルプロパティを正しく追加します。このプロパティは列名のマッピングを定義します。AWS Glue 列の命名規則が原因で、Amazon DocumentDB テーブルと同じ名前の列名を持つ AWS Glue テーブルを作成できない場合は、このプロパティを使用します。Amazon DocumentDB の列名には大文字を使用できますが、AWS Glue 列名には使用できないため、このプロパティは有用です。
`columnMapping` プロパティの値は、`col1=Col1,col2=Col2` 形式のマッピングのセットであることが想定されます。
**注記**
列マッピングは最上位の列名にのみ適用され、ネストされたフィールドには適用されません。
AWS Glue`columnMapping` テーブルプロパティを正しく追加した後に、`disable_projection_and_casing` Lambda 環境変数を削除できます。
1. このドキュメントに記載されているとおり、AWS Glue 用として適切なデータ型を使用しているか確認してください。
## サポートされるデータ型
このセクションでは、DocumentDB コネクタがスキーマ推論に使用するデータ型と、AWS Glue メタデータが使用されている場合のデータ型を一覧で示します。
### スキーマ推論のデータ型
DocumentDB コネクタのスキーマ推論機能は、値を次のいずれかのデータ型に属するものとして推測しようとします。この表では、Amazon DocumentDB、Java、および Apache Arrow に対応させてデータ型を示しています。
****
| Apache Arrow | Java または DocDB |
| --- | --- |
| VARCHAR | String |
| INT | 整数 |
| BIGINT | Long |
| BIT | ブール値 |
| FLOAT4 | 浮動小数点数 |
| FLOAT8 | Double |
| TIMESTAMPSEC | 日付 |
| VARCHAR | ObjectId |
| LIST | リスト |
| STRUCT | ドキュメント |
### AWS Glue データ型
補足的メタデータ用として AWS Glue を使用する場合は、次のデータ型を設定できます。この表では、AWS Glue と Apache Arrow に対応するデータ型を示しています。
****
| AWS Glue | Apache Arrow |
| --- | --- |
| int | INT |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| boolean | BIT |
| バイナリ | VARBINARY |
| string | VARCHAR |
| リスト | LIST |
| Struct | STRUCT |
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-docdb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-docdb/athena-docdb.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス許可をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス許可を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの許可を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – DocumentDB コネクタには、スキーマ情報を取得するために、AWS Glue Data Catalog からの読み込み専用アクセスが必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **AWS Secrets Manager 読み込みアクセス** – DocumentDB エンドポイントの詳細を Secrets Manager に保存する場合は、それらのシークレットに対するアクセス許可をコネクタに付与する必要があります。
+ **VPC アクセス** – コネクタには、VPC に接続して DocumentDB インスタンスと通信するために、その VPC に対しインターフェイスをアタッチおよびデタッチする機能が必要です。
## パフォーマンス
Athena Amazon DocumentDB コネクタは現在、並列スキャンをサポートしていませんが、DocumentDB クエリの一部として述語をプッシュダウンしようとし、DocumentDB コレクションへのインデックスに対する述語は、スキャンされるデータが大幅に少なくなります。
Lambda 関数は、クエリがスキャンするデータを削減するために、射影プッシュダウンを実行します。ただし、列のサブセットを選択した場合は、クエリのランタイムが長くなることがあります。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。
## パススルークエリ
Athena Amazon DocumentDB コネクタは[パススルークエリ](federated-query-passthrough.md)をサポートしており、NoSQL ベースです。Amazon DocumentDB のクエリについては、「*Amazon DocumentDB 開発者ガイド*」の「[クエリ](https://docs.aws.amazon.com/documentdb/latest/developerguide/querying.html)」を参照してください。
Amazon DocumentDB でパススルークエリを使用するには、次の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
database => 'database_name',
collection => 'collection_name',
filter => '{query_syntax}'
))
```
次の例は、`TPCDS` コレクション内の `example` データベースをクエリし、「*Bill of Rights*」というタイトルのすべての書籍をフィルタリングします。
```
SELECT * FROM TABLE(
system.query(
database => 'example',
collection => 'tpcds',
filter => '{title: "Bill of Rights"}'
))
```
## その他のリソース
+ [Amazon Athena のフェデレーティッドクエリ](federated-queries.md)を使用して、MongoDB データベースを [Quick](https://aws.amazon.com/quicksight/) に接続し、ダッシュボードとビジュアライゼーションを構築する方法の記事については、「*AWS ビッグデータブログ*」の「[Visualize MongoDB data from Quick using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/visualize-mongodb-data-from-amazon-quicksight-using-amazon-athena-federated-query/)」を参照してください。
+ このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-docdb)を参照してください。
# Amazon Athena DynamoDB コネクタ
Amazon Athena DynamoDB コネクタは、Amazon Athena が DynamoDB とやり取りすることを可能にして、テーブルを SQL でクエリできるようにします。[INSERT INTO](insert-into.md) などの書き込み操作はサポートされていません。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス許可が必要です。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
DynamoDB 接続を Glue Catalog と Lake Formation に移行すると、小文字のテーブル名と列名のみが認識されます。
## パラメータ
このセクションのパラメータを使用して DynamoDB コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して DynamoDB コネクタを設定することをお勧めします。そのためには、DynamoDB コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type DYNAMODB
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された DynamoDB コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された DynamoDB コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。次のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (例えば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
+ **disable\$1projection\$1and\$1casing** – (オプション) プロジェクションおよび大文字と小文字の区別を無効にします。列名に大文字と小文字の区別がある DynamoDB テーブルをクエリしたいものの、AWS Glue テーブルで `columnMapping` プロパティを指定したくない場合に使用します。
`disable_projection_and_casing` パラメータは、次の値を使用して大文字と小文字の区別、および列のマッピングに関する動作を指定します。
+ **auto** – これまでサポートされていなかったタイプが検出され、列名のマッピングがテーブルに設定されていない場合、プロジェクション、および大文字と小文の区別を無効にします。これはデフォルトの設定です。
+ **always** – プロジェクション、および大文字と小文字の区別を無条件に無効にします。これは、DynamoDB の列名で大文字と小文字を区別しているものの、列名のマッピングを指定したくない場合に便利です。
`disable_projection_and_casing` パラメータを使用する場合は、次の点に注意してください。
+ このパラメータを使用すると、帯域幅の使用量が増加する可能性があります。さらに、Lambda 関数がデータソースと同じ AWS リージョン にない場合、帯域幅の使用量が増えるため、標準の AWS クロスリージョン転送コストが高くなります。クロスリージョン転送コストの詳細については、「AWS Partner Network ブログ」の「[サーバーアーキテクチャおよびサーバーレスアーキテクチャの AWS データ転送料金](https://aws.amazon.com/blogs/apn/aws-data-transfer-charges-for-server-and-serverless-architectures/)」を参照してください。
+ 転送されるバイト数が増え、またバイト数が多いと逆シリアル化により時間がかかるため、全体のレイテンシが長くなる可能性があります。
## AWS Glueでのデータベースとテーブルのセットアップ
コネクタに組み込まれたスキーマ推論機能には制限があるため、メタデータ用としては AWS Glue の使用が適しています。これを行うには、AWS Glue にデータベースとテーブルが必要です。DynamoDB で使用できるようにするには、そのプロパティを編集する必要があります。
**AWS Glue コンソールでデータベースプロパティを編集するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、**[データカタログ]** を展開し、**[データベース]** を選択します。
**[Databases]** (データベース) ページでは、既存のデータベースを編集するか、**[Add database]** (データベースを追加) を選択してデータベースを作成できます。
1. データベースのリストで、編集するデータベース用リンクを選択します。
1. **[編集]** を選択します。
1. **[Update a database]** ページの **[データベース設定]** の下で、**[ロケーション]** に、文字列 **dynamo-db-flag** を追加します。このキーワードは、Athena DynamoDB コネクタが補足メタデータに使用しているテーブルがデータベースに含まれており、`default` 以外の AWS Glue データベースに必要であることを示します。`dynamo-db-flag` プロパティは、多数のデータベースを持つアカウントのデータベースを除外する場合に便利です。
1. **[Update Database]** (データベースの更新) を選択します。
**AWS Glue コンソールでテーブルプロパティを編集するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインで、**[データカタログ]** を展開し、**[テーブル]** を選択します。
1. **[テーブル]** ページのテーブルのリストで、編集するテーブルのリンク名を選択します。
1. **[Actions]** (アクション)、**[Edit table]** (テーブルの編集) の順に選択します。
1. **[Edit table]** (テーブルの編集) ページの **[Table properties]** (テーブルプロパティ) セクションで、必要に応じて次のテーブルプロパティを追加します。AWS Glue DynamoDB クローラーを使用する場合、これらのプロパティは自動的に設定されます。
+ **dynamodb** – テーブルを補足メタデータとして使用できることを Athena DynamoDB コネクタに示す文字列。**[Classification]** (分類) (完全一致) と呼ばれるフィールドにある、テーブルプロパティの `dynamodb` 文字列を入力します。
**注記**
AWS Glue コンソールのテーブル作成プロセスの一部である **[テーブルプロパティの設定]** ページには、**[分類]** フィールドを含む **[データ形式]** セクションがあります。ここでは `dynamodb` を入力も選択もできません。代わりに、テーブルを作成した後、手順に従ってテーブルを編集し、**[テーブルプロパティ]** セクションにキー値のペアとして `classification` および `dynamodb` を入力します。
+ **sourceTable** – DynamoDB 内にあるソーステーブル名を定義するオプションのテーブルプロパティ。AWS Glue テーブルの命名規則が原因で、DynamoDB テーブルと同じ名前で AWS Glue テーブルが作成できない場合に使用します。例えば、AWS Glue テーブルの名前に大文字は許可されていませんが、DynamoDB テーブル名としては使用が可能です。
+ **columnMapping** – カラム名のマッピングを定義するオプションのテーブルプロパティ。AWS Glue 列の命名規則が原因で、DynamoDB テーブルと同じ名前の列を持つ AWS Glue テーブルを作成できない場合に使用します。例えば、AWS Glue では列名として大文字は許可されていませんが、DynamoDB の列名では使用が可能です。このプロパティ値の形式は、col1=Col1、col2=Col2 のようにします。列マッピングは最上位の列名にのみ適用され、ネストされたフィールドには適用されないことに注意してください。
+ **defaultTimeZone** – 明示的なタイムゾーンが含まれない `date` 値、および `datetime` 値に適用される、オプションのテーブルプロパティ。データソースのデフォルトタイムゾーンと Athena セッションのタイムゾーンの間に不一致が生じないようにするためには、この値を設定することが適切です。
+ **datetimeFormatMapping** – AWS Glue `date` または `timestamp` データ型の列のデータを解析する際に、`date` または `datetime` 形式が使用されること指定する、オプションのテーブルプロパティ。このプロパティが指定されていない場合、コネクタは ISO-8601 形式が使用されるものと[推定](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/time/DateFormatUtils.html)します。コネクタが `date` または `datetime` 形式を推定できない、あるいは未加工の文字列を解析できない場合、この値は結果から除外されます。
`datetimeFormatMapping` 値は、`col1=someformat1,col2=someformat2` 形式である必要があります。次に形式の例をいくつか示します。
```
yyyyMMdd'T'HHmmss
ddMMyyyy'T'HH:mm:ss
```
列にタイムゾーンのない `date` または `datetime` 値が含まれており、その列を `WHERE` 句で使用したい場合には、対象の列で `datetimeFormatMapping` プロパティを設定します。
1. 手動で列を定義する場合は、適切なデータ型を使用するように注意してください。クローラーを使用している場合は、クローラーが検出した列とタイプを確認します。
1. **[保存]** を選択します。
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-dynamodb.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-dynamodb/athena-dynamodb.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス許可をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス許可を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの許可を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – DynamoDB コネクタには、スキーマ情報を取得するために、AWS Glue Data Catalog に対する読み込み専用アクセスが必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **DynamoDB 読み込みアクセス** – このコネクタでは、`DescribeTable`、`ListSchemas`、`ListTables`、`Query`、および `Scan` のAPI オペレーションを使用します。
## パフォーマンス
Athena DynamoDB コネクタは並列スキャンをサポートしており、DynamoDB クエリの一部として述語のプッシュダウンを試みます。`X` が異なる値を持つハッシュキー述語を使用すると、DynamoDB に対する `X` クエリ呼び出しが発生します。他のすべての述語シナリオでは、スキャン呼び出しの数が `Y` となります。この際 `Y` は、テーブルのサイズとプロビジョニングされたスループットに基づいて、ヒューリスティックに決定されます。ただし、列のサブセットを選択すると、クエリのランタイムが長くなる場合があります。
`LIMIT` 句と単純な述語がプッシュダウンされるため、スキャンされるデータの量が減少し、クエリ実行のランタイムの短縮につながります。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。機能を強化し、スキャンされるデータの量を減らすために、Athena DynamoDB コネクタはこれらの式を組み合わせて、DynamoDB に直接プッシュできます。
次の Athena DynamoDB コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10 and col_b < 10
LIMIT 10
```
DynamoDB などのフェデレーテッドクエリのパフォーマンスを向上させるために述語プッシュダウンを使用する方法の記事については、「*AWS Big Data Blog*」の「[Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)」を参照してください。
## パススルークエリ
DynamoDB コネクタは[パススルークエリ](federated-query-passthrough.md)をサポートし、PartiQL 構文を使用します。DynamoDB [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) API オペレーションはサポートされません。PartiQL を使用した DynamoDB のクエリに関する詳細については、「*Amazon DynamoDB デベロッパーガイド*」の「[PartiQL select statements for DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ql-reference.select.html)」を参照してください。
DynamoDB でパススルークエリを使用するには、次の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
query => 'query_string'
))
```
次の DynamoDB パススルークエリ例は、PartiQL を使用して、2022 年 12 月 24 日より後の `DateWatched` プロパティを持つ Fire TV Stick デバイスのリストを返します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT Devices
FROM WatchList
WHERE Devices.FireStick.DateWatched[0] > '12/24/22''
))
```
## トラブルシューティング
### ソートキー列上の複数フィルター
**エラーメッセージ**: KeyConditionExpression にはキーごとに 1 つの条件のみを含める必要があります
**原因**: この問題は、Athena エンジンバージョン 3 で、DynamoDB ソートキー列上に下限フィルターと上限フィルターの両方があるクエリで発生する可能性があります。DynamoDB はソートキー上で複数のフィルター条件をサポートしていないため、両方の条件が適用されたクエリをコネクタがプッシュダウンしようとするとエラーが発生します。
**解決策**: コネクタをバージョン 2023.11.1 以降に更新します。コネクタを更新する手順については、「[データソースコネクタを更新する](connectors-updating.md)」を参照してください。
## コスト
コネクタの使用料金は、基礎として使用されている AWS リソースによって異なります。スキャンを使用するクエリでは、大量の[リードキャパシティーユニット (RCU)](https://aws.amazon.com/dynamodb/pricing/provisioned/) を利用することがあるため、「[Amazon DynamoDB pricing」](https://aws.amazon.com/dynamodb/pricing/) (Amazon DynamoDB の料金) に記載された情報を慎重に検討してください。
## その他のリソース
+ Amazon Athena DynamoDB コネクタの使用方法の概要については、「*AWS Prescriptive Guidance Patterns*」ガイドの「[Access, query, and join Amazon DynamoDB tables using Athena](https://docs.aws.amazon.com/prescriptive-guidance/latest/patterns/access-query-and-join-amazon-dynamodb-tables-using-athena.html)」を参照してください。
+ Athena DynamoDB コネクタを使用して SQL で DynamoDB 内のデータをクエリし、Quick 内のインサイトを視覚化する方法については、AWS Big Data Blog 記事「[Visualize Amazon DynamoDB insights in Quick using the Amazon Athena DynamoDB connector and AWS Glue](https://aws.amazon.com/blogs/big-data/visualize-amazon-dynamodb-insights-in-amazon-quicksight-using-the-amazon-athena-dynamodb-connector-and-aws-glue/)」を参照してください。
+ Amazon Athena DynamoDB コネクタを、Amazon DynamoDB、Athena、Quick と共に使用して、シンプルなガバナンスダッシュボードを作成する方法については、「*AWS Big Data Blog*」の記事「[Query cross-account Amazon DynamoDB tables using Amazon Athena Federated Query](https://aws.amazon.com/blogs/big-data/query-cross-account-amazon-dynamodb-tables-using-amazon-athena-federated-query/)」を参照してください。
+ このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-dynamodb)を参照してください。
# Amazon Athena Google BigQuery コネクタ
Google [BigQuery](https://cloud.google.com/bigquery/) のために Amazon Athena コネクタを使用すると、Amazon Athena から、Google BigQuery のデータに対する SQL クエリを実行できるようになります。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ Lambda 関数における最大タイムアウト時間は 15 分です。分割が発生するたびに BigQuery に対しクエリが実行されます。Athena が読み込む結果を保存するためには、十分な時間のクエリが必要です。Lambda 関数がタイムアウトした場合には、クエリは失敗します。
+ Google BigQuery では、大文字と小文字が区別されます。コネクタは、データセット名、テーブル名、プロジェクト ID の大文字と小文字の修正を試みます。これが必要なのは、Athena では、すべてのメタデータを小文字で扱うからです。これらの修正により、Google BigQuery への余分な呼び出しが多数発生します。
+ 二進数のデータ型はサポートされません。
+ Google BigQuery の同時実行性とクォータについての制限が原因で、コネクタにおいて、Google のクォータ制限に関する問題が発生する場合があります。このような問題を回避するには、可能な限り多くの制約 を Google BigQuery に適用します。BigQuery でのクォータの詳細については、Google BigQuery のドキュメントで「[割り当てと上限](https://cloud.google.com/bigquery/quotas)」を参照してください。
## パラメータ
このセクションのパラメータを使用して Google BigQuery コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Google BigQuery コネクタを設定することをお勧めします。そのためには、Google BigQuery コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type BIGQUERY
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Google BigQuery コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Google BigQuery コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **gcp\$1project\$1id** – コネクタの読み込み対象となるデータセットを含むプロジェクト ID (プロジェクト名ではありません、例:`semiotic-primer-1234567`)。
+ **secret\$1manager\$1gcp\$1creds\$1name** – JSON 形式の BigQuery 認証情報が含まれている、AWS Secrets Manager 内のシークレットの名前 (例: `GoogleCloudPlatformCredentials`)。
+ **big\$1query\$1endpoint** — (オプション) BigQuery プライベートエンドポイントの URL。このパラメータは、プライベートエンドポイント経由で BigQuery にアクセスする場合に使用します。
## 分割とビュー
BigQuery コネクタはテーブルのクエリに BigQuery Storage Read API を使用し、BigQuery Storage API はビューをサポートしないため、コネクタはビューに単一の分割を用いる BigQuery クライアントを使用します。
## パフォーマンス
BigQuery コネクタはテーブルのクエリに BigQuery Storage Read API を使用し、この API は BigQuery マネージドストレージへの迅速なアクセスを提供する RPC ベースのプロトコルを使用します。BigQuery Storage Read API の詳細については、Google Cloud ドキュメントの「[Use the BigQuery Storage Read API to read table data](https://cloud.google.com/bigquery/docs/reference/storage)」を参照してください。
列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。このコネクタは、同時実行数が増えるとクエリに失敗する可能性があり、一般に動作が遅いコネクタです。
Athena Google BigQuery コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、`ORDER BY` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 上位 N 件のクエリ
上位 `N` 件のクエリは、結果セットの順序と返される行数に対する制限を指定します。このタイプのクエリを使用して、データセットの上位 `N` 個の最大値または上位 `N` 個の最小値を決定できます。上位 `N` 件のプッシュダウンを使用すると、コネクタは `N` 件の順序付けられた行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Google BigQuery コネクタは、これらの式を組み合わせて Google BigQuery に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Google BigQuery コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
ORDER BY col_a DESC
LIMIT 10;
```
## パススルークエリ
Google BigQuery コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Google BigQuery でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Google BigQuery 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
Amazon Athena Google BigQuery コネクタプロジェクトは、[Apache-2.0 ライセンス](https://www.apache.org/licenses/LICENSE-2.0.html)の下で使用許諾されています。
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)を参照してください。
# Amazon Athena Google Cloud Storage コネクタ
Amazon Athena Google Cloud Storage コネクタを使用すると、Amazon Athena は、Google Cloud Storage (GCS) バケットに保存されている Parquet および CSV ファイルに対してクエリを実行できます。1 つ以上の Parquet ファイルまたは CSV ファイルを GCS バケットの未分割または分割されたフォルダーにグループ化すると、[AWS Glue](https://aws.amazon.com/glue/) データベーステーブルに整理できます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
Athena を使用して GCS バケット内の Parquet ファイルまたは CSV ファイルに対してクエリを実行する方法については、AWS Big Data Blog 記事「[Use Amazon Athena to query data stored in Google Cloud Platform](https://aws.amazon.com/blogs/big-data/use-amazon-athena-to-query-data-stored-in-google-cloud-platform/)」を参照してください。
## 前提条件
+ Google Cloud Storage のバケットとフォルダに対応する AWS Glue データベースとテーブルを設定します。手順については、このドキュメントの後半にある「[AWS Glue でのデータベースとテーブルのセットアップ](#connectors-gcs-setting-up-databases-and-tables-in-glue)」を参照してください。
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ 現在、コネクタはパーティション列 (AWS Glue テーブルスキーマにある `string` または `varchar`) の `VARCHAR` タイプのみをサポートしています。他のパーティションフィールドタイプでは、Athena でクエリを実行するとエラーが発生します。
## 用語
GCS コネクタに関連する用語を次に示します。
+ **ハンドラー** — GCS バケットにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – GCS バケットからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – GCS バケットからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — GCS バケットからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
## サポートされているファイルの種類
GCS コネクタは Parquet ファイルタイプと CSV ファイルタイプをサポートしています。
**注記**
CSV ファイルと Parquet ファイルの両方を同じ GCS バケットまたはパスに配置しないようにしてください。これを行うと、Parquet ファイルを CSV として読み込もうとしたり、その逆を行おうとしたりするため、ランタイムエラーが発生する可能性があります。
## パラメータ
このセクションのパラメータを使用して GCS コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して GCS コネクタを設定することをお勧めします。そのためには、GCS コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type GOOGLECLOUDSTORAGE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された GCS コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された GCS コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **secret\$1manager\$1gcp\$1creds\$1name** – JSON 形式の GCS 認証情報が含まれている、AWS Secrets Manager 内のシークレットの名前 (例: `GoogleCloudPlatformCredentials`)。
## AWS Glue でのデータベースとテーブルのセットアップ
GCS コネクタの組み込みスキーマ推論機能には制限があるため、AWS Glue メタデータに使用することをお勧めします。以下の手順では、AWS Glue で Athena からアクセスできるデータベースとテーブルを作成する方法を示しています。
### AWS Glue でデータベースを作成する
AWS Glue コンソールを使用して、GCS コネクタで使用するデータベースを作成できます。
**AWS Glue にデータベースを作成するには**
1. AWS マネジメントコンソール にサインインし、AWS Glue コンソール ([https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/)) を開きます。
1. ナビゲーションペインから、**[Databases]** (データベース) を選択します。
1. **[Add database]** (データベースの追加) を選択します。
1. **[Name]** (名前) には、GCS コネクタで使用するデータベースの名前を入力します。
1. **[場所]** に、`google-cloud-storage-flag` を指定します。この場所は、AWS Glue データベースに Athena でクエリされる GCS データのテーブルが含まれていることを GCS コネクタに伝えます。コネクタは、このフラグのある Athena 内のデータベースを認識し、そうでないデータベースは無視します。
1. **[データベースの作成]** を選択します。
### AWS Glue でのテーブルの作成
これで、データベース用のテーブルを作成できるようになりました。GCS コネクタで使用する AWS Glue テーブルを作成するときは、追加のメタデータを指定する必要があります。
**AWS Glue コンソールでテーブルを作成するには**
1. AWS Glue コンソールで、ナビゲーションペインから **[Tables]** (テーブル) を選択します。
1. **[Tables]** (テーブル) ページで、**[Add table]** (テーブルの追加) を選択します。
1. **[Set table properties]** (テーブルプロパティの設定) ページで、次の情報を入力します。
+ **名前** – テーブル用に一意の名前を入力します。
+ **データベース** — GCS コネクタ用に作成した AWS Glue データベースを選択します。
+ **インクルードパス** — **[Data store]** (データストア) セクションの **[Include path]** (インクルードパス) に、`gs://` で始まる GCS の URI の場所を入力します (例: `gs://gcs_table/data/`)。パーティションフォルダが 1 つ以上ある場合は、パスに含めないでください。
**注記**
`s3://` テーブル以外のパスを入力すると、AWS Glue コンソールにエラーが表示されます。このエラーは無視して構いません。テーブルは正常に作成されます。
+ **データ形式** — **[Classification]** (分類) には、**[CSV]** または **[Parquet]** を選択します。
1. [**次へ**] を選択します。
1. **[Choose or define schema]** (スキーマの選択または定義) ページでは、テーブルスキーマの定義を強く推奨していますが、必須ではありません。スキーマを定義しない場合、GCS コネクタは自動的にスキーマを推測しようとします。
次のいずれかを行います。
+ GCS コネクタに自動的にスキーマを推測させたい場合は、**[Next]** (次へ) を選択してから **[Create]** (作成) を選択します。
+ 自分でスキーマを定義するには、次のセクションの手順に従います。
### AWS Glue でのテーブルスキーマの定義
AWS Glue でテーブルスキーマを定義すると、より多くの手順が必要になりますが、テーブル作成プロセスをより細かく制御できます。
**AWS Glue でテーブルのスキーマを定義するには**
1. **[Choose or define schema]** (スキーマの選択または定義) ページで、**[Add]** (追加) を選択します。
1. **[Add schema entry]** (スキーマエントリの追加) ダイアログボックスを使用して、列名とデータタイプを指定します。
1. 列をパーティション列として指定するには、**[Set as partition key]** (パーティションキーとして設定) オプションを選択します。
1. **[Save]** (保存) を選択して列を保存します。
1. さらに他の列を追加するには、**[Add]** (追加) を選択します。
1. 列の追加が完了したら、**[Next]** (次へ) を選択します。
1. **[Review and create]** (確認して作成) ページで、テーブルを確認し、**[Create]** (作成) を選択します。
1. スキーマにパーティション情報が含まれている場合は、次のセクションの手順に従って、AWS Glue のテーブルのプロパティにパーティションパターンを追加します。
### AWS Glue のテーブルプロパティへのパーティションパターンの追加
GCS バケットにパーティションがある場合は、AWS Glue のテーブルのプロパティにパーティションパターンを追加する必要があります。
**テーブルプロパティ AWS Glue にパーティション情報を追加するには**
1. AWS Glue で作成したテーブルの詳細ページで、**[Actions]** (アクション)、**[Edit]** (編集) の順に選択します。
1. **[Edit table]** (テーブルの編集) ページで、**[Table properties]** (テーブルプロパティ) セクションまで下にスクロールします。
1. **[Add]** (追加) を選択して、パーティションキーを追加します。
1. **[Key]** (キー) に「**partition.pattern**」と入力します。このキーはフォルダーパスパターンを定義します。
1. **[Value]** (値) には、**StateName=\$1\$1statename\$1/ZipCode=\$1\$1zipcode\$1/** のようなフォルダーパスパターンを入力します。**\$1\$1\$1** で囲まれた **statename** と **zipcode** はパーティションの列名です。GCS コネクタは、Hive パーティションスキームと Hive 以外のパーティションスキームの両方をサポートします。
1. 完了したら、[**Save **] を選択します。
1. 作成したばかりのテーブルプロパティを表示するには、**[Advanced properties]** (詳細プロパティ) タブを選択します。
この時点で、Athena コンソールに移動できます。AWS Glue で作成したデータベースとテーブルは、Athena でクエリできます。
## サポートされるデータ型
次の表に、CSV と Parquet 向けにサポートされているデータ型を示します。
### CSV
****
| **[Nature of data]** (データの性質) | **[Inferred Data Type]** (推定されたデータ型) |
| --- | --- |
| 数字のように見えるデータ | BIGINT |
| 文字列のように見えるデータ | VARCHAR |
| 浮動小数点 (浮動小数点、倍精度浮動小数点、10 進数) のように見えるデータ | DOUBLE |
| 日付のように見えるデータ | タイムスタンプ |
| true/false の値を含むデータ | BOOL |
### Parquet
****
| **[PARQUET]** | **[Athena (Arrow)]** (Athena (矢印)) |
| --- | --- |
| BINARY | VARCHAR |
| BOOLEAN | BOOL |
| DOUBLE | DOUBLE |
| ENUM | VARCHAR |
| FIXED\$1LEN\$1BYTE\$1ARRAY | DECIMAL |
| FLOAT | FLOAT (32 ビット) |
| INT32 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-gcs.html) |
| INT64 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-gcs.html) |
| INT96 | タイムスタンプ |
| MAP | MAP |
| STRUCT | STRUCT |
| LIST | LIST |
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-gcs.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/athena-gcs.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – GCS コネクタには、スキーマ情報を取得するために AWS Glue Data Catalog への読み取り専用アクセス権が必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
## パフォーマンス
テーブルスキーマにパーティションフィールドが含まれていて、`partition.pattern` テーブルプロパティが正しく設定されている場合は、クエリの `WHERE` 句にパーティションフィールドを含めることができます。このようなクエリの場合、GCS コネクタはパーティション列を使用して GCS フォルダーのパスを絞り込み、GCS フォルダー内の不要なファイルをスキャンしないようにします。
Parquet データセットには、列のサブセットを選択すると、スキャンされるデータが少なくなります。通常、これにより、列プロジェクションが適用されるときのクエリ実行時間が短くなります。
CSV データセットでは列の投影はサポートされていないため、スキャンされるデータ量が減ることはありません。
`LIMIT` 句はスキャンされるデータ量を削減しますが、述語が提供されない場合は、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。GCS コネクタでは、`LIMIT` 句が適用されているかに関わらず、小さいデータセットよりも大きいデータセットに対する方が、多くのデータをスキャンします。例えば、クエリ `SELECT * LIMIT 10000` は、小さな基盤データセットよりも大きな基盤データセットに対して、より多くのデータをスキャンします。
### ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-gcs/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
### その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-gcs)を参照してください。
# Amazon Athena HBase コネクタ
Amazon Athena HBase コネクタは、Amazon Athena での Apache HBase インスタンスとの通信を可能にし、HBase データを SQL でクエリできるようにします。
従来のリレーショナルデータストアとは異なり、HBase コレクションにはスキーマが設定されていません。HBase にはメタデータストアがありません。HBase コレクションの各エントリには、異なるフィールドとデータ型を設定できます。
HBase コネクタは、テーブルスキーマ情報を生成するために、基本スキーマ推論と AWS Glue Data Catalog メタデータの 2 つのメカニズムをサポートしています。
デフォルトでは、スキーマ推論が選択されます。このオプションは、コレクション内の少数のドキュメントをスキャンし、すべてのフィールドの合併集合を作成して、強制的にフィールドのデータ型が重複しないようにします。このオプションは、ほとんどのエントリが同一であるコレクションに適しています。
より多くのデータ型を持つコレクションに対して、このコネクタでは、AWS Glue Data Catalog からのメタデータの取得をサポートします。HBase 名前空間およびコレクション名と一致する AWS Glue データベースとテーブルがある場合、コネクタは対応する AWS Glue テーブルからスキーマ情報を取得します。AWS Glue テーブルを作成するときは、HBase コレクションからアクセスする可能性のあるすべてのフィールドのスーパーセットにすることをお勧めします。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して HBase コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して HBase コネクタを設定することをお勧めします。そのためには、HBase コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type HBASE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された HBase コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された HBase コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
+ **default\$1hbase** – 存在する場合、カタログ固有の環境変数が存在しない場合に使用する HBase 接続文字列を指定します。
+ **enable\$1case\$1insensitive\$1match** – (オプション) `true` の場合、HBase 内のテーブル名に対して大文字と小文字を区別しない検索を実行します。デフォルトは `false` です。クエリに大文字のテーブル名が含まれる場合に使用します。
#### 接続文字列の指定
コネクタで使用する HBase インスタンスの HBase 接続の詳細を定義する 1 つまたは複数のプロパティを指定できます。そのためには、Athena で使用するカタログ名と対応した Lambda の環境変数を設定します。例えば、次のクエリを使用して、Athena の 2 つの異なる HBase インスタンスにクエリを実行するとします。
```
SELECT * FROM "hbase_instance_1".database.table
```
```
SELECT * FROM "hbase_instance_2".database.table
```
これら 2 つの SQL ステートメントを使用する際には、Lambda 関数 (`hbase_instance_1` および `hbase_instance_2`) に、2 つの環境変数を追加しておく必要があります。それぞれの値は、次の形式の HBase 接続文字列になります。
```
master_hostname:hbase_port:zookeeper_port
```
##### シークレットの使用
オプションで、接続文字列の詳細の一部またはすべての値について、AWS Secrets Manager を使用できます。Athena フェデレーティッドクエリ機能を Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
Secrets Manager が提供するシークレット名を接続文字列に入れるために `${my_secret}` 構文を使用する場合、コネクタは、シークレット名を Secrets Manager のユーザー名とパスワードの値に置き換えます。
たとえば、`hbase_instance_1` で Lambda 環境変数を次の値に設定した場合を考えます。
```
${hbase_host_1}:${hbase_master_port_1}:${hbase_zookeeper_port_1}
```
Athena Query Federation SDK は、自動的に `hbase_instance_1_creds` という名前のシークレットを Secrets Manager から取得しよう試み、取得した値は `${hbase_instance_1_creds}` の場所に挿入します。接続文字列の中で、`${ }` 文字の組み合わせにより囲まれている任意の部分は、Secrets Manager から提供されたシークレットとして認識されます コネクタにより Secrets Manager 内で検出されないシークレット名を指定した場合、コネクタはテキストを置き換えません。
## AWS Glue でのデータベースとテーブルのセットアップ
コネクタの組み込みスキーマ推論は、HBase で文字列としてシリアル化された値のみをサポートします (例: `String.valueOf(int)`)。コネクタの組み込みスキーマ推論機能は限られているため、代わりにメタデータに AWS Glue を使用したい場合があるかもしれません。HBase で使用するために AWS Glue テーブルを有効にするには、補足メタデータを供給したい HBase 名前空間とテーブルに一致する名前の AWS Glue データベースとテーブルが必要です。HBase 列ファミリーの命名規則の使用はオプションで、必須ではありません。
**補足メタデータのために AWS Glue を使用するには**
1. AWS Glue コンソールでテーブルとデータベースを編集する場合は、次のテーブルプロパティを追加します。
+ **hbase-metadata-flag** – このプロパティは、補足メタデータのテーブルをコネクタが使用できることを HBase コネクタに示します。`hbase-metadata-flag` プロパティがテーブルプロパティのリスト内に存在するのであれば、この `hbase-metadata-flag` に任意の値を指定することが可能です。
+ **hbase-native-storage-flag** – このフラグを使用して、コネクタでサポートされている 2 つの値のシリアル化モードを切り替えます。デフォルトでは、このフィールドが存在しない場合、コネクタはすべての値が HBase に文字列として格納されていると見なします。そのため、HBase からの `INT`、`BIGINT`、`DOUBLE` などのデータ型を文字列として解析しようとします。このフィールドに AWS Glue のテーブルのいずれかの値が設定されている場合、コネクタは「ネイティブ」ストレージモードに切り替わり、次の関数を使用して `INT`、`BIGINT`、`BIT`、および `DOUBLE` をバイトとして読み取ろうとします。
```
ByteBuffer.wrap(value).getInt()
ByteBuffer.wrap(value).getLong()
ByteBuffer.wrap(value).get()
ByteBuffer.wrap(value).getDouble()
```
1. このドキュメントに記載されているとおりに、AWS Glue 用として適切なデータ型を使用しているか確認してください。
### 列ファミリーのモデリング
Athena HBase コネクタは HBase 列ファミリーをモデル化する 2 つの方法 (`family:column` のような完全修飾 (フラット) 命名法、または `STRUCT` オブジェクトの使用) をサポートしています。
`STRUCT` モデルでは、`STRUCT` フィールドの名前は列ファミリーと一致し、`STRUCT` の子要素はファミリーの列の名前と一致するようになっています。ただし、述語プッシュダウンと列指向の読み込みが `STRUCT` のような複合型ではまだ完全にはサポートされていないので、`STRUCT` の使用は現時点では推奨されていません。
次の画像は、2 つのアプローチを組み合わせて使用している AWS Glue で設定されたテーブルを示しています。
![\[Apache HBase 用の AWS Glue での列ファミリーのモデル化。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-hbase-1.png)
## サポートされるデータ型
コネクタはすべての HBase 値を基本バイト型として取得します。次に、AWS Glue データカタログでテーブルをどのように定義したかに基づいて、値を次の表の Apache Arrow データ型の 1 つにマッピングします。
****
| AWS Glue データ型 | Apache Arrow データ型 |
| --- | --- |
| int | INT |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| boolean | BIT |
| バイナリ | VARBINARY |
| string | VARCHAR |
**注記**
AWS Glue を使用してメタデータを補足しない場合、コネクタのスキーマ推論ではデータ型 `BIGINT`、`FLOAT8`、および `VARCHAR` のみを使用します。
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-hbase.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hbase/athena-hbase.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – HBase コネクタには、スキーマ情報を取得するために AWS Glue Data Catalog への読み込み専用アクセス権が必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **AWS Secrets Manager 読み込みアクセス** – HBase エンドポイントの詳細を Secrets Manager に保存する場合は、それらのシークレットへのアクセスをコネクタに許可する必要があります。
+ **VPC アクセス** – コネクタには、VPC に接続して HBase インスタンスと通信できるように、VPC にインターフェイスをアタッチおよびデタッチできることが必要です。
## パフォーマンス
Athena HBase コネクタは、各リージョンサーバーを並行して読み込むことによって、HBase インスタンスに対するクエリを並列化しようとします。Athena HBase コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。
また、Lambda 関数は、クエリがスキャンするデータを削減するために、射影プッシュダウンを実行します。ただし、列のサブセットを選択した場合は、クエリのランタイムが長くなることがあります。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。
HBase はクエリに失敗しやすく、クエリの実行時間が変動しやすいです。クエリを正常に実行するために、何度も再試行する必要がある場合があります。HBase コネクタは同時実行によるスロットリングに強いです。
## パススルークエリ
HBase コネクタは[パススルークエリ](federated-query-passthrough.md)をサポートしており、NoSQL ベースです。Apache HBase のクエリに関する詳細については、Apache ドキュメントの「[Filter language](https://hbase.apache.org/book.html#thrift.filter_language)」を参照してください。
HBase でパススルークエリを使用するには、以下の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
database => 'database_name',
collection => 'collection_name',
filter => '{query_syntax}'
))
```
以下の HBase パススルークエリ例は、`default` データベースの `employee` コレクション内で 24 歳または 30 歳の従業員をフィルタリングします。
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'default',
COLLECTION => 'employee',
FILTER => 'SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:30'')' ||
' OR SingleColumnValueFilter(''personaldata'', ''age'', =, ''binary:24'')'
))
```
## ライセンス情報
Amazon Athena HBase コネクタプロジェクトは、[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) でライセンスされています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hbase)を参照してください。
# Amazon Athena Hortonworks コネクタ
Hortonworks 用の Amazon Athena コネクタを使用すると、Amazon Athena で Cloudera [Hortonworks](https://www.cloudera.com/products/hdp.html) データプラットフォームに SQL クエリを実行できます。コネクタによって Athena SQL クエリは同等の HiveQL 構文に変換されます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
## 用語
Hortonworks Hive コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Hortonworks Hive コネクタを設定します。
### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
hive://${jdbc_connection_string}
```
### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | HiveMuxCompositeHandler |
| メタデータハンドラー | HiveMuxMetadataHandler |
| レコードハンドラー | HiveMuxRecordHandler |
#### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myhivecatalog の場合、環境変数の名前は myhivecatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
以下に、2 つのデータベースインスタンス (デフォルト値の `hive1`、および `hive2`) をサポートする、Hive MUX Lambda 関数のプロパティ例を示します。
****
| プロパティ | 値 |
| --- | --- |
| default | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 |
| hive\$1catalog1\$1connection\$1string | hive://jdbc:hive2://hive1:10000/default?\$1\$1Test/RDS/hive1\$1 |
| hive\$1catalog2\$1connection\$1string | hive://jdbc:hive2://hive2:10000/default?UID=sample&PWD=sample |
#### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/hive1host}` が含まれています。
```
hive://jdbc:hive2://hive1host:10000/default?...&${Test/RDS/hive1host}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
hive://jdbc:hive2://hive1host:10000/default?...&UID=sample2&PWD=sample2&...
```
現在、Hortonworks Hive コネクタは `UID` と `PWD` の JDBC プロパティを認識します。
### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Hortonworks Hive インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | HiveCompositeHandler |
| メタデータハンドラー | HiveMetadataHandler |
| レコードハンドラー | HiveRecordHandler |
#### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Hortonworks Hive インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | hive://jdbc:hive2://hive1host:10000/default?secret=\$1\$1Test/RDS/hive1host\$1 |
### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC、Hortonworks Hive、および Arrow の間で対応するデータ型を示します。
****
| JDBC | Hortonworks Hive | Arrow |
| --- | --- | --- |
| ブール値 | ブール値 | Bit |
| 整数 | TINYINT | Tiny |
| ショート | SMALLINT | Smallint |
| 整数 | INT | Int |
| Long | BIGINT | Bigint |
| float | float4 | Float4 |
| ダブル | float8 | Float8 |
| 日付 | date | DateDay |
| タイムスタンプ | timestamp | DateMilli |
| String | VARCHAR | Varchar |
| バイト | bytes | Varbinary |
| BigDecimal | 10 進数 | 10 進数 |
| 配列 | 該当なし (注記を参照) | リスト |
**注記**
現在、Hortonworks Hive は集計型 `ARRAY`、`MAP`、`STRUCT`、`UNIONTYPE` をサポートしていません。集計型の列は、SQL における `VARCHAR` 列のように扱われます。
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
Hortonworks Hive は静的パーティションをサポートしています。Athena Hortonworks Hive コネクタは、これらのパーティションからデータを並列に取得できます。パーティション分散が一様で非常に大きなデータセットをクエリする場合は、静的パーティショニングの使用を強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。Hortonworks Hive コネクタは同時実行によるスロットリングに強いです。
Athena Hortonworks Hive コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Hortonworks Hive コネクタは、これらの式を組み合わせて Hortonworks Hive に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Hortonworks Hive コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
Hortonworks Hive コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Hortonworks Hive でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Hortonworks Hive 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Hortonworks Hive コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-hortonworks-hive/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-hortonworks-hive)を参照してください。
# Amazon Athena の Apache Kafka コネクタ
Apache Kafka 用の Amazon Athena コネクタを使用して、Amazon Athena で Apache Kafka トピックに対して SQL クエリを実行できます。このコネクタを使用すると、[Apache Kafka](https://kafka.apache.org/) トピックをテーブルとして、メッセージを Athena の行として表示できます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件における日付とタイムスタンプのデータ型は、適切なデータ型にキャストする必要があります。
+ 日付とタイムスタンプのデータ型は、CSV ファイルタイプではサポートされていないため、varchar 値として扱われます。
+ ネストされた JSON フィールドへのマッピングはサポートされていません。コネクタは最上位のフィールドのみをマッピングします。
+ コネクタは複合型をサポートしていません。複合型は文字列として解釈されます。
+ 複合型の JSON 値を抽出または処理するには、Athena に用意されている JSON 関連の関数を使用してください。詳細については、「[文字列から JSON データを抽出する](extracting-data-from-JSON.md)」を参照してください。
+ コネクタは、Kafka メッセージメタデータへのアクセスをサポートしていません。
## 用語
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **Kafka エンドポイント** - Kafka インスタンスへの接続を確立するテキスト文字列。
## クラスター間の互換性
Kafka コネクタは、次のクラスタータイプで使用できます。
+ **スタンドアロン Kafka** - Kafka への直接の接続 (認証または非認証)。
+ **Confluent** — Confluent Kafka への直接接続。Confluent Kafka データに Athena を使用する方法については、「AWS Business Intelligence Blog」の「[Visualize Confluent data in Quick using Amazon Athena](https://aws.amazon.com/blogs/business-intelligence/visualize-confluent-data-in-amazon-quicksight-using-amazon-athena/)」を参照してください。
### Confluent への接続
Confluent への接続には次の手順が必要です。
1. Confluent から API キーを生成する。
1. Confluent API キーのユーザー名とパスワードを入力する。AWS Secrets Manager
1. Kafka コネクターの `secrets_manager_secret` 環境変数にシークレット名を指定します。
1. このドキュメントの [Kafka コネクタのセットアップ](#connectors-kafka-setup) セクションの手順に従ってください。
## サポートされた認証方法
コネクタでは、次の認証方法がサポートされています。
+ [SSL](https://kafka.apache.org/documentation/#security_ssl)
+ [SASL/SCRAM](https://kafka.apache.org/documentation/#security_sasl_scram)
+ SASL/PLAIN
+ SASL/PLAINTEXT
+ NO\$1AUTH
+ **セルフマネージド型の Kafka と Confluent Platform** — SSL、SASL/SCRAM、SASL/プレーンテキスト、NO\$1AUTH
+ **セルフマネージド型の Kafka および Confluent Cloud** — SASL/PLAIN
詳細については、「[Athena Kafka コネクタの認証を設定](#connectors-kafka-setup-configuring-authentication)」を参照してください。
## 対応する入力データ形式
コネクタは、次の入力データ形式をサポートします。
+ JSON
+ CSV
+ AVRO
+ PROTOBUF (PROTOCOL BUFFERS)
## パラメータ
このセクションのパラメータを使用して Athena Kafka コネクタを設定します。
+ **auth\$1type** - クラスターの認証タイプを指定します。コネクタは、次のタイプの認証をサポートしています。
+ **NO\$1AUTH** - Kafka に直接接続します (例えば、認証を使用しない EC2 インスタンスにデプロイされた Kafka クラスターなど)。
+ **SASL\$1SSL\$1PLAIN** - このメソッドは、`SASL_SSL` セキュリティプロトコルと `PLAIN` SASL メカニズムを使用します。詳細については、Apache Kafka ドキュメントの「[SASL 設定](https://kafka.apache.org/documentation/#security_sasl_config)」を参照してください。
+ **SASL\$1PLAINTEXT\$1PLAIN** - このメソッドは、`SASL_PLAINTEXT` セキュリティプロトコルと `PLAIN` SASL メカニズムを使用します。詳細については、Apache Kafka ドキュメントの「[SASL 設定](https://kafka.apache.org/documentation/#security_sasl_config)」を参照してください。
+ **SASL\$1SSL\$1SCRAM\$1SHA512** - この認証タイプを使用して Apache Kafka クラスターへのアクセスを制御できます。このメソッドでは、ユーザー名とパスワードを AWS Secrets Manager に保存します。シークレットは Kafka クラスターに関連付けられている必要があります。詳細については、Apache Kafka ドキュメントの「[SASL/SCRAM を使用する認証](https://kafka.apache.org/documentation/#security_sasl_scram)」を参照してください。
+ **SASL\$1PLAINTEXT\$1SCRAM\$1SHA512** - このメソッドは、`SASL_PLAINTEXT` セキュリティプロトコルと `SCRAM_SHA512 SASL` メカニズムを使用します。このメソッドでは、AWS Secrets Manager に保存したユーザー名とパスワードを使用します。詳細については、Apache Kafka ドキュメントの「[SASL 設定](https://kafka.apache.org/documentation/#security_sasl_config)」セクションを参照してください。
+ **SSL** - SSL 認証では、キーストアとトラストストアのファイルを使用して Apache Kafka クラスターに接続します。トラストストアファイルとキーストアファイルを生成し、それらを Amazon S3 バケットにアップロードして、コネクタをデプロイするときに Amazon S3 への参照を提供する必要があります。キーストア、トラストストア、および SSL キーは AWS Secrets Manager に保存されます。コネクタをデプロイする際に、クライアントは AWS のシークレットキーを提供する必要があります。詳細については、Apache Kafka ドキュメントの「[SSL を使用した暗号化と認証](https://kafka.apache.org/documentation/#security_ssl)」を参照してください。
詳細については、「[Athena Kafka コネクタの認証を設定](#connectors-kafka-setup-configuring-authentication)」を参照してください。
+ **certificates\$1s3\$1reference** - 証明書 (キーストアとトラストストアのファイル) を含む Amazon S3 の場所。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **kafka\$1endpoint** - Kafka に提供するエンドポイントの詳細。
+ **schema\$1registry\$1url** – スキーマレジストリの URL アドレス (例: `http://schema-registry.example.org:8081`)。`AVRO` および `PROTOBUF` データ形式に適用されます。Athena は Confluent スキーマレジストリのみをサポートしています。
+ **secrets\$1manager\$1secret** - 認証情報が保存されている AWS シークレットの名前。
+ **スピルパラメータ** - Lambda 関数は、メモリに収まらないデータを Amazon S3 に一時的に保存 (「スピル」) します。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。次の表のパラメータを使用して、スピル場所を指定します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html)
+ **サブネット ID** — Lambda 関数がデータソースへのアクセスに使用できるサブネットに対応する 1 つ以上のサブネット ID。
+ **パブリックな Kafka クラスターまたは標準の Confluent Cloud クラスタ** — コネクターを NAT ゲートウェイのあるプライベートサブネットに関連付けます。
+ **プライベート接続の Confluent Cloud クラスタ** — Confluent Cloud クラスタへのルートがあるプライベートサブネットにコネクタを関連付けます。
+ [AWS Transit Gateway](https://docs.confluent.io/cloud/current/networking/aws-transit-gateway.html) の場合、サブネットは Confluent Cloud が使用するのと同じトランジットゲートウェイに接続されている VPC 内にある必要があります。
+ [VPC ピアリングの場合](https://docs.confluent.io/cloud/current/networking/peering/aws-peering.html)、サブネットは Confluent Cloud VPC にピアリングされている VPC 内にある必要があります。
+ [AWS PrivateLink](https://docs.confluent.io/cloud/current/networking/private-links/aws-privatelink.html)の場合、サブネットは Confluent Cloud に接続する VPC エンドポイントへのルートがある VPC 内にある必要があります。
**注記**
プライベートリソースにアクセスするためにコネクタを VPC にデプロイし、Confluent などのパブリックにアクセス可能なサービスにも接続する場合は、NAT ゲートウェイを持つプライベートサブネットにコネクタを関連付ける必要があります。詳細については、Amazon VPC ユーザーガイドの「[NAT ゲートウェイ](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)」を参照してください。
## サポートされるデータ型
次の表に、Kafka と Apache Arrow に対応するデータ型を示します。
****
| Kafka | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| TIMESTAMP | ミリ秒 |
| DATE | DAY |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | FLOAT8 |
| DOUBLE | FLOAT8 |
## パーティションと分割
Kafka トピックはパーティションに分割されています。各パーティションは順序付けられています。パーティション内の各メッセージには、*オフセット*と呼ばれるインクリメンタル ID があります。各 Kafka パーティションは、並列処理のためにさらに複数のスプリットに分割されます。データは、Kafka クラスターに設定された保持期間中、利用できます。
## ベストプラクティス
ベストプラクティスとして、次の例のように、Athena にクエリを実行するときは、述語プッシュダウンを使用してください。
```
SELECT *
FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE integercol = 2147483647
```
```
SELECT *
FROM "kafka_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## Kafka コネクタのセットアップ
コネクタを使用する前に、Apache Kafka クラスターをセットアップし、[AWS Glue スキーマレジストリ](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)を使用してスキーマを定義し、コネクタの認証を設定する必要があります。
AWS Glue スキーマレジストリを使用する際は、次の点に注意してください。
+ AWS Glue スキーマレジストリの **[Description]** (説明) フィールドのテキストに文字列 `{AthenaFederationKafka}` が含まれていることを確認してください。このマーカー文字列は、Amazon Athena Kafka コネクタで使用する AWS Glue レジストリに必要です。
+ 最高のパフォーマンスを得るには、 データベース名とテーブル名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。
**Apache Kafka 環境と AWS Glue スキーマレジストリをセットアップするには**
1. Apache Kafka 環境をセットアップします。
1. JSON 形式の Kafka トピック記述ファイル (つまり、そのスキーマ) を AWS Glue スキーマレジストリにアップロードします。詳細については、「AWS Glue デベロッパーガイド」の「[AWS Glue スキーマ登録と連携する](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)」を参照してください。
1. AWS Glue スキーマレジストリでスキーマを定義する際に `AVRO` または `PROTOBUF` データ形式を使用するには:
+ **[スキーマ名]** で、元と同じように大文字および小文字を使用して Kafka トピック名を入力します。
+ **[データ形式]** で、**[Apache Avro]** または **[プロトコルバッファ]** を選択します。
スキーマの例については、次のセクションを参照してください。
### AWS Glue スキーマレジストリのスキーマの例
スキーマを [AWS Glue スキーマレジストリ](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)にアップロードする際は、このセクションの例の形式を使用してください。
#### JSON タイプのスキーマの例
次の例では、AWS Glue スキーマレジストリに作成されるスキーマは、`dataFormat` の値として `json` を指定し、`topicName` の値として `datatypejson` を使用します。
**注記**
`topicName` の値は、Kafka のトピック名と同じ大文字と小文字を使用する必要があります。
```
{
"topicName": "datatypejson",
"message": {
"dataFormat": "json",
"fields": [
{
"name": "intcol",
"mapping": "intcol",
"type": "INTEGER"
},
{
"name": "varcharcol",
"mapping": "varcharcol",
"type": "VARCHAR"
},
{
"name": "booleancol",
"mapping": "booleancol",
"type": "BOOLEAN"
},
{
"name": "bigintcol",
"mapping": "bigintcol",
"type": "BIGINT"
},
{
"name": "doublecol",
"mapping": "doublecol",
"type": "DOUBLE"
},
{
"name": "smallintcol",
"mapping": "smallintcol",
"type": "SMALLINT"
},
{
"name": "tinyintcol",
"mapping": "tinyintcol",
"type": "TINYINT"
},
{
"name": "datecol",
"mapping": "datecol",
"type": "DATE",
"formatHint": "yyyy-MM-dd"
},
{
"name": "timestampcol",
"mapping": "timestampcol",
"type": "TIMESTAMP",
"formatHint": "yyyy-MM-dd HH:mm:ss.SSS"
}
]
}
}
```
#### CSV タイプスキーマの例
次の例では、AWS Glue スキーマレジストリに作成されるスキーマは、`dataFormat` の値として `csv` を指定し、`topicName` の値として `datatypecsvbulk` を使用します。`topicName` の値は、Kafka のトピック名と同じ大文字と小文字を使用する必要があります。
```
{
"topicName": "datatypecsvbulk",
"message": {
"dataFormat": "csv",
"fields": [
{
"name": "intcol",
"type": "INTEGER",
"mapping": "0"
},
{
"name": "varcharcol",
"type": "VARCHAR",
"mapping": "1"
},
{
"name": "booleancol",
"type": "BOOLEAN",
"mapping": "2"
},
{
"name": "bigintcol",
"type": "BIGINT",
"mapping": "3"
},
{
"name": "doublecol",
"type": "DOUBLE",
"mapping": "4"
},
{
"name": "smallintcol",
"type": "SMALLINT",
"mapping": "5"
},
{
"name": "tinyintcol",
"type": "TINYINT",
"mapping": "6"
},
{
"name": "floatcol",
"type": "DOUBLE",
"mapping": "7"
}
]
}
}
```
#### AVRO 型スキーマの例
次の例は、AWS Glue スキーマレジストリで AVRO ベースのスキーマを作成するために使用されます。AWS Glue スキーマレジストリでスキーマを定義する場合、**[スキーマ名]** で元と同じように大文字および小文字を使用して Kafka トピック名を入力し、**[データ形式]** で **[Apache Avro]** を選択します。この情報はレジストリで直接指定するため、`dataformat` および `topicName` フィールドは必要ありません。
```
{
"type": "record",
"name": "avrotest",
"namespace": "example.com",
"fields": [{
"name": "id",
"type": "int"
},
{
"name": "name",
"type": "string"
}
]
}
```
#### PROTOBUF タイプのスキーマの例
次の例は、AWS Glue スキーマレジストリで PROTOBUF ベースのスキーマを作成するために使用されます。AWS Glue スキーマレジストリでスキーマを定義する場合、**[スキーマ名]** で元と同じように大文字および小文字を使用して Kafka トピック名を入力し、**[データ形式]** で **[Protocol Buffers]** を選択します。この情報はレジストリで直接指定するため、`dataformat` および `topicName` フィールドは必要ありません。1 行目はスキーマを PROTOBUF として定義します。
```
syntax = "proto3";
message protobuftest {
string name = 1;
int64 calories = 2;
string colour = 3;
}
```
AWS Glue スキーマレジストリにレジストリとスキーマを追加する方法の詳細については、AWS Glue ドキュメントの「[スキーマレジストリの開始方法](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-gs.html)」を参照してください。
### Athena Kafka コネクタの認証を設定
SSL、SASL/SCRAM、SASL/PLAIN、SASL/PLAINTEXT など、Apache Kafka クラスターへの認証にはさまざまなメソッドを使用できます。
次の表は、コネクタの認証タイプと、それぞれのセキュリティプロトコルおよび SASL メカニズムを示しています。詳細については、Apache Kafka ドキュメントの「[セキュリティ](https://kafka.apache.org/documentation/#security)」セクションを参照してください。
****
| auth\$1type | security.protocol | sasl.mechanism | クラスタータイプの互換性 |
| --- | --- | --- | --- |
| SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html) |
| SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html) |
| SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html) |
| SASL\$1PLAINTEXT\$1SCRAM\$1SHA512 | SASL\$1PLAINTEXT | SCRAM-SHA-512 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html) |
| SSL | SSL | 該当なし | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-kafka.html) |
#### SSL
クラスターが SSL 認証されている場合、トラストストアとキーストアファイルを生成して Amazon S3 バケットにアップロードする必要があります。コネクタをデプロイする際に、この Amazon S3 リファレンスを提供する必要があります。キーストア、トラストストア、および SSL キーは AWS Secrets Manager に保存されます。コネクタをデプロイする際に、AWS のシークレットキーを提供します。
Secrets Manager でのシークレットの作成については、「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。
この認証タイプを使用するには、次の表の説明どおりに環境変数を設定します。
****
| パラメータ | 値 |
| --- | --- |
| auth\$1type | SSL |
| certificates\$1s3\$1reference | 証明書を格納する Amazon S3 の場所。 |
| secrets\$1manager\$1secret | AWS シークレットキーの名前。 |
Secrets Manager でシークレットを作成した後、Secrets Manager コンソールでそのシークレットを確認できます。
**Secrets Manager で自分のシークレットを確認するには**
1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/) から Secrets Manager コンソールを開きます。
1. ナビゲーションペインで **[Secrets]** (シークレット) を選択します。
1. **[Secrets]** (シークレット) ページで、自分のシークレットを選択します。
1. 自分のシークレットの詳細ページで、**[Retrieve secret value]** (シークレットの値を取得する) を選択します。
次の画像は、3 組のキー/値のペア (`keystore_password`、`truststore_password`、`ssl_key_password`) を持つシークレットの例を示しています。
![\[Secrets Manager で SSL シークレットを取得する\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-kafka-setup-1.png)
Kafka で SSL を使用する際の詳細については、Apache Kafka ドキュメントの「[SSL を使用した暗号化と認証](https://kafka.apache.org/documentation/#security_ssl)」を参照してください。
#### SASL/SCRAM
クラスターが SCRAM 認証を使用している場合は、コネクタをデプロイするときに、クラスターに関連付けられている Secrets Manager キーを指定します。ユーザーの AWS 認証情報 (シークレットキーとアクセスキー) は、クラスターとの認証に使用されます。
次の表のように環境変数を設定します。
****
| パラメータ | 値 |
| --- | --- |
| auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 |
| secrets\$1manager\$1secret | AWS シークレットキーの名前。 |
次の画像は、Secrets Manager コンソールにある 2 つのキー/値のペア (1 つは `username` 用、もう 1 つは `password` 用) のシークレットの例を示しています。
![\[Secrets Manager での SCRAM シークレットの取得\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-kafka-setup-2.png)
Kafka で SASL/SCRAM を使用する際の詳細については、Apache Kafka ドキュメントの「[SASL/SCRAM 認証の使用](https://kafka.apache.org/documentation/#security_sasl_scram)」を参照してください。
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-kafka/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-kafka)を参照してください。
# Amazon Athena MSK コネクタ
[Amazon MSK](https://aws.amazon.com/msk/) 用の Amazon Athena コネクタを使用すると、Amazon Athena で Apache Kafka トピックに対する SQL クエリを実行できるようになります。このコネクタを使用すると、[Apache Kafka](https://kafka.apache.org/) トピックをテーブルとして、メッセージを Athena の行として表示できます。追加情報については、「AWS ビッグデータブログ」の「[Amazon Athena を使用して Amazon MSK でリアルタイムストリーミングデータを分析する](https://aws.amazon.com/blogs/big-data/analyze-real-time-streaming-data-in-amazon-msk-with-amazon-athena/)」を参照してください。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件における日付とタイムスタンプのデータ型は、適切なデータ型にキャストする必要があります。
+ 日付とタイムスタンプのデータ型は、CSV ファイルタイプではサポートされていないため、varchar 値として扱われます。
+ ネストされた JSON フィールドへのマッピングはサポートされていません。コネクタは最上位のフィールドのみをマッピングします。
+ コネクタは複合型をサポートしていません。複合型は文字列として解釈されます。
+ 複合型の JSON 値を抽出または処理するには、Athena に用意されている JSON 関連の関数を使用してください。詳細については、「[文字列から JSON データを抽出する](extracting-data-from-JSON.md)」を参照してください。
+ コネクタは、Kafka メッセージメタデータへのアクセスをサポートしていません。
## 用語
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **Kafka エンドポイント** - Kafka インスタンスへの接続を確立するテキスト文字列。
## クラスター間の互換性
MSK コネクタは、次のクラスタータイプで使用できます。
+ **MSK プロビジョニングクラスター** - クラスター容量を手動で指定、監視、スケーリングします。
+ **MSK Serverless クラスター** - アプリケーション I/O のスケーリングに合わせて自動的にスケーリングされるオンデマンドの容量を提供します。
+ **スタンドアロン Kafka** - Kafka への直接の接続 (認証または非認証)。
## サポートされた認証方法
コネクタでは、次の認証方法がサポートされています。
+ [SASL/IAM](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)
+ [SSL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)
+ [SASL/SCRAM](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html)
+ SASL/PLAIN
+ SASL/PLAINTEXT
+ NO\$1AUTH
詳細については、「[Athena MSK コネクタの認証の設定](#connectors-msk-setup-configuring-authentication)」を参照してください。
## 対応する入力データ形式
コネクタは、次の入力データ形式をサポートします。
+ JSON
+ CSV
## パラメータ
このセクションのパラメータを使用して Athena MSK コネクタを設定します。
+ **auth\$1type** - クラスターの認証タイプを指定します。コネクタは、次のタイプの認証をサポートしています。
+ **NO\$1AUTH** - 認証なしで Kafka に直接接続します (例えば、認証を使用しない EC2 インスタンスにデプロイされた Kafka クラスターなど)。
+ **SASL\$1SSL\$1PLAIN** - このメソッドは、`SASL_SSL` セキュリティプロトコルと `PLAIN` SASL メカニズムを使用します。
+ **SASL\$1PLAINTEXT\$1PLAIN** - このメソッドは、`SASL_PLAINTEXT` セキュリティプロトコルと `PLAIN` SASL メカニズムを使用します。
**注記**
`SASL_SSL_PLAIN` および `SASL_PLAINTEXT_PLAIN` 認証タイプは、Apache Kafka ではサポートされていますが、Amazon MSK ではサポートされていません。
+ **SASL\$1SSL\$1AWS\$1MSK\$1IAM** - Amazon MSK の IAM アクセス制御により、MSK クラスターの認証と承認の両方を処理できます。ユーザーの AWS 認証情報 (シークレットキーとアクセスキー) は、クラスターへの接続に使用されます。詳細については、Amazon Managed Streaming for Apache Kafka デベロッパーガイドの「[IAM access control](https://docs.aws.amazon.com/msk/latest/developerguide/iam-access-control.html)」(IAM アクセスコントロール) を参照してください。
+ **SASL\$1SSL\$1SCRAM\$1SHA512** - この認証タイプを使用して Amazon MSK クラスターへのアクセスを制御できます。このメソッドでは、ユーザー名とパスワードを AWS Secrets Manager に保存します。シークレットは Amazon MSK クラスターに関連付けられている必要があります。詳細については、Amazon Managed Streaming for Apache Kafka デベロッパーガイドの「[Amazon MSK クラスターの SASL/SCRAM 認証のセットアップ](https://docs.aws.amazon.com/msk/latest/developerguide/msk-password.html#msk-password-tutorial)」を参照してください。
+ **SSL** - SSL 認証では、キーストアとトラストストアのファイルを使用して Amazon MSK クラスターに接続します。トラストストアファイルとキーストアファイルを生成し、それらを Amazon S3 バケットにアップロードして、コネクタをデプロイするときに Amazon S3 への参照を提供する必要があります。キーストア、トラストストア、および SSL キーは AWS Secrets Manager に保存されます。コネクタをデプロイする際に、クライアントは AWS のシークレットキーを提供する必要があります。詳細については、Amazon Managed Streaming for Apache Kafka デベロッパーガイドの「[相互 TLS 認証](https://docs.aws.amazon.com/msk/latest/developerguide/msk-authentication.html)」を参照してください。
詳細については、「[Athena MSK コネクタの認証の設定](#connectors-msk-setup-configuring-authentication)」を参照してください。
+ **certificates\$1s3\$1reference** - 証明書 (キーストアとトラストストアのファイル) を含む Amazon S3 の場所。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **kafka\$1endpoint** - Kafka に提供するエンドポイントの詳細。例えば、Amazon MSK クラスターの場合、クラスターの[ブートストラップ URL](https://docs.aws.amazon.com/msk/latest/developerguide/msk-get-bootstrap-brokers.html) を指定します。
+ **secrets\$1manager\$1secret** - 認証情報が保存されている AWS シークレットの名前。このパラメータは IAM 認証には必要ありません。
+ **スピルパラメータ** - Lambda 関数は、メモリに収まらないデータを Amazon S3 に一時的に保存 (「スピル」) します。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。次の表のパラメータを使用して、スピル場所を指定します。
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/connectors-msk.html)
## サポートされるデータ型
次の表に、Kafka と Apache Arrow に対応するデータ型を示します。
****
| Kafka | Arrow |
| --- | --- |
| CHAR | VARCHAR |
| VARCHAR | VARCHAR |
| TIMESTAMP | ミリ秒 |
| DATE | DAY |
| BOOLEAN | BOOL |
| SMALLINT | SMALLINT |
| INTEGER | INT |
| BIGINT | BIGINT |
| DECIMAL | FLOAT8 |
| DOUBLE | FLOAT8 |
## パーティションと分割
Kafka トピックはパーティションに分割されています。各パーティションは順序付けられています。パーティション内の各メッセージには、*オフセット*と呼ばれるインクリメンタル ID があります。各 Kafka パーティションは、並列処理のためにさらに複数のスプリットに分割されます。データは、Kafka クラスターに設定された保持期間中、利用できます。
## ベストプラクティス
ベストプラクティスとして、次の例のように、Athena にクエリを実行するときは、述語プッシュダウンを使用してください。
```
SELECT *
FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE integercol = 2147483647
```
```
SELECT *
FROM "msk_catalog_name"."glue_schema_registry_name"."glue_schema_name"
WHERE timestampcol >= TIMESTAMP '2018-03-25 07:30:58.878'
```
## MSK コネクタのセットアップ
コネクタを使用する前に、Amazon MSK クラスターをセットアップし、[AWS Glue スキーマレジストリ](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)を使用してスキーマを定義し、コネクタの認証を設定する必要があります。
**注記**
プライベートリソースにアクセスするためにコネクタを VPC にデプロイし、Confluent などのパブリックにアクセス可能なサービスにも接続する場合は、NAT ゲートウェイを持つプライベートサブネットにコネクタを関連付ける必要があります。詳細については、Amazon VPC ユーザーガイドの「[NAT ゲートウェイ](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-nat-gateway.html)」を参照してください。
AWS Glue スキーマレジストリを使用する際は、次の点に注意してください。
+ AWS Glue スキーマレジストリの **[Description]** (説明) フィールドのテキストに文字列 `{AthenaFederationMSK}` が含まれていることを確認してください。このマーカー文字列は、Amazon Athena MSK コネクタで使用する AWS Glue レジストリに必要です。
+ 最高のパフォーマンスを得るには、 データベース名とテーブル名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。
**Amazon MSK 環境と AWS Glue スキーマレジストリをセットアップするには**
1. Amazon MSK 環境をセットアップします。詳細と手順については、Amazon Managed Streaming for Apache Kafka デベロッパーガイドの「[Amazon MSK のセットアップ](https://docs.aws.amazon.com/msk/latest/developerguide/before-you-begin.html)」および「[Amazon MSK を使い始める](https://docs.aws.amazon.com/msk/latest/developerguide/getting-started.html)」を参照してください。
1. JSON 形式の Kafka トピック記述ファイル (つまり、そのスキーマ) を AWS Glue スキーマレジストリにアップロードします。詳細については、AWS Glue デベロッパーガイドの「[AWS Glue スキーマ登録と連携する](https://docs.aws.amazon.com/glue/latest/dg/schema-registry-integrations.html)」を参照してください。スキーマの例については、次のセクションを参照してください。
### AWS Glue スキーマレジストリのスキーマの例
スキーマを [AWS Glue スキーマレジストリ](https://docs.aws.amazon.com/glue/latest/dg/schema-registry.html)にアップロードする際は、このセクションの例の形式を使用してください。
#### JSON タイプのスキーマの例
次の例では、AWS Glue スキーマレジストリに作成されるスキーマは、`dataFormat` の値として `json` を指定し、`topicName` の値として `datatypejson` を使用します。
**注記**
`topicName` の値は、Kafka のトピック名と同じ大文字と小文字を使用する必要があります。
```
{
"topicName": "datatypejson",
"message": {
"dataFormat": "json",
"fields": [
{
"name": "intcol",
"mapping": "intcol",
"type": "INTEGER"
},
{
"name": "varcharcol",
"mapping": "varcharcol",
"type": "VARCHAR"
},
{
"name": "booleancol",
"mapping": "booleancol",
"type": "BOOLEAN"
},
{
"name": "bigintcol",
"mapping": "bigintcol",
"type": "BIGINT"
},
{
"name": "doublecol",
"mapping": "doublecol",
"type": "DOUBLE"
},
{
"name": "smallintcol",
"mapping": "smallintcol",
"type": "SMALLINT"
},
{
"name": "tinyintcol",
"mapping": "tinyintcol",
"type": "TINYINT"
},
{
"name": "datecol",
"mapping": "datecol",
"type": "DATE",
"formatHint": "yyyy-MM-dd"
},
{
"name": "timestampcol",
"mapping": "timestampcol",
"type": "TIMESTAMP",
"formatHint": "yyyy-MM-dd HH:mm:ss.SSS"
}
]
}
}
```
#### CSV タイプスキーマの例
次の例では、AWS Glue スキーマレジストリに作成されるスキーマは、`dataFormat` の値として `csv` を指定し、`topicName` の値として `datatypecsvbulk` を使用します。`topicName` の値は、Kafka のトピック名と同じ大文字と小文字を使用する必要があります。
```
{
"topicName": "datatypecsvbulk",
"message": {
"dataFormat": "csv",
"fields": [
{
"name": "intcol",
"type": "INTEGER",
"mapping": "0"
},
{
"name": "varcharcol",
"type": "VARCHAR",
"mapping": "1"
},
{
"name": "booleancol",
"type": "BOOLEAN",
"mapping": "2"
},
{
"name": "bigintcol",
"type": "BIGINT",
"mapping": "3"
},
{
"name": "doublecol",
"type": "DOUBLE",
"mapping": "4"
},
{
"name": "smallintcol",
"type": "SMALLINT",
"mapping": "5"
},
{
"name": "tinyintcol",
"type": "TINYINT",
"mapping": "6"
},
{
"name": "floatcol",
"type": "DOUBLE",
"mapping": "7"
}
]
}
}
```
### Athena MSK コネクタの認証の設定
Amazon MSK クラスターへの認証には、IAM、SSL、SCRAM、スタンドアロン Kafka など、さまざまな方法を使用できます。
次の表は、コネクタの認証タイプと、それぞれのセキュリティプロトコルおよび SASL メカニズムを示しています。詳細については、「Amazon Managed Streaming for Apache Kafka Developer Guide」の「[Authentication and authorization for Apache Kafka APIs](https://docs.aws.amazon.com/msk/latest/developerguide/kafka_apis_iam.html)」を参照してください。
****
| auth\$1type | security.protocol | sasl.mechanism |
| --- | --- | --- |
| SASL\$1SSL\$1PLAIN | SASL\$1SSL | PLAIN |
| SASL\$1PLAINTEXT\$1PLAIN | SASL\$1PLAINTEXT | PLAIN |
| SASL\$1SSL\$1AWS\$1MSK\$1IAM | SASL\$1SSL | AWS\$1MSK\$1IAM |
| SASL\$1SSL\$1SCRAM\$1SHA512 | SASL\$1SSL | SCRAM-SHA-512 |
| SSL | SSL | 該当なし |
**注記**
`SASL_SSL_PLAIN` および `SASL_PLAINTEXT_PLAIN` 認証タイプは、Apache Kafka ではサポートされていますが、Amazon MSK ではサポートされていません。
#### SASL/IAM
クラスターが IAM 認証を使用する場合、クラスターをセットアップする際にユーザーの IAM ポリシーを設定する必要があります。詳細については、Amazon Managed Streaming for Apache Kafka デベロッパーガイドの「[IAM access control](https://docs.aws.amazon.com/msk/latest/developerguide/IAM-access-control.html)」(IAM アクセスコントロール) を参照してください。
この認証タイプを使用するには、コネクタの `auth_type` Lambda 環境変数を `SASL_SSL_AWS_MSK_IAM` に設定します。
#### SSL
クラスターが SSL 認証されている場合、トラストストアとキーストアファイルを生成して Amazon S3 バケットにアップロードする必要があります。コネクタをデプロイする際に、この Amazon S3 リファレンスを提供する必要があります。キーストア、トラストストア、および SSL キーは AWS Secrets Manager に保存されます。コネクタをデプロイする際に、AWS のシークレットキーを提供します。
Secrets Manager でのシークレットの作成については、「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。
この認証タイプを使用するには、以下の表の説明どおりに環境変数を設定します。
****
| パラメータ | 値 |
| --- | --- |
| auth\$1type | SSL |
| certificates\$1s3\$1reference | 証明書を格納する Amazon S3 の場所。 |
| secrets\$1manager\$1secret | AWS シークレットキーの名前。 |
Secrets Manager でシークレットを作成した後、Secrets Manager コンソールでそのシークレットを確認できます。
**Secrets Manager で自分のシークレットを確認するには**
1. [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/) から Secrets Manager コンソールを開きます。
1. ナビゲーションペインで **[Secrets]** (シークレット) を選択します。
1. **[Secrets]** (シークレット) ページで、自分のシークレットを選択します。
1. 自分のシークレットの詳細ページで、**[Retrieve secret value]** (シークレットの値を取得する) を選択します。
次の画像は、3 組のキー/値のペア (`keystore_password`、`truststore_password`、`ssl_key_password`) を持つシークレットの例を示しています。
![\[Secrets Manager で SSL シークレットを取得する\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-msk-setup-1.png)
#### SASL/SCRAM
クラスターが SCRAM 認証を使用している場合は、コネクタをデプロイするときに、クラスターに関連付けられている Secrets Manager キーを指定します。ユーザーの AWS 認証情報 (シークレットキーとアクセスキー) は、クラスターとの認証に使用されます。
下表のように環境変数を設定します。
****
| パラメータ | 値 |
| --- | --- |
| auth\$1type | SASL\$1SSL\$1SCRAM\$1SHA512 |
| secrets\$1manager\$1secret | AWS シークレットキーの名前。 |
次の画像は、Secrets Manager コンソールにある 2 つのキー/値のペア (1 つは `username` 用、もう 1 つは `password` 用) のシークレットの例を示しています。
![\[Secrets Manager での SCRAM シークレットの取得\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-msk-setup-2.png)
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-msk/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-msk)を参照してください。
# Amazon Athena MySQL コネクタ
Amazon Athena Lambda MySQL コネクタは、Amazon Athena での MySQL のデータベースへのアクセスを可能にします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ Athena はクエリを小文字に変換するため、MySQL テーブル名は小文字である必要があります。たとえば、`myTable` という名前のテーブルに対する Athena のクエリは失敗します。
+ MySQL 接続を Glue Catalog と Lake Formation に移行すると、小文字のテーブル名と列名のみが認識されます。
## 用語
MySQL コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して MySQL コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して MySQL コネクタを設定することをお勧めします。
そのためには、MySQL コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type MYSQL
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された MySQL コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された MySQL コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
mysql://${jdbc_connection_string}
```
**注記**
MySQL テーブルに対して `SELECT` クエリを実行したときに「java.sql.SQLException: Zero date value prohibited」(java.sql.SQLException: ゼロの日付値は禁止されています) というエラーが発生したら、接続文字列に次のパラメータを追加します。
```
zeroDateTimeBehavior=convertToNull
```
詳細については、GitHub.com で「[Error 'Zero date value prohibited' while trying to select from MySQL table](https://github.com/awslabs/aws-athena-query-federation/issues/760)」(MySQL テーブルから選択しようとしたときの「ゼロ日付値は禁止されています」というエラー) を参照してください。
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | MySqlMuxCompositeHandler |
| メタデータハンドラー | MySqlMuxMetadataHandler |
| レコードハンドラー | MySqlMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mymysqlcatalog の場合、環境変数の名前は mymysqlcatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`mysql1` (デフォルト) と `mysql2` の 2 つのデータベースインスタンスをサポートする MySql MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 |
| mysql\$1catalog1\$1connection\$1string | mysql://jdbc:mysql://mysql1.host:3306/default?\$1\$1Test/RDS/MySql1\$1 |
| mysql\$1catalog2\$1connection\$1string | mysql://jdbc:mysql://mysql2.host:3333/default?user=sample2&password=sample2 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/MySql1}` が含まれています。
```
mysql://jdbc:mysql://mysql1.host:3306/default?...&${Test/RDS/MySql1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
mysql://jdbc:mysql://mysql1host:3306/default?...&user=sample2&password=sample2&...
```
現在、MySQL コネクタは `user` と `password` の JDBC プロパティを認識します。
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の MySQL インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | MySqlCompositeHandler |
| メタデータハンドラー | MySqlMetadataHandler |
| レコードハンドラー | MySqlRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の MySQL インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | mysql://mysql1.host:3306/default?secret=Test/RDS/MySql1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Arrow に対応するデータ型を示します。
****
| JDBC | Arrow |
| --- | --- |
| ブール値 | Bit |
| 整数 | Tiny |
| ショート | Smallint |
| 整数 | Int |
| Long | Bigint |
| float | Float4 |
| ダブル | Float8 |
| 日付 | DateDay |
| タイムスタンプ | DateMilli |
| String | Varchar |
| バイト | Varbinary |
| BigDecimal | 10 進数 |
| 配列 | リスト |
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
MySQL はネイティブパーティションをサポートしています。Athena MySQL コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。
Athena MySQL コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena MySQL コネクタは、これらの式を組み合わせて MySQL に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena MySQL コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
MySQL などのフェデレーテッドクエリのパフォーマンスを向上させるために述語プッシュダウンを使用する方法の記事については、*AWS Big Data Blog* の「[Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)」を参照してください。
## パススルークエリ
MySQL コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
MySQL でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
次のクエリ例は、MySQL 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の MySQL コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-mysql/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-mysql)を参照してください。
# Amazon Athena Neptune コネクタ
Amazon Neptune は、高速で信頼性に優れたフルマネージド型のグラフデータベースサービスで、高度に接続されたデータセットを使用するアプリケーションの構築と実行を容易にします。Neptune の高性能専用グラフデータベースエンジンは、数十億のリレーションシップを最適に保存し、ミリ秒単位のレイテンシーでグラフをクエリします。詳細については、「[Neptune ユーザーガイド](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html)」を参照してください。
Amazon Athena Neptune コネクタは、Athena が Neptune グラフデータベースインスタンスとやり取りすることを可能にして、SQL クエリがNeptune グラフデータにアクセスできるようにします。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
## 前提条件
Neptune コネクタを使用するには、次の 3 つのステップが必要です。
+ Neptune クラスターのセットアップ
+ AWS Glue Data Catalog のセットアップ
+ AWS アカウント へのコネクタのデプロイ。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。Neptune コネクタのデプロイに関するその他の詳細については、GitHub.com で「[Deploy the Amazon Athena Neptune Connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-connector-setup)」(Amazon Athena Neptune コネクタのデプロイ) を参照してください。
## 制限事項
現在、Neptune コネクタには以下のような制限があります。
+ プライマリキー (ID) を含む列の射影はサポートされていません。
## Neptune クラスターのセットアップ
使用したい既存の Amazon Neptune クラスターとプロパティグラフデータセットがない場合は、セットアップする必要があります。
Neptune クラスターをホストする VPC にインターネットゲートウェイと NAT ゲートウェイがあることを確認してください。Neptune コネクタ Lambda 関数が使用するプライベートサブネットには、この NAT ゲートウェイを経由するインターネットへのルートが必要です。Neptune コネクタの Lambda 関数は NAT ゲートウェイを使用して AWS Glue と通信します。
新しい Neptune クラスターをセットアップしてサンプルデータセットとともにロードする手順については、GitHub.com で「[Sample Neptune Cluster Setup](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/neptune-cluster-setup)」(Neptune クラスターのセットアップ例) を参照してください。
## AWS Glue Data Catalog のセットアップ
従来のリレーショナルデータストアとは異なり、Neptune グラフ DB ノードとエッジは設定されたスキーマを使用しません。各エントリには、異なるフィールドとデータ型を設定できます。ただし、Neptune コネクタは AWS Glue Data Catalog からメタデータを取得するので、必要なスキーマのテーブルを含む AWS Glue データベースを作成する必要があります。AWS Glue データベースとテーブル作成したら、コネクタは Athena からのクエリに使用できるテーブルのリストに入力できます。
### 大文字と小文字を区別しない列の照合を有効にする
AWS Glue の列名がすべて小文字である場合でも、Neptune テーブルの列名を正しい大文字と小文字で解決するには、大文字と小文字を区別しない照合を行うように Neptune コネクタを構成できます。
この機能を有効にするには、Neptune コネクタの Lambda 関数で `enable_caseinsensitivematch` 環境変数を `true` に設定します。
### 大文字と小文字を区別するテーブル名に AWS Glue glabel テーブルパラメータを指定する
AWS Glue は小文字のテーブル名のみをサポートしているため、Neptune 用の AWS Glue テーブルを作成する際には、`glabel` AWS Glue テーブルパラメータを指定することが重要です。
AWS Glue テーブルの定義に `glabel` パラメータを含めて、その値を元の大文字と小文字を区別したテーブル名に設定します。これにより、AWS Glue が Neptune テーブルとやり取りするときに、大文字と小文字が正しく区別された状態が維持されます。次の例では、`glabel` の値をテーブル名 `Airport` に設定します。
```
glabel = Airport
```
![\[Neptune テーブルのテーブル名の大文字と小文字の区別が維持されるように glabel AWS Glue テーブルプロパティを正しく設定する\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-neptune-1.png)
Neptune とのやり取りを考慮して AWS Glue Data Catalog を設定するための詳細については、GitHub.com に掲載されている「[Set up AWS Glue Catalog](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune/docs/aws-glue-sample-scripts)」を参照してください。
## パフォーマンス
Athena Neptune コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。ただし、プライマリキーを使用する述語はクエリに失敗します。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語が提供されない場合は、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。Neptune コネクタは、同時実行によるスロットリングに強いです。
## パススルークエリ
Neptune コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。この機能を使用すると、プロパティグラフで Gremlin クエリを実行したり、RDF データに対して SPARQL クエリを実行したりできます。
Neptune でパススルークエリを作成するには、以下の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'database_name',
COLLECTION => 'collection_name',
QUERY => 'query_string'
))
```
次の Neptune パススルークエリの例では、コード `ATL` の空港がフィルタリングされています。二重引用符はエスケープ用です。
```
SELECT * FROM TABLE(
system.query(
DATABASE => 'graph-database',
COLLECTION => 'airport',
QUERY => 'g.V().has(''airport'', ''code'', ''ATL'').valueMap()'
))
```
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-neptune)を参照してください。
# Amazon Athena OpenSearch コネクタ
OpenSearch Service
Amazon Athena OpenSearch コネクタは、Amazon Athena でのOpenSearch インスタンスとの通信を可能にし、OpenSearch データを SQL でクエリできるようにします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
**注記**
既知の問題により、OpenSearch コネクタは VPC では使用できません。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 用語
OpenSearch コネクタに関連する用語を次に示します。
+ **ドメイン** – このコネクタが OpenSearch インスタンスのエンドポイントに関連付ける名前。ドメインはデータベース名としても使用されます。Amazon OpenSearch Service 内で定義されている OpenSearch インスタンスの場合、ドメインは自動検出可能です。他のインスタンスでは、ドメイン名とエンドポイント間のマッピングを指定する必要があります。
+ **インデックス** – OpenSearch インスタンスで定義されているデータベーステーブル。
+ **マッピング** – インデックスがデータベーステーブルの場合、マッピングはそのスキーマ (すなわち、フィールドと属性の定義) です。
このコネクタは、OpenSearch インスタンスからのメタデータ取得と AWS Glue Data Catalog からのメタデータ取得の両方をサポートします。OpenSearch ドメインとインデックス名に一致する AWS Glue データベースとテーブルをコネクタが検出した場合、コネクタはそれらをスキーマ定義に使用しようとします。AWS Glue テーブルは、OpenSearch インデックスのすべてのフィールドのスーパーセットになるように作成することをお勧めします。
+ **ドキュメント** – データベーステーブル内のレコード。
+ **データストリーム** — 複数のバッキングインデックスで構成される時間ベースのデータ。詳細については、OpenSearch ドキュメントの「[Data Streams](https://opensearch.org/docs/latest/dashboards/im-dashboards/datastream/)」および、「Amazon OpenSearch Service 開発者ガイド」の「[Data Streams の使用開始](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/data-streams.html#data-streams-example)」を参照してください。
**注記**
データストリームインデックスは OpenSearch によって内部で作成管理されるため、コネクタは最初の使用可能なインデックスからスキーママッピングを選択します。このため、補足メタデータのソースとして AWS Glue テーブルを設定することを強く推奨します。詳細については、「[AWS Glue でのデータベースとテーブルのセットアップ](#connectors-opensearch-setting-up-databases-and-tables-in-aws-glue)」を参照してください。
## パラメータ
このセクションのパラメータを使用して OpenSearch コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して OpenSearch コネクタを設定することをお勧めします。そのためには、OpenSearch コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type OPENSEARCH
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された OpenSearch コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された OpenSearch コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **query\$1timeout\$1cluster** – 並列スキャンの生成に使用されるクラスターヘルスクエリのタイムアウト時間 (秒単位)。
+ **query\$1timeout\$1search** – インデックスからのドキュメントの取得に使用される検索クエリのタイムアウト時間 (秒単位)。
+ **auto\$1discover\$1endpoint** – ブール値。デフォルトは `true` です。Amazon OpenSearch Service を使用する際に、このパラメータを true に設定すると、コネクタは OpenSearch Service で適切な describe API オペレーションまたは list API オペレーションを呼び出すことで、ドメインとエンドポイントを自動検出できます。その他のタイプの OpenSearch インスタンス (セルフホスト型など) では、関連するドメインエンドポイントを `domain_mapping` 変数に指定する必要があります。`auto_discover_endpoint=true` の場合、コネクタは AWS 認証情報を使用して OpenSearch Service に対する認証を行います。それ以外の場合、コネクタは `domain_mapping` 変数を通じて AWS Secrets Manager からユーザー名とパスワードの認証情報を取得します。
+ **domain\$1mapping** – `auto_discover_endpoint` が false に設定されている場合にのみ使用され、ドメイン名とそれに関連付けられているエンドポイントとのマッピングを定義します。`domain_mapping` 変数は、次の形式の複数の OpenSearch エンドポイントに対応できます。
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...
```
OpenSearch エンドポイントへの認証を目的として、コネクタは AWS Secrets Manager から取得したユーザー名とパスワードを含む `${SecretName}` の形式を使用して挿入された置換文字列をサポートします。シークレットは次の JSON 形式で保存する必要があります。
```
{ "username": "your_username", "password": "your_password" }
```
コネクタは、この JSON 構造を自動的に解析して認証情報を取得します。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
次の例では、`opensearch-creds` シークレットを使用しています。
```
movies=https://${opensearch-creds}:search-movies-ne...qu---us-east-1---es.amazonaws.com
```
実行時には、次の例のように、`${opensearch-creds}` はユーザー名とパスワードとして表示されます。
```
movies=https://myusername@mypassword:search-movies-ne...qu---us-east-1---es.amazonaws.com
```
`domain_mapping` パラメータでは、ドメインとエンドポイントのペアごとに異なるシークレットを使用できます。シークレット自体は*ユーザー名*@*パスワード*の形式で指定する必要があります。パスワードに `@` 記号が含まれている場合がありますが、最初の `@` が*ユーザー名*との区切りになります。
カンマ (,) と等号 (=) がこのコネクタによってドメインとエンドポイントのペアの区切り文字として使用されていることにも注意してください。そのため、これらの文字を保存されたシークレットの中で使用するべきではありません。
## AWS Glue でのデータベースとテーブルのセットアップ
コネクタは、AWS Glue または OpenSearch を使用してメタデータ情報を取得します。AWS Glue テーブルを補足メタデータ定義のソースとしてセットアップできます。この機能を有効にするには、補足するソースのドメインとインデックスに一致する AWS Glue データベースとテーブルを定義します。コネクタは、指定されたインデックスのマッピングを取得することで、OpenSearch インスタンスに保存されているメタデータ定義を利用することもできます。
### OpenSearch での配列のメタデータの定義
OpenSearch には専用の配列データ型はありません。データ型が同じであれば、どのフィールドにもゼロ以上の値を含められます。OpenSearch をメタデータ定義のソースとして使用する場合は、リストまたは配列と見なされるフィールドの Athena で使用されるすべてのインデックスの `_meta` プロパティを定義する必要があります。このステップを完了しなかった場合、クエリはリストフィールドの最初の要素のみを返します。`_meta` プロパティを指定すると、フィールド名はネストされた JSON 構造に対して完全修飾である必要があります (たとえば、`street` が `address` ストラクチャの内部にネストされたフィールドである場合、`address.street`)。
次の例では、`movies` テーブル内で `actor` リストと `genre` リストを定義しています。
```
PUT movies/_mapping
{
"_meta": {
"actor": "list",
"genre": "list"
}
}
```
### データ型
OpenSearch コネクタは、AWS Glue と OpenSearch インスタンスのどちらからでもメタデータの定義を抽出できます。コネクタは、次の表のマッピングを使用して定義を Apache Arrow データ型に変換します。これには、次のセクションで説明する点が含まれます。
****
| OpenSearch | Apache Arrow | AWS Glue |
| --- | --- | --- |
| text、keyword、binary | VARCHAR | string |
| long | BIGINT | bigint |
| scaled\$1float | BIGINT | SCALED\$1FLOAT(...) |
| integer | INT | int |
| short | SMALLINT | smallint |
| バイト | TINYINT | tinyint |
| double | FLOAT8 | double |
| float、half\$1float | FLOAT4 | float |
| boolean | BIT | boolean |
| date、date\$1nanos | DATEMILLI | timestamp |
| JSON の構造 | STRUCT | STRUCT |
| \$1meta (詳細については、「[OpenSearch での配列のメタデータの定義](#connectors-opensearch-defining-metadata-for-arrays-in-opensearch)」セクションを参照してください) | LIST | 配列 |
#### データ型に関する注意事項
+ 現在、コネクタは OpenSearch と前の表にリストされている AWS Glue データタイプのみをサポートしています。
+ `scaled_float` は、浮動小数点数を固定の double 型のスケーリング係数でスケーリングしたもので、Apache Arrow では `BIGINT` として表されます。たとえば、0.756 は、スケーリング係数が 100 の場合、四捨五入されて 76 になります。
+ AWS Glue で `scaled_float` を定義するには、列に `array` 型を選択し、SCALED\$1FLOAT(*スケーリング係数*) という形式を使用してフィールドを宣言する必要があります。
有効な例を次に示します。
```
SCALED_FLOAT(10.51)
SCALED_FLOAT(100)
SCALED_FLOAT(100.0)
```
有効でない例を次に示します。
```
SCALED_FLOAT(10.)
SCALED_FLOAT(.5)
```
+ `date_nanos` から `DATEMILLI` に変換する場合、ナノ秒は最も近いミリ秒に四捨五入されます。`date` と `date_nanos` の有効な例には、次の形式が含まれますが、これらに限定されません。
```
"2020-05-18T10:15:30.123456789"
"2020-05-15T06:50:01.123Z"
"2020-05-15T06:49:30.123-05:00"
1589525370001 (epoch milliseconds)
```
+ OpenSearch `binary` は、`Base64` を使用してエンコードされたバイナリ値の文字列表現で、`VARCHAR` に変換されます。
## SQL クエリの実行
このコネクタで使用できる DDL クエリの例を次に示します。これらの例では、*function\$1name* は Lambda 関数の名前に対応し、*domain* はクエリするドメインの名前で、*index* はインデックスの名前です。
```
SHOW DATABASES in `lambda:function_name`
```
```
SHOW TABLES in `lambda:function_name`.domain
```
```
DESCRIBE `lambda:function_name`.domain.index
```
## パフォーマンス
Athena OpenSearch コネクタは、シャードベースの並列スキャンをサポートしています。コネクタは、OpenSearch インスタンスから取得したクラスターヘルス情報を使用して、ドキュメント検索クエリに対する複数のリクエストを生成します。リクエストはシャードごとに分割され、同時に実行されます。
また、コネクタはドキュメント検索クエリの一部として述語をプッシュダウンします。次のクエリと述語の例は、コネクタがどのように述語プッシュダウンを使用するかを示しています。
**クエリ**
```
SELECT * FROM "lambda:elasticsearch".movies.movies
WHERE year >= 1955 AND year <= 1962 OR year = 1996
```
**述語**
```
(_exists_:year) AND year:([1955 TO 1962] OR 1996)
```
## パススルークエリ
OpenSearch コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートし、Query DSL 言語を使用します。Query DSL を使用したクエリの詳細については、Elasticsearch ドキュメントの「[Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html)」、または OpenSearch ドキュメントの「[Query DSL](https://opensearch.org/docs/latest/query-dsl/)」を参照してください。
OpenSearch コネクタでパススルークエリを使用するには、以下の構文を使用します。
```
SELECT * FROM TABLE(
system.query(
schema => 'schema_name',
index => 'index_name',
query => "{query_string}"
))
```
以下の OpenSearch パススルークエリ例は、`default` スキーマの `employee` インデックス内でアクティブ雇用ステータスを持つ従業員をフィルタリングします。
```
SELECT * FROM TABLE(
system.query(
schema => 'default',
index => 'employee',
query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}"
))
```
## その他のリソース
+ Amazon Athena OpenSearch コネクタを使用して、1 つのクエリで Amazon OpenSearch Service および Amazon S3 のデータをクエリする方法の記事については、*AWS Big Data Blog* の「[Query data in Amazon OpenSearch Service using SQL from Amazon Athena](https://aws.amazon.com/blogs/big-data/query-data-in-amazon-opensearch-service-using-sql-from-amazon-athena/)」を参照してください。
+ このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-elasticsearch)を参照してください。
# Amazon Athena Oracle コネクタ
Oracle 用の Amazon Athena コネクタを使用すると、Amazon Athena で オンプレミスや、Amazon EC2、Amazon RDS 上で稼働する Oracle に保存されたデータに SQL クエリを実行できます。このコネクタを使用して [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/) のデータにクエリを実行することもできます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ バージョン 12.1.0.2 の Oracle データベースのみがサポートされます。
+ Oracle コネクタが Glue 接続を使用しない場合、コネクタによってデータベース名、テーブル名、および列名が大文字に変換されます。
Oracle コネクタが Glue 接続を使用している場合、コネクタによってデータベース名、テーブル名、および列名がデフォルトで大文字になることはありません。この大文字と小文字の変換動作を変更するには、Lambda の環境変数 `casing_mode` を必要に応じて `upper` または `lower` に変更します。
Glue 接続を使用する Oracle コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
+ 精度とスケールを定義せずに Oracle `NUMBER` を使用すると、Athena はこれを `BIGINT` として扱います。必要な小数点以下の桁を Athena で取得するには、Lambda 環境変数で `default_scale=` を指定します。
## 用語
Oracle コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Oracle コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Oracle コネクタを設定することをお勧めします。そのためには、Oracle コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type ORACLE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **is\$1fips\$1enabled** – (オプション) FIPS モードが有効になっている場合は True に設定します。デフォルトは False です。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。これは、グルー接続が関連付けられていないコネクタのデフォルトです。
+ **case\$1insensitive\$1search** – Oracle のスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。クエリにコネクタのデフォルトの大文字と小文字に一致しないスキーマ名またはテーブル名が含まれている場合は、この値を使用します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Oracle コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Oracle コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **default** – Oracle データベースインスタンスへの接続に使用する JDBC 接続文字列。例: `oracle://${jdbc_connection_string}`
+ **catalog\$1connection\$1string** – マルチプレックスハンドラーによって使用されます (Glue 接続を使用する場合はサポートされていません)。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myoraclecatalog の場合、環境変数の名前は myoraclecatalog\$1connection\$1string になります。
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **is\$1fips\$1enabled** – (オプション) FIPS モードが有効になっている場合は True に設定します。デフォルトは False です。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。これは、グルー接続が関連付けられていないコネクタのデフォルトです。
+ **case\$1insensitive\$1search** – Oracle のスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。クエリにコネクタのデフォルトの大文字と小文字に一致しないスキーマ名またはテーブル名が含まれている場合は、この値を使用します。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
oracle://${jdbc_connection_string}
```
**注記**
パスワードに特殊文字が含まれている場合は (例: `some.password`)、パスワードを接続文字列に渡すときにそのパスワードを二重引用符で囲みます (例: `"some.password"`)。これを実行しない場合、「無効な Oracle URL が指定されました」というエラーが発生する可能性があります。
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Oracle インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | OracleCompositeHandler |
| メタデータハンドラー | OracleMetadataHandler |
| レコードハンドラー | OracleRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
| IsFIPSEnabled | オプション。FIPS モードが有効になっている場合は、true に設定します。デフォルトは false です。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
コネクタは Amazon RDS インスタンスへの SSL ベースの接続をサポートします。このサポートは、Transport Layer Security (TLS) プロトコルと、クライアントによるサーバーの認証に限定されています。相互認証は Amazon RDS ではサポートされていません。下の表の 2 行目は、SSL を使用するための構文を示しています。
Lambda 関数でサポートされる単一の Oracle インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@//hostname:port/servicename |
| | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle\$1@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\$1DATA=(SID=))(SECURITY=(SSL\$1SERVER\$1CERT\$1DN=))) |
#### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**注記**
パスワードに特殊文字が含まれている場合は (例: `some.password`)、Secrets Manager にパスワードを保存するときにそのパスワードを二重引用符で囲みます (例: `"some.password"`)。これを実行しない場合、「無効な Oracle URL が指定されました」というエラーが発生する可能性があります。
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/Oracle}` が含まれています。
```
oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename
```
現在、Oracle コネクタは `UID` と `PWD` の JDBC プロパティを認識します。
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | OracleMuxCompositeHandler |
| メタデータハンドラー | OracleMuxMetadataHandler |
| レコードハンドラー | OracleMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myoraclecatalog の場合、環境変数の名前は myoraclecatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`oracle1` (デフォルト) と `oracle2` の 2 つのデータベースインスタンスをサポートする Oracle MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename |
| oracle\$1catalog1\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle1\$1@//oracle1.hostname:port/servicename |
| oracle\$1catalog2\$1connection\$1string | oracle://jdbc:oracle:thin:\$1\$1Test/RDS/Oracle2\$1@//oracle2.hostname:port/servicename |
## サポートされるデータ型
次の表に、JDBC、Oracle、Arrow に対応するデータ型を示します。
****
| JDBC | Oracle | Arrow |
| --- | --- | --- |
| ブール値 | boolean | Bit |
| 整数 | 該当なし | Tiny |
| ショート | smallint | Smallint |
| 整数 | integer | Int |
| Long | bigint | Bigint |
| float | float4 | Float4 |
| ダブル | float8 | Float8 |
| 日付 | date | DateDay |
| タイムスタンプ | timestamp | DateMilli |
| String | text | Varchar |
| バイト | bytes | Varbinary |
| BigDecimal | numeric(p,s) | 10 進数 |
| 配列 | 該当なし (注記を参照) | リスト |
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
Oracle はネイティブパーティションをサポートしています。Athena Oracle コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。Oracle コネクタは、同時実行によるスロットリングに強いです。ただし、クエリランタイムは長くなる傾向があります。
Athena Oracle コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。単純な述語と複雑な式はコネクタにプッシュダウンされるため、スキャンされるデータ量が減少し、クエリ実行のランタイムが短縮されます。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Oracle コネクタは、これらの式を組み合わせて Oracle に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Oracle コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## パススルークエリ
Oracle コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Oracle でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Oracle 内のデータソースにクエリをプッシュダウンします。クエリは、`customer` テーブル内のすべての列を選択します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Oracle コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle)を参照してください。
# Amazon Athena PostgreSQL コネクタ
Amazon Athena PostgreSQL コネクタは、Athena での PostgreSQL データベースへのアクセスを可能にします。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ PostgreSQL と同様に、Athena は PostgreSQL `CHAR` タイプの末尾のスペースを、長さや比較の目的で意味的に重要ではないものとして扱います。これは `CHAR` にのみ適用され、`VARCHAR` タイプには適用されないことに留意してください。Athena は、`CHAR` タイプの末尾のスペースを無視しますが、`VARCHAR` タイプでは重要なものとして扱います。
+ 大文字と小文字を区別しない [citext](https://www.postgresql.org/docs/current/citext.html) 文字列データ型を使用すると、PostgreSQL は大文字と小文字を区別しないデータ比較を使用します。これは Athena とは異なります。この違いにより、SQL `JOIN` オペレーション中にデータの不一致が発生します。この問題を回避するには、PostgreSQL コネクタのパススルークエリ機能を使用します。詳細については、このドキュメントの後半にある[パススルークエリ](#connectors-postgres-passthrough-queries)のセクションを参照してください。
## 用語
PostgreSQL コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して PostgreSQL コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して PostgreSQL コネクタを設定することをお勧めします。
そのためには、PostgreSQL コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type POSTGRESQL
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された PostgreSQL コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された PostgreSQL コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
postgres://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | PostGreSqlMuxCompositeHandler |
| メタデータハンドラー | PostGreSqlMuxMetadataHandler |
| レコードハンドラー | PostGreSqlMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mypostgrescatalog の場合、環境変数の名前は mypostgrescatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`postgres1` (デフォルト) と `postgres2` の 2 つのデータベースインスタンスをサポートする PostgreSql MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 |
| postgres\$1catalog1\$1connection\$1string | postgres://jdbc:postgresql://postgres1.host:5432/default?\$1\$1Test/RDS/PostGres1\$1 |
| postgres\$1catalog2\$1connection\$1string | postgres://jdbc:postgresql://postgres2.host:5432/default?user=sample&password=sample |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/PostGres1}` が含まれています。
```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&${Test/RDS/PostGres1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
postgres://jdbc:postgresql://postgres1.host:5432/default?...&user=sample2&password=sample2&...
```
現在、PostgreSQL コネクタは `user` と `password` の JDBC プロパティを認識します。
##### SSL を有効にしています
PostgreSQL 接続で SSL をサポートするには、接続文字列に以下を追加します。
```
&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```
**例**
次の接続文字列の例は SSL を使用していません。
```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword
```
SSL を有効にするには、文字列を次のように変更します。
```
postgres://jdbc:postgresql://example-asdf-aurora-postgres-endpoint:5432/asdf?user=someuser&password=somepassword&sslmode=verify-ca&sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory
```
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の PostgreSQL インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | PostGreSqlCompositeHandler |
| メタデータハンドラー | PostGreSqlMetadataHandler |
| レコードハンドラー | PostGreSqlRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の PostgreSQL インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | postgres://jdbc:postgresql://postgres1.host:5432/default?secret=\$1\$1Test/RDS/PostgreSQL1\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC、PostgreSQL、Arrow に対応するデータ型を示します。
****
| JDBC | PostgreSQL | Arrow |
| --- | --- | --- |
| ブール値 | ブール値 | Bit |
| 整数 | 該当なし | Tiny |
| ショート | smallint | Smallint |
| 整数 | integer | Int |
| Long | bigint | Bigint |
| float | float4 | Float4 |
| ダブル | float8 | Float8 |
| 日付 | date | DateDay |
| タイムスタンプ | timestamp | DateMilli |
| String | text | Varchar |
| バイト | bytes | Varbinary |
| BigDecimal | numeric(p,s) | 10 進数 |
| 配列 | 該当なし (注記を参照) | リスト |
**注記**
`ARRAY` 型は PostgreSQL コネクタでサポートされていますが、多次元配列 (`[][]` またはネストされた配列) はサポートされていないという制約があります。サポートされていない `ARRAY` データ型の列は文字列要素の配列 (`array`) に変換されます。
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
## パフォーマンス
PostgreSQL はネイティブパーティションをサポートしています。Athena PostgreSQL コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。
Athena PostgreSQL コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。ただし、列のサブセットを選択すると、クエリのランタイムが長くなる場合があります。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena PostgreSQL コネクタは、これらの式を組み合わせて PostgreSQL に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena PostgreSQL コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
PostgreSQL コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
PostgreSQL でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、PostgreSQL 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の PostgreSQL コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-postgresql/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-postgresql)を参照してください。
# Amazon Athena Redis OSS コネクタ
Amazon Athena Redis OSS コネクタは、Amazon Athena が Redis OSS インスタンスとやり取りすることを可能にして、Redis OSS データを SQL でクエリできるようにします。AWS Glue Data Catalog を使用して、Redis OSS のキーと値のペアを仮想テーブルにマッピングできます。
従来のリレーショナルデータストアとは異なり、Redis OSS にはテーブルや列の概念がありません。代わりに、Redis OSS にはキーと値のアクセスパターンが用意されています。キーは基本的に `string` で、値は `string`、`z-set`、または `hmap` です。
AWS Glue Data Catalog を使用して、スキーマを作成し、仮想テーブルを設定します。特別なテーブルプロパティによって、Redis OSS のキーと値をテーブルにマッピングする方法が Athena Redis OSS コネクタに伝えられます。詳細については、このドキュメントで後述する「[AWS Glue でのデータベースとテーブルのセットアップ](#connectors-redis-setting-up-databases-and-tables-in-glue)」を参照してください。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
Amazon Athena Redis OSS コネクタは Amazon MemoryDB および Amazon ElastiCache (Redis OSS) をサポートしています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して Redis コネクタを設定します。
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
## AWS Glue でのデータベースとテーブルのセットアップ
AWS Glue テーブルを Redis OSS で使用できるようにするために、テーブルに `redis-endpoint` および `redis-value-type`、さらに `redis-keys-zset` または `redis-key-prefix` のテーブルプロパティを設定できます。
さらに、Redis OSS テーブルを含む AWS Glue データベースには、データベースの URI プロパティに `redis-db-flag` がある必要があります。`redis-db-flag` URI プロパティ設定するには、AWS Glue コンソールでデータベースを編集します。
次のリストは、テーブルプロパティについての説明です。
+ **redis-endpoint** – (必須) このテーブルのデータを含む Redis OSS サーバーの*ホスト名*`:`*ポート*`:`*パスワード* (例: `athena-federation-demo.cache.amazonaws.com:6379`)。または、\$1\$1*Secret\$1Name*\$1 をテーブルプロパティ値として使用して、エンドポイント、またはエンドポイントの一部を AWS Secrets Manager に保存することもできます。
**注記**
Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
+ **redis-keys-zset** – (`redis-key-prefix` が使用されていない場合は必須) 値が [zset](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/) であるキーのカンマ区切りリスト (例: `active-orders,pending-orders`)。zset 内のそれぞれの値は、テーブルの一部であるキーとして扱われます。`redis-keys-zset` プロパティまたは `redis-key-prefix` プロパティのいずれかを設定する必要があります。
+ **redis-key-prefix** – (`redis-keys-zset` が使用されていない場合は必須) テーブル内の値をスキャンするキープレフィックスのカンマ区切りリスト (例: `accounts-*,acct-`)。`redis-key-prefix` プロパティまたは `redis-keys-zset` プロパティのいずれかを設定する必要があります。
+ **redis-value-type** – (必須) `redis-key-prefix` または `redis-keys-zset` のいずれかをテーブルにマッピングすることによって、キーの値がどのように定義されるかを定義します。リテラルは単一の列にマッピングされます。また、zset は単一の列にマッピングされますが、各キーには多数の行を格納できます。ハッシュを使用すると、各キーを複数の列 (ハッシュ、リテラル、zset など) から成る行にすることができます。
+ **redis-ssl-flag** – (オプション) `True` の場合、SSL/TLS を使用する Redis 接続を作成します。デフォルトは `False` です。
+ **edis-cluster-flag** – (オプション) `True` の場合、クラスター化された Redis インスタンスのサポートを有効にします。デフォルトは `False` です。
+ **redis-db-number** – (オプション) スタンドアロンのクラスター化されていないインスタンスにのみ適用されます。デフォルト以外の Redis データベースから読み込むには、この番号 (1、2、3 など) を設定します。デフォルトは Redis 論理データベース 0 です。この番号は、Athena や AWS Glue のデータベースではなく、Redis の論理データベースを示すものです。詳細については、Redis ドキュメントの「[SELECT index](https://redis.io/commands/select)」を参照してください。
## データ型
Redis OSS コネクタは、次のデータ型に対応しています。Redis OSS ストリームはサポートされていません。
+ [文字列](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-1-strings-in-redis/)
+ [ハッシュ](https://redis.com/ebook/part-1-getting-started/chapter-1-getting-to-know-redis/1-2-what-redis-data-structures-look-like/1-2-4-hashes-in-redis/)
+ ソート済みセット ([ZSet](https://redis.com/ebook/part-2-core-concepts/chapter-3-commands-in-redis/3-5-sorted-sets/))
Redis OSS すべての値は `string` データ型として取得されます。次に、テーブルが AWS Glue Data Catalog でどのように定義されているかに基づいて、次の Apache Arrow データ型のいずれかに変換されます。
****
| AWS Glue データ型 | Apache Arrow データ型 |
| --- | --- |
| int | INT |
| string | VARCHAR |
| bigint | BIGINT |
| double | FLOAT8 |
| float | FLOAT4 |
| smallint | SMALLINT |
| tinyint | TINYINT |
| boolean | BIT |
| バイナリ | VARBINARY |
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-redis.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redis/athena-redis.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** – Redis コネクタには、スキーマ情報を取得するために AWS Glue Data Catalog への読み込み専用アクセス権が必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **AWS Secrets Manager 読み込みアクセス** – Redis エンドポイントの詳細を Secrets Manager に保存する場合は、それらのシークレットへのアクセスをコネクタに許可する必要があります。
+ **VPC アクセス** – コネクタには、VPC に接続して Redis インスタンスと通信できるように、VPC にインターフェイスをアタッチおよびデタッチできることが必要です。
## パフォーマンス
Athena Redis OSS コネクタは、定義したテーブルのタイプ (zset キーやプレフィックスキーなど) に従って、Redis OSS インスタンスに対するクエリを並列化しようとします。
Athena Redis コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。ただし、プライマリキーに対する述語を含むクエリはタイムアウトで失敗します。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。Redis コネクタは同時実行によるスロットリングに強いです。
## パススルークエリ
Redis コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。この機能を使用して、Redis データベースで Lua スクリプトを使用するクエリを実行できます。
Redis でパススルークエリを作成するには、以下の構文を使用します。
```
SELECT * FROM TABLE(
system.script(
script => 'return redis.[call|pcall](query_script)',
keys => '[key_pattern]',
argv => '[script_arguments]'
))
```
次の例では、Lua スクリプトを実行して、`l:a` キーで値を取得します。
```
SELECT * FROM TABLE(
system.script(
script => 'return redis.call("GET", KEYS[1])',
keys => '[l:a]',
argv => '[]'
))
```
## ライセンス情報
Amazon Athena Redis コネクタプロジェクトは、[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) でライセンスされています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redis)を参照してください。
# Amazon Athena Redshift コネクタ
Amazon Athena Redshift コネクタは、Amazon Athena が Amazon Redshift データベースと Amazon Redshift Serverless データベース (Redshift Serverless ビューを含む) にアクセスすることを可能にします。どちらのサービスにも、このページで説明されている JDBC 接続文字列設定を使用して接続できます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ Redshift は外部パーティションをサポートしていないため、クエリで指定されたすべてのデータが毎回取得されます。
+ Redshift と同様に、Athena は Redshift `CHAR` タイプの末尾のスペースを、長さや比較の目的で意味的に重要ではないものとして扱います。これは `CHAR` にのみ適用され、`VARCHAR` タイプには適用されないことに留意してください。Athena は、`CHAR` タイプの末尾のスペースを無視しますが、`VARCHAR` タイプでは重要なものとして扱います。
## 用語
Redshift コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Redshift コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Redshift コネクタを設定することをお勧めします。そのためには、Amazon Redshift コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type REDSHIFT
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Redshift コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Redshift コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **disable\$1glue** – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
redshift://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | RedshiftMuxCompositeHandler |
| メタデータハンドラー | RedshiftMuxMetadataHandler |
| レコードハンドラー | RedshiftMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myredshiftcatalog の場合、環境変数の名前は myredshiftcatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`redshift1` (デフォルト) と `redshift2` の 2 つのデータベースインスタンスをサポートする Redshift MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | redshift://jdbc:redshift://redshift1.host:5439/dev?user=sample2&password=sample2 |
| redshift\$1catalog1\$1connection\$1string | redshift://jdbc:redshift://redshift1.host:3306/default?\$1\$1Test/RDS/Redshift1\$1 |
| redshift\$1catalog2\$1connection\$1string | redshift://jdbc:redshift://redshift2.host:3333/default?user=sample2&password=sample2 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列はシークレット名 \$1\$1Test/RDS/ `Redshift1`\$1 を含んでいます。
```
redshift://jdbc:redshift://redshift1.host:3306/default?...&${Test/RDS/Redshift1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
redshift://jdbc:redshift://redshift1.host:3306/default?...&user=sample2&password=sample2&...
```
現在、Redshift コネクタは `user` と `password` の JDBC プロパティを認識します。
## サポートされるデータ型
次の表に、JDBC と Apache Arrow に対応するデータ型を示します。
****
| JDBC | Arrow |
| --- | --- |
| ブール値 | Bit |
| 整数 | Tiny |
| ショート | Smallint |
| 整数 | Int |
| Long | Bigint |
| float | Float4 |
| ダブル | Float8 |
| 日付 | DateDay |
| タイムスタンプ | DateMilli |
| String | Varchar |
| バイト | Varbinary |
| BigDecimal | 10 進数 |
| 配列 | リスト |
## パーティションと分割
Redshift は外部パーティションをサポートしていません。パフォーマンス関連の問題については、「[パフォーマンス](#connectors-redshift-performance)」を参照してください。
## パフォーマンス
Athena Redshift コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、`ORDER BY` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。ただし、列のサブセットを選択すると、クエリのランタイムが長くなる場合があります。Amazon Redshift は、複数のクエリを同時に実行すると、特にクエリの実行速度が低下しやすくなります。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 上位 N 件のクエリ
上位 `N` 件のクエリは、結果セットの順序と返される行数に対する制限を指定します。このタイプのクエリを使用して、データセットの上位 `N` 個の最大値または上位 `N` 個の最小値を決定できます。上位 `N` 件のプッシュダウンを使用すると、コネクタは `N` 件の順序付けられた行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Redshift コネクタは、これらの式を組み合わせて Redshift に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Redshift コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
ORDER BY col_a DESC
LIMIT 10;
```
Amazon Redshift などのフェデレーテッドクエリのパフォーマンスを向上させるために述語プッシュダウンを使用する方法の記事については、*AWS Big Data Blog* の「[Improve federated queries with predicate pushdown in Amazon Athena](https://aws.amazon.com/blogs/big-data/improve-federated-queries-with-predicate-pushdown-in-amazon-athena/)」を参照してください。
## パススルークエリ
Redshift コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Redshift でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Redshift 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Redshift コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-redshift/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-redshift)を参照してください。
# Amazon Athena SAP HANA コネクタ
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ SAP HANA では、オブジェクト名が SAP HANA データベースに保存される際に大文字に変換されます。ただし、引用符で囲まれた名前は大文字と小文字が区別されるため、2 つのテーブルに同じ名前が小文字と大文字で存在する場合があります (たとえば、`EMPLOYEE` と `employee`)。
Athena のフェデレーティッドクエリでは、スキーマのテーブル名が小文字で Lambda 関数に渡されます。この問題を回避するには、クエリヒント `@schemaCase` を指定して、大文字と小文字が区別される名前のテーブルからデータを取得します。クエリヒントを含む 2 つのサンプルクエリを次に示します。
```
SELECT *
FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=upper"
```
```
SELECT *
FROM "lambda:saphanaconnector".SYSTEM."MY_TABLE@schemaCase=upper&tableCase=lower"
```
## 用語
SAP HANA コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して SAP HANA コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して SAP HANA コネクタを設定することをお勧めします。そのためには、SAP HANA コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type SAPHANA
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された SAP HANA コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された SAP HANA コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
saphana://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | SaphanaMuxCompositeHandler |
| メタデータハンドラー | SaphanaMuxMetadataHandler |
| レコードハンドラー | SaphanaMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysaphanacatalog の場合、環境変数の名前は mysaphanacatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`saphana1` (デフォルト) と `saphana2` の 2 つのデータベースインスタンスをサポートする Saphana MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 |
| saphana\$1catalog1\$1connection\$1string | saphana://jdbc:sap://saphana1.host:port/?\$1\$1Test/RDS/ Saphana1\$1 |
| saphana\$1catalog2\$1connection\$1string | saphana://jdbc:sap://saphana2.host:port/?user=sample2&password=sample2 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/Saphana1}` が含まれています。
```
saphana://jdbc:sap://saphana1.host:port/?${Test/RDS/Saphana1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
saphana://jdbc:sap://saphana1.host:port/?user=sample2&password=sample2&...
```
現在、SAP HANA コネクタは `user` と `password` の JDBC プロパティを認識します。
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の SAP HANA インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | SaphanaCompositeHandler |
| メタデータハンドラー | SaphanaMetadataHandler |
| レコードハンドラー | SaphanaRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の SAP HANA インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Apache Arrow に対応するデータ型を示します。
****
| JDBC | Arrow |
| --- | --- |
| ブール値 | Bit |
| 整数 | Tiny |
| ショート | Smallint |
| 整数 | Int |
| Long | Bigint |
| float | Float4 |
| ダブル | Float8 |
| 日付 | DateDay |
| タイムスタンプ | DateMilli |
| String | Varchar |
| バイト | Varbinary |
| BigDecimal | 10 進数 |
| 配列 | リスト |
## データ型変換
JDBC から Arrow への変換に加えて、コネクタは特定の別の変換を実行して SAP HANA ソースと Athena データ型との互換性を保ちます。これらの変換は、クエリを正常に実行するのに役立ちます。次の表に、これらの変換を示します。
****
| ソースデータタイプ (SAP HANA) | 変換されたデータ型 (Athena) |
| --- | --- |
| DECIMAL | BIGINT |
| INTEGER | INT |
| DATE | DATEDAY |
| TIMESTAMP | DATEMILLI |
その他のサポートされていないデータ型はすべて `VARCHAR` に変換されます。
## パーティションと分割
パーティションは、`Integer` 型の単一パーティション列で表されます。この列には、SAP HANA テーブルで定義されているパーティションのパーティション名が含まれます。パーティション名のないテーブルの場合、\$1 が返されます。これは 1 つのパーティションと同じです。パーティションはスプリットと同等です。
****
| 名前 | 型 | 説明 |
| --- | --- | --- |
| PART\$1ID | 整数 | SAP HANA の名前付きパーティション。 |
## パフォーマンス
SAP HANA はネイティブパーティションをサポートしています。Athena SAP HANA コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。コネクタでは、同時実行が原因で大幅なスロットリングが発生し、場合によってはクエリに失敗することもあります。
Athena SAP HANA コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena SAP HANA コネクタは、これらの式を組み合わせて SAP HANA に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena SAP HANA コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
## パススルークエリ
SAP HANA コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
SAP HANA でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、SAP HANA 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の SAP HANA コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-saphana/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-saphana)を参照してください。
# Amazon Athena Snowflake コネクタ
[Snowflake](https://www.snowflake.com/) 用の Amazon Athena コネクタを使用すると、Amazon Athena で Snowflake SQL または RDS インスタンスに保存されたデータに対して JDBC を使用して SQL クエリを実行できます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
Athena コンソールまたは `CreateDataCatalog` API オペレーションを使用して AWS アカウント にコネクタをデプロイします。詳細については、「[データソース接続を作成する](connect-to-a-data-source.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ マルチプレクサーのセットアップをサポートしているのはレガシー接続のみです。
+ 現在、単一スプリットの Snowflake ビューがサポートされています。
+ Snowflake では、オブジェクト名では大文字と小文字が区別されます。Athena では大文字と小文字の DDL クエリと DML クエリが受け入れられますが、クエリを実行するときのオブジェクト名はデフォルトで[小文字](https://docs.aws.amazon.com/athena/latest/ug/tables-databases-columns-names.html#table-names-and-table-column-names-in-ate-must-be-lowercase)になります。Snowflake コネクタは、Glue Catalog/Lake Formation を使用する場合にのみ小文字をサポートします。Athena Catalog が使用されている場合、お客様は `casing_mode` Lambda 環境変数を使用して大文字と小文字の動作を制御できます。使用できる値は [パラメータ](#connectors-snowflake-parameters) セクションに一覧表示されています（例: `key=casing_mode, value = CASE_INSENSITIVE_SEARCH`）。
## 用語
Snowflake コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Snowflake コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Snowflake コネクタを設定することをお勧めします。そのためには、Snowflake コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type SNOWFLAKE
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **NONE** – 指定されたスキーマとテーブル名の大文字と小文字を変更しないでください（Snowflake に対してクエリをそのまま実行します）。これは、**case\$1mode** が指定されていない場合のデフォルト値です。
+ **UPPER** – Snowflake に対して実行する前に、クエリで指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **LOWER** – Snowflake に対して実行する前に、クエリで指定されたすべてのスキーマ名とテーブル名を小文字にします。
+ **CASE\$1INSENSITIVE\$1SEARCH** – Snowflake においてスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。たとえば、`SELECT * FROM EMPLOYEE` のようなクエリがあって Snowflake に `Employee` というテーブルが含まれている場合に、このモードを使用できます。ただし、Snowflake に `EMPLOYEE` というテーブルと `Employee` という別のテーブルがある場合など、名前の衝突がある場合、クエリは失敗します。
**注記**
Glue 接続を使用して作成された Snowflake コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Snowflake コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
**認証情報を保存する**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。詳細については、「[Snowflake で認証する](connectors-snowflake-authentication.md)」を参照してください。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **default** – Snowflake データベースインスタンスへの接続に使用する JDBC 接続文字列。例: `snowflake://${jdbc_connection_string}`
+ **catalog\$1connection\$1string** – マルチプレックスハンドラーによって使用されます (Glue 接続を使用する場合はサポートされていません)。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysnowflakecatalog の場合、環境変数の名前は mysnowflakecatalog\$1connection\$1string になります。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **NONE** – 指定されたスキーマとテーブル名の大文字と小文字を変更しないでください（Snowflake に対してクエリをそのまま実行します）。これは、**case\$1mode** が指定されていない場合のデフォルト値です。
+ **UPPER** – Snowflake に対して実行する前に、クエリで指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **LOWER** – Snowflake に対して実行する前に、クエリで指定されたすべてのスキーマ名とテーブル名を小文字にします。
+ **CASE\$1INSENSITIVE\$1SEARCH** – Snowflake においてスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。たとえば、`SELECT * FROM EMPLOYEE` のようなクエリがあって Snowflake に `Employee` というテーブルが含まれている場合に、このモードを使用できます。ただし、Snowflake に `EMPLOYEE` というテーブルと `Employee` という別のテーブルがある場合など、名前の衝突がある場合、クエリは失敗します。
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
snowflake://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | SnowflakeMuxCompositeHandler |
| メタデータハンドラー | SnowflakeMuxMetadataHandler |
| レコードハンドラー | SnowflakeMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysnowflakecatalog の場合、環境変数の名前は mysnowflakecatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`snowflake1` (デフォルト) と `snowflake2` の 2 つのデータベースインスタンスをサポートする Snowflake MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1&\$1\$1Test/RDS/Snowflake1\$1 |
| snowflake\$1catalog1\$1connection\$1string | snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1\$1\$1Test/RDS/Snowflake1\$1 |
| snowflake\$1catalog2\$1connection\$1string | snowflake://jdbc:snowflake://snowflake2.host:port/?warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/Snowflake1}` が含まれています。
```
snowflake://jdbc:snowflake://snowflake1.host:port/?warehouse=warehousename&db=db1&schema=schema1${Test/RDS/Snowflake1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
snowflake://jdbc:snowflake://snowflake1.host:port/warehouse=warehousename&db=db1&schema=schema1&user=sample2&password=sample2&...
```
現在、Snowflake は `user` と `password` の JDBC プロパティを認識します。また、ユーザー名とパスワードを、`user` や `password` のキーなしで、*ユーザー名*`/`*パスワード*の形式で受け付けます。
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Snowflake インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | SnowflakeCompositeHandler |
| メタデータハンドラー | SnowflakeMetadataHandler |
| レコードハンドラー | SnowflakeRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Snowflake インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | snowflake://jdbc:snowflake://snowflake1.host:port/?secret=Test/RDS/Snowflake1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Apache Arrow に対応するデータ型を示します。
****
| JDBC | Arrow |
| --- | --- |
| ブール値 | Bit |
| 整数 | Tiny |
| ショート | Smallint |
| 整数 | Int |
| Long | Bigint |
| float | Float4 |
| ダブル | Float8 |
| 日付 | DateDay |
| タイムスタンプ | DateMilli |
| String | Varchar |
| バイト | Varbinary |
| BigDecimal | 10 進数 |
| 配列 | リスト |
## データ型変換
JDBC から Arrow への変換に加えて、コネクタは特定の別の変換を実行して Snowflake ソースと Athena データ型との互換性を保ちます。これらの変換は、クエリを正常に実行するのに役立ちます。次の表に、これらの変換を示します。
****
| ソースデータ型 (Snowflake) | 変換されたデータ型 (Athena) |
| --- | --- |
| TIMESTAMP | TIMESTAMPMILLI |
| DATE | TIMESTAMPMILLI |
| INTEGER | INT |
| DECIMAL | BIGINT |
| TIMESTAMP\$1NTZ | TIMESTAMPMILLI |
その他のサポートされていないデータ型はすべて `VARCHAR` に変換されます。
## パーティションと分割
パーティションは、コネクタを分割する方法を決定するために使用されます。Athena は `varchar` 型の合成列を作成し、コネクタが分割を生成できるようにするために、テーブルに対するパーティションのスキームを示します。コネクタは実際のテーブル定義を変更しません。
この合成列とパーティションを作成するには、Athena がプライマリキーの定義を要求します。ただし、Snowflake はプライマリキーの制約を強制しないため、ユーザー自身が一意性を強制する必要があります。これを行わなければ、Athena がデフォルトの単一分割を実行することになります。
## パフォーマンス
最適なパフォーマンスを得るには、可能な限りクエリでフィルターを使用します。さらに、パーティション分散が均一な巨大なデータセットを取得するには、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。Snowflake コネクタは、同時実行によるスロットリングに強いです。
Athena Snowflake コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。
### LIMIT 句
`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Snowflake コネクタは、これらの式を組み合わせて Snowflake に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Snowflake コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%')
LIMIT 10;
```
# Snowflake で認証する
Amazon Athena Snowflake コネクタは、キーペア認証または OAuth 認証方法を使用して Snowflake データウェアハウスに接続するように設定できます。どちらの方法でも、Snowflake へのセキュアアクセスを提供し、接続文字列にパスワードを保存する必要がなくなります。
+ **キーペア認証** – この方法は、RSA パブリックキーペアまたはプライベートキーペアを使用して Snowflake で認証します。プライベートキーは認証リクエストにデジタル署名するものであり、対応するパブリックキーは検証のために Snowflake に登録されます。この方法だと、パスワードを保存する必要がなくなります。
+ **OAuth 認証** – この方法は、認可トークンと更新トークンを使用して Snowflake で認証します。自動トークン更新をサポートしているため、長時間実行されるアプリケーションに適しています。
詳細については、Snowflake ユーザーガイドの「[キーペア認証](https://docs.snowflake.com/en/user-guide/key-pair-auth)」と「[OAuth 認証](https://docs.snowflake.com/en/user-guide/oauth-custom)」を参照してください。
## 前提条件
開始する前に、次の前提条件を完了します。
+ 管理者権限を持つ Snowflake アカウントアクセス。
+ Athena コネクタ専用の Snowflake ユーザーアカウント。
+ キーペア認証用の OpenSSL またはそれと同等のキー生成ツール。
+ シークレットを作成および管理するための AWS Secrets Manager アクセス。
+ OAuth 認証の OAuth フローを完了するためのウェブブラウザ。
## キーペア認証を設定する
このプロセスでは、RSA キーペアの生成、パブリックキーを使用した Snowflake アカウントの設定、AWS Secrets Manager でのプライベートキーの安全な保存を行います。次の手順では、暗号化キーの作成、必要な Snowflake アクセス許可の設定、シームレスな認証を実現するための AWS 認証情報の設定について説明します。
1. **RSA キーペアを生成する**
OpenSSL を使用してプライベートキーとパブリックキーのペアを生成します。
+ 暗号化されていないバージョンを生成するには、ローカルのコマンドラインアプリケーションで次のコマンドを使用します。
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```
+ 暗号化されたバージョンを生成するには、`-nocrypt` を省略した次のコマンドを使用します。
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
```
+ プライベートキーからパブリックキーを生成する場合
```
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
# Set appropriate permissions (Unix/Linux)
chmod 600 rsa_key.p8
chmod 644 rsa_key.pub
```
**注記**
プライベートキーは共有しないでください。プライベートキーにアクセスするのは、Snowflake で認証する必要があるアプリケーションのみであるべきです。
1. **Snowflake のパブリックキーコンテンツを区切り文字なしで抽出する**
```
# Extract public key content (remove BEGIN/END lines and newlines)
cat rsa_key.pub | grep -v "BEGIN\|END" | tr -d '\n'
```
次のステップの後半で必要になるため、この出力を保存します。
1. **Snowflake ユーザーを設定する**
Snowflake ユーザーを設定するには、次の手順に従います。
1. Athena コネクタがまだ存在しない場合は、専用ユーザーを作成します。
```
-- Create user for Athena connector
CREATE USER athena_connector_user;
-- Grant necessary privileges
GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE athena_connector_role;
GRANT USAGE ON DATABASE your_database TO ROLE athena_connector_role;
GRANT SELECT ON ALL TABLES IN DATABASE your_database TO ROLE athena_connector_role;
```
1. 認証権限を付与します。ユーザーにパブリックキーを割り当てるには、次のいずれかのロールまたは権限が必要です。
+ ユーザーの `MODIFY PROGRAMMATIC AUTHENTICATION METHODS` または `OWNERSHIP` 権限。
+ `SECURITYADMIN` ロール 以上。
次のコマンドを使用して、パブリックキーを割り当てるために必要な権限を付与します。
```
GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER athena_connector_user TO ROLE your_admin_role;
```
1. 次のコマンドを使用して、パブリックキーを Snowflake ユーザーに割り当てます。
```
ALTER USER athena_connector_user SET RSA_PUBLIC_KEY='RSAkey';
```
次のコマンドを使用して、パブリックキーがユーザーに正常に割り当てられていることを確認します。
```
DESC USER athena_connector_user;
```
1. **AWS Secrets Manager にプライベートキーを保存する**
1. プライベートキーを、コネクタに必要な形式に変換します。
```
# Read private key content
cat rsa_key.p8
```
1. AWS Secrets Manager で、次のような構造体のシークレットを作成します。
```
{
"sfUser": "your_snowflake_user",
"pem_private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"pem_private_key_passphrase": "passphrase_in_case_of_encrypted_private_key(optional)"
}
```
**注記**
ヘッダーとフッターはオプションです。
プライベートキーは `\n` で区切る必要があります。
## OAuth 認証を設定する
この認証方法では、認証情報の自動更新機能を使用して、Snowflake へのトークンベースのセキュアアクセスが可能になります。設定プロセスでは、Snowflake でのセキュリティ統合の作成、OAuth クライアント認証情報の取得、アクセスコードを取得するための認可フローの完了、コネクタが使用する OAuth 認証情報の AWS Secrets Manager への保存を行います。
1. **Snowflake でセキュリティ統合を作成する**
Snowflake で次の SQL コマンドを実行して、Snowflake OAuth セキュリティ統合を作成します。
```
CREATE SECURITY INTEGRATION my_snowflake_oauth_integration_a
TYPE = OAUTH
ENABLED = TRUE
OAUTH_CLIENT = CUSTOM
OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
OAUTH_REDIRECT_URI = 'https://localhost:8080/oauth/callback'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = 7776000;
```
**設定パラメータ**
+ `TYPE = OAUTH` – OAuth 認証タイプを指定します。
+ `ENABLED = TRUE` – セキュリティ統合を有効にします。
+ `OAUTH_CLIENT = CUSTOM` – カスタム OAuth クライアント設定を使用します。
+ `OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'` – 安全なアプリケーションのクライアントタイプを設定します。
+ `OAUTH_REDIRECT_URI` – OAuth フローのコールバック URL。テストでは localhost にすることができます。
+ `OAUTH_ISSUE_REFRESH_TOKENS = TRUE` – 更新トークンの生成を有効にします。
+ `OAUTH_REFRESH_TOKEN_VALIDITY = 7776000` – 更新トークンの有効期間 (90日、秒単位) を設定します。
1. **OAuth クライアントシークレットを取得する**
1. 次の SQL コマンドを実行して、これらの認証情報を取得します。
```
DESC SECURITY INTEGRATION 'MY_SNOWFLAKE_OAUTH_INTEGRATION_A';
```
1. OAuth クライアントシークレットを取得します。
```
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('MY_SNOWFLAKE_OAUTH_INTEGRATION_A');
```
**レスポンスの例**
```
{
"OAUTH_CLIENT_SECRET_2": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"OAUTH_CLIENT_SECRET": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY,
"OAUTH_CLIENT_ID": "AIDACKCEVSQ6C2EXAMPLE"
}
```
**注記**
これらの認証情報は安全に保管し、共有しないでください。これらは OAuth クライアントの設定に使用されます。
1. **ユーザーを承認し、認可コードを取得する**
1. 次の URL をブラウザで開きます。
```
https://.snowflakecomputing.com/oauth/authorize?client_id=&response_type=code&redirect_uri=https://localhost:8080/oauth/callback
```
1. 認可フローを完了します。
1. Snowflake 認証情報を使用してサインインします。
1. リクエストされたアクセス許可を付与します。認可コードが付加されたコールバック URI にリダイレクトされます。
1. リダイレクト URL からコードパラメータをコピーして、認可コードを抽出します。
```
https://localhost:8080/oauth/callback?code=
```
**注記**
認可コードは期間限定で有効で、1 回のみ使用できます。
1. **AWS Secrets Manager に OAuth 認証情報を保存する**
AWS Secrets Manager で、次のような構造体のシークレットを作成します。
```
{
"redirect_uri": "https://localhost:8080/oauth/callback",
"client_secret": "je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY",
"token_url": "https://.snowflakecomputing.com/oauth/token-request",
"client_id": "AIDACKCEVSQ6C2EXAMPLE,
"username": "your_snowflake_username",
"auth_code": "authorizationcode"
}
```
**必須フィールド**
+ `redirect_uri` – ステップ 1 で取得した OAuth リダイレクト URI。
+ `client_secret` – ステップ 2 で取得した OAuth クライアントシークレット。
+ `token_url` – Snowflake OAuth トークンエンドポイント。
+ `client_id` – ステップ 2 の OAuth クライアント ID。
+ `username` – コネクタの Snowflake ユーザー名。
+ `auth_code` – ステップ 3 で取得した認可コード。
シークレットを作成したら、[データソース接続を作成する](connect-to-a-data-source.md)ときに Glue 接続で使用できるシークレット ARN を取得します。
## パススルークエリ
Snowflake コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Snowflake でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Snowflake 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Snowflake コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-snowflake/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-snowflake)を参照してください。
# Amazon Athena Microsoft SQL Server コネクタ
[Microsoft SQL Server](https://docs.microsoft.com/en-us/sql/?view=sql-server-ver15) 用の Amazon Athena コネクタを使用すると、Amazon Athena で Microsoft SQL Server に保存されたデータに JDBC を使用して SQL クエリを実行できます。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
+ フィルター条件では、`Date` と `Timestamp` データ型を適切なデータ型に型変換する必要があります。
+ `Real` および `Float` 型の負の値を検索するには、`<=` または `>=` 演算子を使用します。
+ `binary`、`varbinary`、`image`、および `rowversion` データ型はサポートされていません。
## 用語
SQL Server コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して SQL Server コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して SQL Server コネクタを設定することをお勧めします。そのためには、SQL Server コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type SQLSERVER
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された SQL Server コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された SQL Server コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
sqlserver://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | SqlServerMuxCompositeHandler |
| メタデータハンドラー | SqlServerMuxMetadataHandler |
| レコードハンドラー | SqlServerMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysqlservercatalog の場合、環境変数の名前は mysqlservercatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`sqlserver1` (デフォルト) と `sqlserver2` の 2 つのデータベースインスタンスをサポートする SqlServer MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| sqlserver\$1catalog1\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver1.hostname:port;databaseName=;\$1\$1secret1\$1name\$1 |
| sqlserver\$1catalog2\$1connection\$1string | sqlserver://jdbc:sqlserver://sqlserver2.hostname:port;databaseName=;\$1\$1secret2\$1name\$1 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${secret_name}` が含まれています。
```
sqlserver://jdbc:sqlserver://hostname:port;databaseName=;${secret_name}
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
sqlserver://jdbc:sqlserver://hostname:port;databaseName=;user=;password=
```
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の SQL Server インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | SqlServerCompositeHandler |
| メタデータハンドラー | SqlServerMetadataHandler |
| レコードハンドラー | SqlServerRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の SQL Server インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | sqlserver://jdbc:sqlserver://hostname:port;databaseName=;\$1\$1secret\$1name\$1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、SQL Server と Apache Arrow に対応するデータ型を示します。
****
| SQL Server | Arrow |
| --- | --- |
| bit | TINYINT |
| tinyint | SMALLINT |
| smallint | SMALLINT |
| int | INT |
| bigint | BIGINT |
| decimal | DECIMAL |
| numeric | FLOAT8 |
| smallmoney | FLOAT8 |
| money | DECIMAL |
| float[24] | FLOAT4 |
| float[53] | FLOAT8 |
| real | FLOAT4 |
| datetime | Date(MILLISECOND) |
| datetime2 | Date(MILLISECOND) |
| smalldatetime | Date(MILLISECOND) |
| date | Date(DAY) |
| 時間 | VARCHAR |
| datetimeoffset | Date(MILLISECOND) |
| char[n] | VARCHAR |
| varchar[n/max] | VARCHAR |
| nchar[n] | VARCHAR |
| nvarchar[n/max] | VARCHAR |
| text | VARCHAR |
| ntext | VARCHAR |
## パーティションと分割
パーティションは、`varchar` 型の単一パーティション列で表されます。SQL Server コネクタの場合、パーティション関数によってテーブルへのパーティションの適用方法が決まります。パーティション関数と列名の情報は、SQL Server メタデータテーブルから取得されます。次に、カスタムクエリによってパーティションが取得されます。スプリットは、受信した個別のパーティションの数に基づいて作成されます。
## パフォーマンス
列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。SQL Server コネクタは、同時実行によるスロットリングに強いです。
Athena SQL Server コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。単純な述語と複雑な式はコネクタにプッシュダウンされるため、スキャンされるデータ量が減少し、クエリ実行のランタイムが短縮されます。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena SQL Server コネクタは、これらの式を組み合わせて SQL Server に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena SQL Server コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、IS\$1DISTINCT\$1FROM、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## パススルークエリ
SQL Server コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
SQL Server でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、SQL Server 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の SQL Server コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-sqlserver/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-sqlserver)を参照してください。
# Amazon Athena Teradata コネクタ
Teradata 用の Amazon Athena コネクタを使用すると、Athena で Teradata データベースに保存されたデータに SQL クエリを実行できます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## 制限事項
+ DDL の書き込みオペレーションはサポートされていません。
+ マルチプレクサの設定では、スピルバケットとプレフィックスが、すべてのデータベースインスタンスで共有されます。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
## 用語
Teradata コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。
## パラメータ
このセクションのパラメータを使用して Teradata コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Teradata コネクタを設定することをお勧めします。そのためには、Teradat コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type TERADATA
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Teradata コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Teradata コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
teradata://${jdbc_connection_string}
```
#### マルチプレックスハンドラーの使用
マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。
****
| Handler | Class |
| --- | --- |
| 複合ハンドラー | TeradataMuxCompositeHandler |
| メタデータハンドラー | TeradataMuxMetadataHandler |
| レコードハンドラー | TeradataMuxRecordHandler |
##### マルチプレックスハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| \$1catalog\$1connection\$1string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myteradatacatalog の場合、環境変数の名前は myteradatacatalog\$1connection\$1string になります。 |
| default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:\$1\$1AWS\$1LAMBDA\$1FUNCTION\$1NAME\$1 の場合に使用されます。 |
`teradata1` (デフォルト) と `teradata2` の 2 つのデータベースインスタンスをサポートする Teradata MUX Lambda 関数用のプロパティを次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 |
| teradata\$1catalog1\$1connection\$1string | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,\$1\$1Test/RDS/Teradata1\$1 |
| teradata\$1catalog2\$1connection\$1string | teradata://jdbc:teradata://teradata2.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,user=sample2&password=sample2 |
##### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 `${Test/RDS/Teradata1}` が含まれています。
```
teradata://jdbc:teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,${Test/RDS/Teradata1}&...
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,...&user=sample2&password=sample2&...
```
現在、Teradata は `user` と `password` の JDBC プロパティを認識します。また、ユーザー名とパスワードを、`user` や `password` のキーなしで、*ユーザー名*`/`*パスワード*の形式で受け付けます。
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Teradata インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | TeradataCompositeHandler |
| メタデータハンドラー | TeradataMetadataHandler |
| レコードハンドラー | TeradataRecordHandler |
##### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
Lambda 関数でサポートされる単一の Teradata インスタンス用のプロパティ例を次に示します。
****
| プロパティ | 値 |
| --- | --- |
| default | teradata://jdbc:teradata://teradata1.host/TMODE=ANSI,CHARSET=UTF8,DATABASE=TEST,secret=Test/RDS/Teradata1 |
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表に、JDBC と Apache Arrow に対応するデータ型を示します。
****
| JDBC | Arrow |
| --- | --- |
| ブール値 | Bit |
| 整数 | Tiny |
| ショート | Smallint |
| 整数 | Int |
| Long | Bigint |
| float | Float4 |
| ダブル | Float8 |
| 日付 | DateDay |
| タイムスタンプ | DateMilli |
| String | Varchar |
| バイト | Varbinary |
| BigDecimal | 10 進数 |
| 配列 | リスト |
## パーティションと分割
パーティションは、`Integer` 型の単一パーティション列で表されます。この列には、Teradata テーブルで定義されているパーティションのパーティション名が含まれます。パーティション名のないテーブルの場合、\$1 が返されます。これは 1 つのパーティションと同じです。パーティションはスプリットと同等です。
****
| 名前 | 型 | 説明 |
| --- | --- | --- |
| パーティション | 整数 | Teradata の名前付きパーティション。 |
## パフォーマンス
Teradata はネイティブパーティションをサポートしています。Athena Teradata コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に遅くなります。同時実行が原因で、コネクタにスロットリングが発生しています。
Athena Teradata コネクタは、述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。単純な述語と複雑な式はコネクタにプッシュダウンされるため、スキャンされるデータ量が減少し、クエリ実行のランタイムが短縮されます。
### 述語
述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする SQL クエリの `WHERE` 句内の式です。Athena Teradata コネクタは、これらの式を組み合わせて Teradata に直接プッシュすることで、機能を強化し、スキャンされるデータ量を削減できます。
次の Athena Teradata コネクタ演算子は、述語のプッシュダウンをサポートしています。
+ **ブーリアン: **AND、OR、NOT
+ **等値: **EQUAL、NOT\$1EQUAL、LESS\$1THAN、LESS\$1THAN\$1OR\$1EQUAL、GREATER\$1THAN、GREATER\$1THAN\$1OR\$1EQUAL、NULL\$1IF、IS\$1NULL
+ **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **その他: **LIKE\$1PATTERN、IN
### 組み合わせたプッシュダウンの例
クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。
```
SELECT *
FROM my_table
WHERE col_a > 10
AND ((col_a + col_b) > (col_c % col_d))
AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%');
```
## パススルークエリ
Teradata コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Teradata でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Teradata 内のデータソースにクエリをプッシュダウンします。クエリは、`customer` テーブル内のすべての列を選択します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com の Teradata コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-teradata/pom.xml) ファイルを参照してください。
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-teradata)を参照してください。
# Amazon Athena Timestream コネクタ
Amazon Athena Timestream コネクタにより、Amazon Athena で [Amazon Timestream](https://aws.amazon.com/timestream/) とやり取りすることをが可能です。また、Amazon Athena を通して時系列データにアクセスできます。AWS Glue Data Catalog は、オプションで補足メタデータのソースとして使用できます。
Amazon Timestream は、高速でスケーラブルなフルマネージド型の専用時系列データベースで、1 日あたり何兆もの時系列データポイントの保存と分析を容易にします。Timestream は、最新のデータをメモリに保持し、履歴データをユーザー定義のポリシーに基づいてコスト最適化ストレージ階層に移動することで、時系列データのライフサイクル管理にかかる時間とコストを節約します。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して Timestream コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Timestream コネクタを設定することをお勧めします。そのためには、Timestream コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type TIMESTREAM
```
**Lambda 環境プロパティ**
**glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Timestream コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Timestream コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、関連付けられた Glue 接続なしで作成された Athena データソースコネクタ用です。以下のパラメータは、Athena データソースコネクタの以前のバージョンを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合、または `glue_connection` 環境プロパティが指定されていない場合にのみ使用します。
**Lambda 環境プロパティ**
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
+ **glue\$1catalog** – (オプション) [クロスアカウントの AWS Glue カタログ](data-sources-glue-cross-account.md)を指定するために、このオプションを使用します。デフォルトでは、コネクタは自身の AWS Glue アカウントからメタデータを取得しようとします。
## でのデータベースとテーブルのセットアップAWS Glue
オプションで、AWS Glue Data Catalog を補足メタデータのソースとして使用できます。Timestream での使用のために AWS Glue テーブルを有効にするには、補足メタデータを供給する Timestream データベースに一致する名前の AWS Glue データベースとテーブルが必要です。
**注記**
最高のパフォーマンスを得るには、 データベース名とテーブル名には小文字のみを使用してください。大文字と小文字が混在すると、コネクタは大文字と小文字を区別しない検索を実行するため、計算量が多くなります。
Timestream での使用のために AWS Glue テーブルを設定するには、AWS Glue でそのテーブルのプロパティを設定する必要があります。
**補足メタデータのために AWS Glue を使用するには**
1. AWS Glue コンソールでテーブルを編集して、次のテーブルプロパティを追加します。
+ **timestream-metadata-flag** — このプロパティは、補足メタデータのテーブルをコネクタが使用できることを Timestream コネクタに示します。`timestream-metadata-flag` プロパティがテーブルプロパティのリスト内に存在するのであれば、この `timestream-metadata-flag` に任意の値を指定することが可能です。
+ **\$1view\$1template** — 補足メタデータに AWS Glue を使用する場合は、このテーブルプロパティを使用して、任意の Timestream SQL をビューとして指定できます。Athena Timestream コネクタは、ビューからの SQL と Athena の SQL を使用してクエリを実行します。これは、Athena では利用できない Timestream SQL の機能を使用する場合に便利です。
1. このドキュメントに記載されているとおりに、AWS Glue 用として適切なデータ型を使用しているか確認してください。
### データ型
現在、Timestream コネクタは Timestream で使用可能なデータ型のサブセット (具体的にはスカラー値 `varchar`、`double`、および `timestamp`) のみをサポートしています。
`timeseries` データ型をクエリするには、Timestream `CREATE_TIME_SERIES` 関数を使用する AWS Glue テーブルプロパティでビューを設定する必要があります。また、任意の時系列の列のタイプとして構文 `ARRAY>` を使用するビューのスキーマを提供する必要があります。`double` をテーブルに適したスカラータイプに必ず置き換えてください。
次のイメージは、時系列でビューをセットアップするように設定された AWS Glue テーブルプロパティの例を示しています。
![\[時系列でビューをセットアップする AWS Glue のテーブルプロパティの設定。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-timestream-1.png)
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-timestream.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-timestream/athena-timestream.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
+ **AWS Glue Data Catalog** — Timestream コネクタには、スキーマ情報を取得するために AWS Glue Data Catalog への読み込み専用アクセス権が必要です。
+ **CloudWatch Logs** – コネクタは、ログを保存するために CloudWatch Logs にアクセスする必要があります。
+ **Timestream Access** — Timestream クエリの実行用です。
## パフォーマンス
`LIMIT` 句を使用して、インタラクティブなクエリのパフォーマンスを確保するために、返されるデータ (スキャンされたデータではない) を 256 MB 未満に制限することをお勧めします。
Athena Timestream コネクタは、述語プッシュダウンを実行してクエリがスキャンするデータを減少させます。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。Timestream コネクタは、同時実行によるスロットリングに強いです。
## パススルークエリ
Timestream コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Timestream でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
次のクエリ例は、Timestream 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
Amazon Athena Timestream コネクタプロジェクトは、[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) でライセンスされています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-timestream)を参照してください。
# Amazon Athena TPC Benchmark DS (TPC-DS) コネクタ
Amazon Athena TPC-DS コネクタは、Amazon Athena で、Athena フェデレーションでのベンチマークや機能のテストに使用するランダムに生成された TPC Benchmark DS データのソースとやり取りすることを可能にします。Athena TPC-DS コネクタは、4 つのスケール係数のいずれかで TPC-DS 準拠のデータベースを生成します。Amazon S3 が基盤となるデータレイクのパフォーマンステストの代わりにこのコネクタを使用することはお勧めしません。
このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
## パラメータ
このセクションのパラメータを使用して TPC-DS コネクタを設定します。
**注記**
2024 年 12 月 3 日以降に作成された Athena データソースコネクタは、AWS Glue 接続を使用します。
以下に示すパラメータ名と定義は、2024 年 12 月 3 日より前に作成された Athena データソースコネクタ用です。これらは、対応する [AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)とは異なる場合があります。2024 年 12 月 3 日以降、以前のバージョンの Athena データソースコネクタを[手動でデプロイ](connect-data-source-serverless-app-repo.md)する場合にのみ、以下のパラメータを使用します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して TPC-DS コネクタを設定することをお勧めします。そのためには、TPC-DS コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type TPCDS
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された TPC-DS コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された TPC-DS コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
+ **spill\$1bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
+ **spill\$1prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
+ **spill\$1put\$1request\$1headers** – (オプション) スピリングに使用されるAmazon S3 の `putObject` リクエスト (例:`{"x-amz-server-side-encryption" : "AES256"}`) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。
+ **kms\$1key\$1id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
+ **disable\$1spill\$1encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。
## テストデータベースとテーブル
Athena TPC-DS コネクタは、4 つのスケール係数 `tpcds1`、`tpcds10`、`tpcds100`、`tpcds250` または `tpcds1000` のいずれかで TPC-DS 準拠のデータベースを生成します。
### テーブルの概要
テストデータのテーブルと列の完全なリストを確認するには、`SHOW TABLES` または `DESCRIBE TABLE` クエリを実行してください。次のテーブルの概要は、便宜上提供されています。
1. call\$1center
1. catalog\$1page
1. catalog\$1returns
1. catalog\$1sales
1. カスタマー
1. customer\$1address
1. customer\$1demographics
1. date\$1dim
1. dbgen\$1version
1. household\$1demographics
1. income\$1band
1. インベントリ
1. item
1. プロモーション
1. 理由
1. ship\$1mode
1. ストア
1. store\$1returns
1. store\$1sales
1. time\$1dim
1. ウェアハウス
1. web\$1page
1. web\$1returns
1. web\$1sales
1. web\$1site
この生成されたスキーマとデータに対応する TPC-DS クエリについては、GitHub の [athena-tpcds/src/main/resources/queries/](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds/src/main/resources/queries) ディレクトリを参照してください。
### クエリの例
次の `SELECT` クエリの例では、郡別の顧客層の `tpcds` カタログをクエリしています。
```
SELECT
cd_gender,
cd_marital_status,
cd_education_status,
count(*) cnt1,
cd_purchase_estimate,
count(*) cnt2,
cd_credit_rating,
count(*) cnt3,
cd_dep_count,
count(*) cnt4,
cd_dep_employed_count,
count(*) cnt5,
cd_dep_college_count,
count(*) cnt6
FROM
"lambda:tpcds".tpcds1.customer c, "lambda:tpcds".tpcds1.customer_address ca, "lambda:tpcds".tpcds1.customer_demographics
WHERE
c.c_current_addr_sk = ca.ca_address_sk AND
ca_county IN ('Rush County', 'Toole County', 'Jefferson County',
'Dona Ana County', 'La Porte County') AND
cd_demo_sk = c.c_current_cdemo_sk AND
exists(SELECT *
FROM "lambda:tpcds".tpcds1.store_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = ss_customer_sk AND
ss_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3) AND
(exists(SELECT *
FROM "lambda:tpcds".tpcds1.web_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = ws_bill_customer_sk AND
ws_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3) OR
exists(SELECT *
FROM "lambda:tpcds".tpcds1.catalog_sales, "lambda:tpcds".tpcds1.date_dim
WHERE c.c_customer_sk = cs_ship_customer_sk AND
cs_sold_date_sk = d_date_sk AND
d_year = 2002 AND
d_moy BETWEEN 1 AND 1 + 3))
GROUP BY cd_gender,
cd_marital_status,
cd_education_status,
cd_purchase_estimate,
cd_credit_rating,
cd_dep_count,
cd_dep_employed_count,
cd_dep_college_count
ORDER BY cd_gender,
cd_marital_status,
cd_education_status,
cd_purchase_estimate,
cd_credit_rating,
cd_dep_count,
cd_dep_employed_count,
cd_dep_college_count
LIMIT 100
```
## 必要な許可
このコネクタが必要とする IAM ポリシーの完全な詳細については、[athena-tpcds.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-tpcds/athena-tpcds.yaml) ファイルの `Policies` セクションを参照してください。次のリストは、必要なアクセス権限をまとめたものです。
+ **Amazon S3 への書き込みアクセス** – 大規模なクエリからの結果をスピルするために、コネクタは Amazon S3 内のロケーションへの書き込みアクセス権限を必要とします。
+ **Athena GetQueryExecution** – コネクタはこの権限を使用して、アップストリームの Athena クエリが終了した際に fast-fail を実行します。
## パフォーマンス
Athena TPC-DS コネクタは、選択したスケールファクターに基づいてクエリの並列化を試みます。述語のプッシュダウンは Lambda 関数内で実行されます。
## ライセンス情報
Amazon Athena TPC-DS コネクタプロジェクトは、[Apache-2.0 License](https://www.apache.org/licenses/LICENSE-2.0.html) でライセンスされています。
## その他のリソース
このコネクタに関するその他の情報については、GitHub.com で[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-tpcds)を参照してください。
# Amazon Athena Vertica コネクタ
Vertica は、クラウドまたはオンプレミスでデプロイできる列指向データベースプラットフォームで、エクサバイト規模のデータウェアハウスをサポートします。Athena からの Vertica データソースのクエリには、フェデレーティッドクエリで Amazon Athena Vertica コネクタを使用できます。たとえば、Vertica 上のデータウェアハウスと Amazon S3 のデータレイクに対して分析クエリを実行できます。
このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元化しません。接続設定は Lambda を介して行われます。
## 前提条件
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。
+ このコネクタを使用する際は、先に VPC とセキュリティグループをセットアップしておきます。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
## 制限事項
+ Athena Vertica コネクタは、Amazon S3 からエクスポートされた Parquet ファイルを読み取るので、コネクタのパフォーマンスが低下する可能性があります。大きなテーブルに対してクエリを実行する場合は、[CREATE TABLE AS (SELECT ...)](ctas.md) クエリおよび SQL 述語を使用することをお勧めします。
+ 現在、Athena フェデレーティッドクエリでの既知の問題のため、コネクタにより Vertica ではクエリされたテーブルのすべての列が Amazon S3 にエクスポートされますが、Athena コンソールの結果にはクエリされた列のみが表示されます。
+ DDL の書き込みオペレーションはサポートされていません。
+ 関連性のある Lambda 上限値。詳細については、「*AWS Lambda デベロッパーガイド*」の「[Lambda のクォータ](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html)」を参照してください。
## ワークフロー
次の図は、Vertica コネクタを使用するクエリのワークフローを示しています。
![\[Amazon Athena からの Vertica クエリのワークフロー\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-vertica-1.png)
1. SQL クエリは、Vertica の 1 つ以上のテーブルに対して発行されます。
1. コネクタは SQL クエリを解析し、関連する部分を JDBC 接続経由で Vertica に送信します。
1. Vertica にアクセスするため、接続文字列には AWS Secrets Manager に保存されているユーザー名とパスワードを使用します。
1. コネクタは、次の例のように SQL クエリを Vertica の `EXPORT` コマンドでラップします。
```
EXPORT TO PARQUET (directory = 's3://amzn-s3-demo-bucket/folder_name,
Compression='Snappy', fileSizeMB=64) OVER() as
SELECT
PATH_ID,
...
SOURCE_ITEMIZED,
SOURCE_OVERRIDE
FROM DELETED_OBJECT_SCHEMA.FORM_USAGE_DATA
WHERE PATH_ID <= 5;
```
1. Vertica が SQL クエリを処理し、結果セットを Amazon S3 バケットに送信します。スループットを向上させるため、Vertica は `EXPORT` オプションを使用して、複数の Parquet ファイルの書き込みオペレーションを並列化します。
1. Athena は Amazon S3 バケットをスキャンして、結果セット用に読み込むファイルの数を決定します。
1. Athena は Lambda 関数を複数回呼び出し、Apache `ArrowReader` を使用して結果のデータセットから Parquet ファイルを読み取ります。複数回呼び出しを行うことで、Athena は Amazon S3 ファイルの読み取りを並列化し、1 秒あたり最大 100 GB のスループットを達成できます。
1. Athena は、Vertica から返されたデータをデータレイクからスキャンされたデータで処理し、その結果を返します。
## 用語
Vertica コネクタに関連する用語を次に示します。
+ **データベースインスタンス** — Amazon EC2 にデプロイされた Vertica データベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
## パラメータ
このセクションのパラメータを使用して Vertica コネクタを設定します。
### Glue 接続 (推奨)
Glue 接続オブジェクトを使用して Vertica コネクタを設定することをお勧めします。そのためには、Vertica コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。
**Glue 接続プロパティ**
次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。
```
aws glue describe-connection-type --connection-type VERTICA
```
**Lambda 環境プロパティ**
+ **glue\$1connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。
+ **casing\$1mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。
+ **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。
+ **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。
+ **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。
**注記**
Glue 接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。
Glue 接続を使用して作成された Vertica コネクタは、マルチプレックスハンドラーの使用をサポートしていません。
Glue 接続を使用して作成された Vertica コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。
### レガシー接続
Amazon Athena Vertica コネクタは Lambda 環境変数を使用して、設定オプションを公開します。次の Lambda 環境変数を使用して、コネクタを設定できます。
+ **AthenaCatalogName** — Lambda 関数名
+ **ExportBucket** — Vertica のクエリ結果がエクスポートされる Amazon S3 バケット。
+ **SpillBucket** — この関数がデータを提供できる Amazon S3 バケットの名前。
+ **SpillPrefix** — この関数がデータを提供できる `SpillBucket` の場所のプレフィックス。
+ **SecurityGroupIds** — Lambda 関数に適用する必要があるセキュリティグループに対応する 1 つ以上の ID (例: `sg1`、`sg2`、または `sg3`)。
+ **SubnetIds** — Lambda 関数がデータソースへのアクセスに使用できるサブネットに対応する 1 つ以上のサブネット ID (例: `subnet1`、または `subnet2`)。
+ **SecretNameOrPrefix** — この関数がアクセスできる Secrets Manager 内の名前セットの名前またはプレフィックス (例: `vertica-*`)。
+ **VerticaConnectionString** — カタログ固有の接続が定義されていない場合にデフォルトで使用される Vertica 接続の詳細。オプションで、文字列は AWS Secrets Manager 構文を使用できます (例: `${secret_name}`)。
+ **VPC ID** — Lambda 関数にアタッチする VPC ID。
#### 接続文字列
次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。
```
vertica://jdbc:vertica://host_name:
port/database?user=vertica-username&password=
vertica-password
```
#### 単一接続ハンドラーの使用
次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の Vertica インスタンスに接続できます。
****
| ハンドラーのタイプ | Class |
| --- | --- |
| 複合ハンドラー | VerticaCompositeHandler |
| メタデータハンドラー | VerticaMetadataHandler |
| レコードハンドラー | VerticaRecordHandler |
#### 単一接続ハンドラーのパラメータ
****
| パラメータ | 説明 |
| --- | --- |
| default | 必須。デフォルトの接続文字列。 |
単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。
#### 認証情報の提供
JDBC 接続文字列の中でデータベースのユーザー名とパスワードを指定するには、接続文字列のプロパティ、もしくは AWS Secrets Manager を使用します。
+ **接続文字列** – ユーザー名とパスワードを、JDBC 接続文字列のプロパティとして指定できます。
**重要**
セキュリティのベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「*AWS Secrets Manager ユーザーガイド*」の「[ハードコードされたシークレットを AWS Secrets Manager に移動する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html)」を参照してください。
+ **AWS Secrets Manager** – Athena フェデレーティッドクエリ機能を AWS Secrets Manager で使用するには、Secrets Manager に接続するための[インターネットアクセス](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/)または [VPC エンドポイント](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html)が、Lambda 関数に接続されている VPC に必要です。
JDBC 接続文字列には、AWS Secrets Manager のシークレットの名前を含めることができます。コネクタは、このシークレット名を Secrets Manager の `username` および `password` の値に置き換えます。
Amazon RDS データベースインスタンスには、このサポートが緊密に統合されています。Amazon RDS を使用している場合は、AWS Secrets Manager と認証情報ローテーションの使用を強くお勧めします。データベースで Amazon RDS を使用していない場合は、認証情報を次の形式で JSON として保存します。
```
{"username": "${username}", "password": "${password}"}
```
**シークレット名を含む接続文字列の例**
次の文字列には、シークレット名 \$1\$1`vertica-username`\$1 および `${vertica-password}` が含まれています。
```
vertica://jdbc:vertica://
host_name:port/database?user=${vertica-username}&password=${vertica-password}
```
次の例のように、コネクタはシークレット名を使用し、シークレットを取得してユーザー名とパスワードを提供します。
```
vertica://jdbc:vertica://
host_name:port/database?user=sample-user&password=sample-password
```
現在、Vertica コネクタは `vertica-username` と `vertica-password` の JDBC プロパティを認識します。
#### スピルパラメータ
Lambda SDK は Amazon S3 にデータをスピルする可能性があります。同一の Lambda 関数によってアクセスされるすべてのデータベースインスタンスは、同じ場所にスピルします。
****
| パラメータ | 説明 |
| --- | --- |
| spill\$1bucket | 必須。スピルバケット名。 |
| spill\$1prefix | 必須。スピルバケットのキープレフィックス |
| spill\$1put\$1request\$1headers | (オプション) スピルに使用される Amazon S3 の putObject リクエスト (例:\$1"x-amz-server-side-encryption" : "AES256"\$1) における、リクエストヘッダーと値に関する JSON でエンコードされたマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「[PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)」を参照してください。 |
## サポートされるデータ型
次の表は、Vertica コネクタ用にサポートされているデータ型です。
****
| ブール値 |
| --- |
| BigInt |
| ショート |
| 整数 |
| Long |
| 浮動小数点数 |
| Double |
| 日付 |
| Varchar |
| バイト |
| BigDecimal |
| Varchar としての TimeStamp |
## パフォーマンス
Lambda 関数は射影プッシュダウンを実行して、クエリがスキャンするデータを減少させます。`LIMIT` 句はスキャンされるデータ量を削減しますが、述語を提供しない場合、`LIMIT` 句を含む `SELECT` クエリは少なくとも 16 MB のデータをスキャンすることを想定する必要があります。Vertica コネクタは、同時実行によるスロットリングに強いです。
## パススルークエリ
Vertica コネクタは、[パススルークエリ](federated-query-passthrough.md)をサポートします。パススルークエリは、テーブル関数を使用して、実行のためにクエリ全体をデータソースにプッシュダウンします。
Vertica でパススルークエリを使用するには、以下の構文を使用できます。
```
SELECT * FROM TABLE(
system.query(
query => 'query string'
))
```
以下のクエリ例は、Vertica 内のデータソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
system.query(
query => 'SELECT * FROM customer LIMIT 10'
))
```
## ライセンス情報
このコネクタを使用することにより、[pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) ファイル内のリストにある、サードパーティのコンポーネントが使用されることを承認し、 GitHub.com にある [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/LICENSE.txt) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。
## その他のリソース
最新の JDBC ドライバーのバージョン情報については、GitHub.com で Vertica コネクタ用の [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-vertica/pom.xml) ファイルを参照してください。
このコネクタの追加情報については、GitHub.com の[対応するサイト](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-vertica)および AWS ビッグデータブログの「[Athena Federated Query SDK を使用して Amazon Athena で Vertica データソースのクエリを実行する](https://aws.amazon.com/blogs/big-data/querying-a-vertica-data-source-in-amazon-athena-using-the-athena-federated-query-sdk/)」を参照してください。
# データソース接続を作成する
Athena データソースコネクタを使用するには、コネクタとデータソースに関する接続情報を保存する AWS Glue 接続を作成します。接続を作成するときは、SQL クエリでデータソースを参照するために使用する名前をデータソースに付けます。
[コンソール](connect-to-a-data-source-console-steps.md)または [CreateDataCatalog API](https://docs.aws.amazon.com/athena/latest/APIReference/API_CreateDataCatalog.html) オペレーションを使用して、Athena でデータソース接続を作成および設定できます。
**Topics**
+ [Athena でデータソースを作成して使用するアクセス許可](connect-to-a-data-source-permissions.md)
+ [Athena コンソールを使用してデータソースに接続する](connect-to-a-data-source-console-steps.md)
+ [AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)
+ [データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)
+ [AWS アカウントに ECR イメージをプルする](pull-ecr-customer-account.md)
+ [接続を Glue データカタログとして登録する](register-connection-as-gdc.md)
+ [クロスアカウントフェデレーテッドクエリを有効にする](xacct-fed-query-enable.md)
+ [データソースコネクタを更新する](connectors-updating.md)
# Athena でデータソースを作成して使用するアクセス許可
データソースを作成して使用するには、次のアクセス許可のセットが必要です。
+ AmazonAthenaFullAccess。これは、Amazon Athena へのフルアクセスと、クエリ、結果の書き込み、データ管理に必要な依存関係へのスコープ付きアクセスを提供します。詳細については、「AWS 管理ポリシーリファレンスガイド」の「[AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html)」を参照してください。
+ CreateDataCatalog API を呼び出すアクセス許可。これらのアクセス許可は、Glue 接続と統合するデータソースを作成する場合にのみ必要です。ポリシー例の詳細については、「[コネクタと Athena カタログの作成に必要なアクセス許可](athena-catalog-access.md)」を参照してください。
+ Lake Formation のきめ細かなアクセスコントロールを使用する場合は、上記のアクセス許可に加えて、次のアクセス許可も必要です。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lakeformation:RegisterResource",
"iam:ListRoles",
"glue:CreateCatalog",
"glue:GetCatalogs",
"glue:GetCatalog"
],
"Resource": "*"
}
]
}
```
------
# Athena コンソールを使用してデータソースに接続する
Athena コンソールを使用して、データソース接続を作成および設定できます。
**データソースへの接続を作成するには**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. **[Data source selection]** (データソースの選択) については、次のガイドラインを考慮して、Athena でクエリを実行するデータソースを選択します。
+ データソースに対応する接続オプションを選択します。Athena には、MySQL、Amazon DocumentDB、PostgreSQL などのソースに設定できる事前構築されたデータソースコネクタがあります。
+ このページで Apache Hive メタストアまたは他のフェデレーションクエリのデータソースオプションを使用していない場合、Amazon S3 内のデータをクエリするには **[S3 - AWS Glue Data Catalog]** を選択します。Athena では、AWS Glue Data Catalog を使用して Amazon S3 にデータソースのメタデータとスキーマ情報を格納します。これはデフォルト (非フェデレーション) のオプションです。詳細については、「[AWS Glue Data Catalog を使用してデータに接続する](data-sources-glue.md)」を参照してください。このワークフローを使用する手順については、「[Athena でデータカタログを登録して使用する](gdc-register.md)」を参照してください。
+ **[S3 - Apache Hive metastore]** (S3 - Apache Hive メタストア) を選択して、Apache Hive メタストアを使用する Amazon S3 内のデータセットをクエリします。このオプションの詳細については、「[Athena を Apache Hive メタストアに接続する](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md)」を参照してください。
+ Athena で使用する独自のデータソースコネクタを作成する場合、[**Custom data source**] (カスタムデータソース) を選択します。データソースコネクタの書き込みについては、「[Athena Query Federation SDK を使用してデータソースコネクタを開発する](connect-data-source-federation-sdk.md)」を参照してください。
1. [**次へ**] を選択します。
1. **[データソース詳細の入力]** ページの **[データソース名]** に、自動生成された名前を使用するか、Athena からデータソースをクエリする際に SQL ステートメントで使用する一意の名前を入力します。名前は最大 127 文字で、アカウント内で一意である必要があります。この設定は、作成後に変更することはできません。有効な文字は、a～z、A～Z、0～9、\$1 (アンダースコア)、@ (at マーク)、および - (ハイフン) です。`awsdatacatalog`、`hive`、`jmx`、および `system` の名前は Athena によって予約されており、データソース名には使用できません。
1. 選択したデータソースが AWS Glue 接続と統合されている場合。
1. **[AWS Glue 接続の詳細]** に、必要な情報を入力します。接続には、特定のデータソースに接続するために必要なプロパティが含まれます。必要なプロパティは、接続タイプによって異なります。コネクタに関連するプロパティの詳細については、「[使用可能なデータソースコネクタ](connectors-available.md)」を参照してください。追加の接続プロパティの詳細については、「*AWS Glue ユーザーガイド*」の「[AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)」を参照してください。
**注記**
Glue 接続プロパティを更新する場合、更新されたプロパティを取得するには Lambda コネクタを再起動する必要があります。これを行うには、環境プロパティを編集し、実際には何も変更せずに保存します。
Glue 接続を更新したときに、対応する Lambda 関数で次のプロパティが自動的に更新されることはありません。これらのプロパティの Lambda 関数を手動で更新する必要があります。
Lambda VPC 設定 – `security_group_ids`、`subnet_ids`
Lambda 実行ロール – `spill_bucket`、`secret_name`、`spill_kms_key_id`
1. **[Lambda 実行 IAM ロール]** で、以下のいずれかを選択します。
+ **新しい実行ロールを作成して使用する** – (デフォルト) Athena は、ユーザーに代わって AWS Lambda のリソースにアクセスするために使用する実行ロールを作成します。Athena では、フェデレーティッドデータソースを作成するためにこのロールが必要です。
+ **既存の実行ロールを使用する** – 既存の実行ロールを選択するには、このオプションを使用します。このオプションでは、**[実行ロール]** ドロップダウンから使用する実行ロールを選択します。
1. 選択したデータソースが AWS Glue 接続と統合されていない場合。
1. **Lambda 関数**を使用する場合、[**Lambda 関数の作成**] を選択します。選択したコネクタの機能ページが AWS Lambda コンソールで開きます。このページには、コネクタに関する詳細情報が表示されます。
1. [**アプリケーションの設定**] で、各アプリケーション設定の説明をよく読み、要件に対応する値を入力します。
表示されるアプリケーション設定は、データソースのコネクタによって異なります。最低限必要な設定は次のとおりです。
+ **AthenaCatalogName** – ターゲットとなるデータソースを示す小文字の Lambda 関数の名前です (例えば、`cloudwatchlogs`)。
+ **[SpillBucket]** – Lambda 関数のレスポンスサイズ制限を超えるデータを保存するための、アカウント内の Simple Storage Service (Amazon S3) バケット。
**注記**
スピルデータは、その後の実行では再利用されることはなく、安全に削除できます。Athena はこれらのデータを削除しません。これらのオブジェクトを管理するには、Simple Storage Service (Amazon S3) スピルバケットから古いデータを削除するオブジェクトライフサイクルポリシーを追加することを検討してください。詳細については、「Amazon S3 ユーザーガイド」の「[ストレージのライフサイクルの管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)」を参照してください。
1. **[I acknowledge that this app creates custom IAM roles and resource policies]** (このアプリがカスタム IAM ロールとリソースポリシーを作成することを承認します) を選択します。詳細については、**[Info]** (情報) リンクを選択してください。
1. **[デプロイ]** を選択します。デプロイが完了すると、Lambda 関数が Lambda コンソールの [**リソース**] セクションに表示されます。
データソースコネクタをアカウントにデプロイしたら、Athena を接続できます。
1. Athena コンソールの [**Connect data sources**] (データソースを接続) ページに戻ります。
1. [**接続の詳細**] セクションで、[**Lambda 関数を選択または入力**] 検索ボックスの横にある更新アイコンを選択します。
1. Lambda コンソールで作成した関数の名前を選択します。Lambda 関数の ARN が表示されます。
1. (オプション) **[Tags]** (タグ) でキーと値のペアを追加して、このデータソースに関連付けます。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**次へ**] を選択します。
1. **[確認と作成]** ページで、データソースの詳細を確認します。変更するには、**[Edit]** (編集) を選択します。
1. **[Athena がアカウントにリソースを作成します]** の情報を読みます。同意する場合は、**[Athena がユーザーに代わってリソースを作成することを承認します]** を選択します。
1. **[データソースを作成]** を選択します。**Athena** がユーザー用に次のリソースを作成します。
+ Lambda 実行 IAM ロール
+ AWS Glue 接続 (データソースが AWS Glue 接続と互換性がある場合のみ）
+ Lambda function
データソースのページの [**データソースの詳細**] セクションには、新しいコネクタに関する情報が表示されます。これで、Athena クエリでコネクタを使用できるようになりました。
データコネクタを使用したクエリについては、「[フェデレーティッドクエリを実行する](running-federated-queries.md)」を参照してください。
# AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする
データソースコネクタをデプロイするには、AWS Glue 接続を使用する代わりに [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/) を使用できます。
**注記**
カスタムコネクタを使用している場合、または古いコネクタを使用する必要がある場合にのみ、SAR を使用することをお勧めします。それ以外の場合は、Athena コンソールを使用することをお勧めします。
AWS Serverless Application Repository を使用すると、使用する対象のコネクタを検索し、コネクタに必要なパラメータを指定した上で、そのコネクタをアカウントにデプロイできます。コネクタのデプロイが完了したら、Athena コンソールを使用して Athena がデータソースを使用できるようにします。
## アカウントへのコネクタのデプロイ
**AWS Serverless Application Repository を使用してデータソースコネクタをアカウントにデプロイするには**
1. AWS マネジメントコンソール にサインインし、**サーバーレスアプリケーションリポジトリ**を開きます。
1. ナビゲーションペインで、[**Available applications**] (利用可能なアプリケーション) を選択します。
1. **[Show apps that create custom roles or resource policies]** (カスタム IAM ロールまたはリソースポリシーを作成するアプリを表示する) オプションを選択します。
1. 検索ボックスに、コネクタの名前を入力します。事前構築された Athena データコネクタのリストについては、「[使用可能なデータソースコネクタ](connectors-available.md)」を参照してください。
1. コネクタの名前を選択します。コネクタを選択すると、Lambda 関数の **[Application details]** (アプリケーションの詳細) ページが AWS Lambda コンソールに表示されます。
1. 詳細ページの右側の **[Application settings]** (アプリケーションの設定) で、必要な情報を入力します。最低限必要な設定は次のとおりです。Athena で構築されるデータコネクタのその他の設定可能なオプションについては、GitHub の「[Available connectors](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)」(使用可能なコネクタ) の対応するトピックを参照してください。
+ **AthenaCatalogName** — ターゲットとなるデータソースを示す小文字の Lambda 関数の名前 (例えば、`cloudwatchlogs`)。
+ **SpillBucket** — アカウント内の Amazon S3 バケットを指定して、Lambda 関数のレスポンスサイズ制限を超える大規模なレスポンスペイロードからデータを受信します。
1. **[I acknowledge that this app creates custom IAM roles and resource policies]** (このアプリがカスタム IAM ロールとリソースポリシーを作成することを承認します) を選択します。詳細については、**[Info]** (情報) リンクを選択してください。
1. **[Application settings]** (アプリケーションの設定) セクションの右下で **[Deploy]** (デプロイ) を選択します。デプロイが完了すると、Lambda 関数が Lambda コンソールの [**リソース**] セクションに表示されます。
## コネクタを Athena で使用できるようにする
Athena コンソールを使用して、データソースコネクタを Athena で使用できるようにします。
**データソースコネクタを Athena で使用できるようにするには**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. **[データソースを選択]** で、AWS Serverless Application Repository でコネクタを作成したデータソースを選択します。このチュートリアルでは、フェデレーションデータソースとして **Amazon CloudWatch Logs** を選択します。
1. [**次へ**] を選択します。
1. [**Data source details**] (データソースの詳細) ページの [**Data source name**] (データソース名) に、Athena からデータソースをクエリする際に SQL ステートメントで使用する名前 (例えば `CloudWatchLogs`) を入力します。名前は最大 127 文字で、アカウント内で一意である必要があります。この設定は、作成後に変更することはできません。有効な文字は、a～z、A～Z、0～9、\$1 (アンダースコア)、@ (at マーク)、および - (ハイフン) です。`awsdatacatalog`、`hive`、`jmx`、および `system` の名前は Athena によって予約されており、データソース名には使用できません。
1. [**接続の詳細**] セクションで、[**Lambda 関数を選択または入力**] ボックスを使って、先ほど作成した関数の名前を選択します。Lambda 関数の ARN が表示されます。
1. (オプション) **[Tags]** (タグ) でキーと値のペアを追加して、このデータソースに関連付けます。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**次へ**] を選択します。
1. [**Review and create**] (確認と作成) ページで、データソースの詳細について確認し、[**Add data source**] (データソースの追加) を選択します。
1. データソースのページの [**データソースの詳細**] セクションには、新しいコネクタに関する情報が表示されます。これで、Athena クエリでコネクタを使用できるようになりました。
データコネクタを使用したクエリについては、「[フェデレーティッドクエリを実行する](running-federated-queries.md)」を参照してください。
# データソースコネクタまたは AWS Glue 接続用の VPC を作成する
一部の Athena データソースコネクタと AWS Glue 接続には VPC とセキュリティグループが必要です。このトピックでは、サブネットと VPC 用のセキュリティグループを持つ VPC を作成する方法について説明します。このプロセスの一環として、作成した VPC、サブネット、およびセキュリティグループの ID を取得します。これらの ID は、AWS Glue 接続またはデータソースコネクタを Athena で使用するように設定するときに必要になります。
**Athena データソースコネクタ用の VPC を作成するには**
1. AWS マネジメントコンソール にサインインして、Amazon VPC コンソール ([https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)) を開きます。
1. **[Create VPC（VPC の作成）]** を選択します。
1. **[VPC の作成]** ページの **[VPC 設定]** の下で、**[作成するリソース]** に、**[VPC など]** を選択します。
1. **[名前タグの自動生成]** の下で、**[自動生成]** に、VPC 内のすべてのリソースの名前タグを生成する際に使用される値を入力します。
1. **[Create VPC（VPC の作成）]** を選択します。
1. プロセスが完了したら、**[VPC を表示]** を選択します。
1. **[Details]** (詳細) セクションの **[VPC ID]** に、後で参照できるように VPC ID をコピーします。
これで、先ほど作成した VPC のサブネット ID を取得する準備が整いました。
**VPC サブネット ID を取得するには**
1. VPC コンソールのナビゲーションペインで、**[Subnets]** (サブネット) を選択します。
1. **[VPC]** 列にメモした VPC ID があるサブネットの名前を選択して指定します。
1. **[Details]** (詳細) セクションの **[Subnet ID]** (サブネット ID) に、後で参照できるようにサブネット ID をコピーします。
次に、VPC 用のセキュリティグループを作成します。
**VPC 用のセキュリティグループを作成するには**
1. VPC コンソールのナビゲーションペインで、**[Security]** (セキュリティ)、**[Security Groups]** (セキュリティグループ) を選択します。
1. **[セキュリティグループの作成]** を選択してください。
1. **[Create security group]** (セキュリティグループの作成) ページで、以下の情報を入力します。
+ **[Security group name]** (セキュリティグループ名) に、セキュリティグループの名前を入力します。
+ **[Description]** (説明) に、セキュリティグループの説明を入力します。説明が必要です。
+ **[VPC]** に、データソースコネクタ用に作成した VPC の VPC ID を選択して指定します。
+ **[Inbound rules]** (インバウンドルール) と **[Outbound rules]** (アウトバウンドルール) で、必要なインバウンドルールとアウトバウンドルールを追加します。
1. **[セキュリティグループの作成]** を選択してください。
1. セキュリティグループの **[Details]** (詳細) ページに、後で参照できるように **[Security group ID]** (セキュリティグループ ID) をコピーします。
## Athena コネクタで VPC を使用する際の重要な考慮事項
すべてのコネクタは VPC を利用できるため、以下の手順はすべての Athena コネクタに適用されます。
**注記**
AWS Glue 接続で VPC を使用する場合は、次の PrivateLink エンドポイントを設定する必要があります。
Amazon S3
AWS Glue
AWS 秘密マネジャー
あるいは、パブリックインターネットアクセスを使用することもできますが、セキュリティ上の理由からお勧めしません。
**警告**
パブリックインターネットアクセスを使用すると、リソースが追加のセキュリティリスクにさらされる可能性があります。VPC 設定のセキュリティを強化するために PrivateLink エンドポイントを使用することを強くお勧めします。
# AWS アカウントに ECR イメージをプルする
Athena フェデレーションコネクタの Lambda 関数は、Athena が管理する Amazon ECR リポジトリに保存されているコンテナイメージを使用します。これらのコンテナイメージに対してセキュリティスキャンを実行するには、まずそれらをアカウントの Amazon ECR リポジトリにコピーする必要があります。このセクションでは、イメージをリポジトリにコピーし、そのイメージを使用するように Lambda 関数を設定する方法について、手順ごとに説明します。
## 前提条件
+ Athena フェデレーションコネクタ – コンテナイメージを使用する限り、任意のソースからコネクタを作成できます。
**注記**
イメージのデプロイを確認するには、Athena フェデレーションコネクタ Lambda の [イメージ] タブをチェックします。
+ Docker のインストールと実行
+ AWS CLI のインストール
+ 適切なプルアクセス許可を持つアカウント認証情報
## イメージの転送方法
1. Athena フェデレーションコネクタ Lambda からイメージ URI を見つけます
**Example**
```
account_id_1.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1
```
1. Athena が管理するアカウントの Docker 認証トークンを生成します。
```
aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin athena-managed-registry
```
コードの説明は以下のとおりです。
+ *regionID* はデプロイリージョンです (例: us-east-1)
+ *athena-managed-registry* はイメージ URI のレジストリ部分になります (例: account\$1id\$11.dkr.ecr.us-east-1.amazonaws.com)
1. Athena が管理するアカウントからイメージをプルします。
```
docker pull athenaImageURI
```
1. レジストリに対して Docker を認証します。
```
aws ecr get-login-password --region regionID | docker login --username AWS --password-stdin customer-registry
```
ここで *customer-registry* は ECR レジストリになります (例: account\$1id\$12.dkr.ecr.us-east-1.amazonaws.com)
1. リポジトリ用にプルしたイメージにタグを付けます。
```
docker tag athenaImageURI yourImageURI
```
1. イメージをリポジトリにプッシュします。
```
docker push yourImageURI
```
1. Athena フェデレーションコネクタを更新します。
1. Lambda 関数に移動する
1. **[新しいイメージをデプロイ]** を選択する
1. 新しいイメージ URI を入力する
Athena フェデレーティッドコネクタイメージがアカウントに配置され、イメージに対して CVE スキャンを実行できるようになりました。
# 接続を Glue データカタログとして登録する
データソースを作成したら、Athena コンソールを使用して接続を Glue データカタログとして登録できます。登録すると、フェデレーティッドデータカタログを管理し、Lake Formation を使用してきめ細かなアクセスコントロールを有効にすることができます。詳細については、「[フェデレーティッドカタログの作成](https://docs.aws.amazon.com/lake-formation/latest/dg/create-fed-catalog-data-source.html)」を参照してください。
次のコネクタを登録して AWS Glue と統合し、きめ細かなアクセスコントロールを行うことができます。
+ Redshift
+ BigQuery
+ DynamoDB (プレビュー）
+ Snowflake (プレビュー）
+ MySQL
+ PostgreSQL
+ AWS CMDB
+ Timestream
+ Azure Data Lake Storage
+ Azure Synapse
+ IBM Db2
+ IBM Db2 AS/400 (Db2 iSeries)
+ DocumentDB
+ Google Cloud Storage
+ HBase
+ OpenSearch
+ Oracle
+ SAP HANA
+ SQL Server
+ TPC-DS
+ Cloudera Hive
+ Cloudwatch
+ Cloudwatch メトリクス
+ Teradata
+ Vertica
## 前提条件
開始する前に、次の前提条件を満たしている必要があります
+ ロケーションの登録に必要なロールとアクセス許可があることを確認します。詳細については、「AWS Lake Formation デベロッパーガイド」の「[ロールの要件](https://docs.aws.amazon.com/lake-formation/latest/dg/registration-role.html)」を参照してください。
+ 必要な Lake Formation ロールがあることを確認します。詳細については、「AWS Lake Formation デベロッパーガイド」の「[データカタログを外部データソースに接続するための前提条件](https://docs.aws.amazon.com/lake-formation/latest/dg/federated-catalog-data-connection.html)」を参照してください。
+ Glue に登録するロールには、次の例に示すアクセス許可が必要です。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix/*",
"arn:aws:s3:::amzn-s3-demo-bucket/spill-prefix"
]
},
{
"Sid": "lambdainvoke",
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-1:111122223333:function:lambda_function_name"
},
{
"Sid": "gluepolicy",
"Effect": "Allow",
"Action": "glue:*",
"Resource": [
"arn:aws:glue:us-east-1:111122223333:connection/",
"arn:aws:glue:us-east-1:111122223333:catalog"
]
}
]
}
```
------
+ 適切なデータアクセスを決定および管理するのはお客様の責任です。フェデレーティッドクエリに対するきめ細かなアクセスコントロールでは、[AmazonAthenaFullAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html) 管理ポリシーを使用することをお勧めします。独自のポリシーを使用する場合は、フェデレーティッドクエリを実行するユーザーが次のリソースにアクセスできないようにする必要があります。
+ Glue 接続で指定された Lambda コネクタの `lambda:InvokeFunction`
+ IAM でのスピルバケットの場所へのアクセス
+ フェデレーティッドカタログに関連付けられた Glue 接続へのアクセス
+ IAM の Lake Formation ロール
## コンソールを使用して接続を登録する
**接続を Glue データカタログとして登録するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソース]** リストから、作成したデータソースを選択して **[データソースの詳細]** ページを開きます。
1. **[AWS Lake Formation の使用を開始する]** を選択します。
**注記**
このオプションを選択したら、Lambda 関数を自分で管理する必要があります。Athena は Lambda 関数を削除しません。
1. **[データカタログ名]** には、カタログの一意の名前を指定します。
1. Lambda 関数を呼び出すアクセス許可を Lake Formation に付与する **[Lake Formation IAM ロール]** を選択します。[例](#register-connection-as-gdc-pre)に示すようなアクセス許可をロールが持っていることを確認します。
1. テキストボックスに「**confirm**」と入力して Athena データソースを削除し、Glue データカタログ登録に置き換えます。
**注記**
このアクションにより、Athena データソースが削除され、代わりに新しい Glue データカタログが作成されます。このプロセスが完了したら、データソースにアクセスするクエリを更新して、代わりに新しく作成された Glue データカタログを参照する必要がある場合があります。
1. **[カタログを作成し Lake Formation に移動]** を選択します。これにより、Lake Formation コンソールが開き、そこでカタログを管理し、カタログ、データベース、テーブルに対するアクセス許可をユーザーに付与できます。
# クロスアカウントフェデレーテッドクエリを有効にする
フェデレーションクエリを使用すると、AWS Lambda にデプロイされたデータソースコネクタを使用して Amazon S3 以外のデータソースをクエリできます。クロスアカウントのフェデレーションクエリ機能を使用すると、Lambda 関数とクエリ対象のデータソースを異なるアカウントに配置できます。
**注記**
この方法は、フェデレーティッドデータソースを AWS Glue Data Catalog に登録していない場合にのみ使用します。データソースを AWS Glue Data Catalog に登録している場合は、AWS Glue Data Catalog クロスアカウント機能とアクセス許可モデルを使用します。詳細については、「*AWS Glue ユーザーガイド*」の「[クロスアカウントアクセス許可の付与](https://docs.aws.amazon.com/glue/latest/dg/cross-account-access.html)」を参照してください。
データ管理者は、データコネクタをデータアナリストのアカウントと共有することでクロスアカウントの串刺検索を有効化できます。また、データアナリストは、データ管理者から共有された Lambda ARN を使用してアカウントに追加することでクロスアカウントの串刺検索を有効化できます。元のアカウントのコネクタの設定を変更すると、更新された設定は自動的に他のユーザーのアカウントのコネクタの共有インスタンスに適用されます。
## 考慮事項と制限事項
+ クロスアカウントのフェデレーションクエリ機能は、Lambda ベースのデータソースを使用する Hive 以外のメタストアデータのコネクタで使用できます。
+ AWS Glue Data Catalog データソース型では、この機能は使用できません。AWS Glue Data Catalog へのクロスアカウントアクセスの詳細については、「[AWS Glue データカタログへのクロスアカウントアクセスを構成する](security-iam-cross-account-glue-catalog-access.md)」を参照してください。
+ コネクタの Lambda 関数からの応答が Lambda 応答サイズの制限である 6 MB を超えると、Athena は自動的に応答を暗号化してバッチ処理し、設定した Amazon S3 バケットに流出します。Athena が流出したデータを読み取るには、Athena クエリを実行するエンティティが流出場所にアクセスできる必要があります。クエリが完了するとデータが不要になるため、流出場所からオブジェクトを削除するように Amazon S3 ライフサイクルポリシーを設定することをお勧めします。
+ AWS リージョン をまたいだフェデレーションクエリの使用はサポートされていません。
## 必要なアクセス許可
必要なアクセス許可を設定するには、アカウント A (*444455556666*) とアカウント B (*111122223333*) の両方でアクションを実行する必要があります。
### アカウント A のアクション
データ管理者のアカウント A がデータアナリストのアカウント B と Lambda 関数を共有するには、アカウント B に Lambda の呼び出し関数と流出バケットのアクセスが必要です。したがって、アカウント A では、Lambda 関数への[リソースベースのポリシー](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)と Amazon S3 内の流出バケットへの[プリンシパル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html)アクセスを追加する必要があります。
1. 次のポリシーは、アカウント A の Lambda 関数で Lambda の呼び出し関数のアクセス許可をアカウント B に付与します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "CrossAccountInvocationStatement",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:user/username"
]
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-1:444455556666:function:lambda-function-name"
}
]
}
```
------
1. 次のポリシーは、アカウント B のプリンシパルに流出バケットへのアクセスを許可します。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": ["arn:aws:iam::111122223333:user/username"]
},
"Action": [
"s3:GetObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::spill-bucket",
"arn:aws:s3:::spill-bucket/*"
]
}
]
}
```
------
1. Lambda 関数がフェデレーション SDK によって提供されるデフォルトの暗号化ではなく、AWS KMS キーを使用して流出バケットを暗号化している場合、次の例のようにアカウント A の AWS KMS キーポリシーで、アカウント B のユーザーにアクセス許可を付与する必要があります。
```
{
"Sid": "Allow use of the key",
"Effect": "Allow",
"Principal":
{
"AWS": ["arn:aws:iam::account-B-id:user/username"]
},
"Action": [ "kms:Decrypt" ],
"Resource": "*" // Resource policy that gets placed on the KMS key.
}
```
### アカウント B のアクション
アカウント A のコネクタをアカウント B と共有するには、AWS Security Token Service の [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) API アクションを呼び出すことでアカウント A が引き受ける `AthenaCrossAccountCreate-account-A-id` というロールをアカウント B で作成する必要があります。
1. IAM コンソールまたは AWS CLI を使用して、カスタム信頼ポリシーロールとして `AthenaCrossAccountCreate-account-A-id` ロールを作成します。カスタムの信頼ポリシーを使用すると、アクセスを委任し、他のユーザーに自分の AWS アカウントでのアクションの実行を許可できます。詳細については、「*IAM ユーザーガイド*」の「[カスタム信頼ポリシーを使用してロールを作成する](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-custom.html)」を参照してください。
信頼関係には、次の例のように、キーが `AWS` で、値がアカウント A の ARN であるプリンシパルオブジェクトが必要です。
```
...
"Principal":
{
"AWS": ["arn:aws:iam::account-A-id:user/username"]
},
...
```
1. また、アカウント B で、`CreateDataCatalog` アクションを許可する次のようなポリシーを作成します。
```
{
"Effect": "Allow",
"Action": "athena:CreateDataCatalog",
"Resource": "arn:aws:athena:*:account-B-id:datacatalog/*"
}
```
1. アカウント B を使用して作成した `AthenaCrossAccountCreate-account-A-id` ロールに `CreateDataCatalog` アクションを許可するポリシーを追加します。
## アカウント A のデータソースをアカウント B と共有する
アクセス許可を設定すると、Athena コンソールの **[データソースとカタログ]** ページで、アカウント (アカウント A) のデータコネクタを別のアカウント (アカウント B) と共有できます。アカウント A は、コネクタの完全な制御と所有権を保持しています。アカウント A がコネクタの設定を変更すると、更新された設定がアカウント B の共有されたコネクタに適用されます。
**注記**
Lambda タイプのデータソースのみを共有でき、AWS Glue 接続を使用するデータソースは共有できません。詳細については、「[使用可能なデータソースコネクタ](connectors-available.md)」を参照してください。
**アカウント A の Lambda データソースをアカウント B と共有するには**
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. **[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで、共有するコネクタのリンクを選択します。
1. Lambda データソースの詳細ページで、右上隅の **[Actions]** (アクション) メニューから **[Share]** (共有) オプションを選択します。
1. **[Share *Lambda-name* with another account?]** (別のアカウントと Lambda-name を共有) ダイアログボックスで、必要な情報を入力します。
+ **[Data source name]** (データソース名) については、コピーしたデータソースの名前を他のアカウントで表示したいとおりに入力します。
+ **[Account ID]** (アカウント ID) については、データソースを共有するアカウントの ID を入力します (この場合、アカウント B)。
1. [**共有**] を選択します。指定した共有のデータコネクタが、アカウント B で作成されます。アカウント A のコネクタに対する設定の変更は、アカウント B のコネクタに適用されます。
## アカウント A からアカウント B への共有データソースの追加
データアナリストとして、データ管理者からアカウントに追加するコネクタの ARN が与えられる場合があります。Athena コンソールの **[データソースとカタログ]** ページを使用して、管理者から提供された Lambda ARN をアカウントに追加できます。
**共有されたデータコネクタの Lambda ARN をアカウントに追加するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. ナビゲーションペインが表示されない場合は、左側の展開メニューをクリックします。
1. **[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. **[Choose a data source]** (データソースの選択) ページで、**[Custom or shared connector]** (カスタムまたは共有されたコネクタ) を選択します。
1. [**次へ**] を選択します。
1. **[Enter data source details]** (データソースの詳細を入力) ページの **[Connection details]** (接続の詳細) セクションで、**[Select or enter a Lambda function]** (Lambda 関数を選択または入力) については、アカウント A の Lambda ARN を入力します。
1. [**次へ**] を選択します。
1. **[Review and create]** (確認して作成) ページで、**[Create data source]** (データソースを作成) を選択します。
## トラブルシューティング
アカウント A にアカウント B のロールを引き受けるアクセス許可がないというエラーメッセージが表示された場合は、アカウント B で作成されたロールの名前のスペルが正しいこと、適切なポリシーがアタッチされていることを確認してください。
# データソースコネクタを更新する
最新バージョンを使用して新機能と機能強化を利用するために、Athena ではデータソースコネクタを定期的に更新することを推奨しています。データソースコネクタの更新には、次のステップが含まれます。
# Glue 接続 (推奨)
## 最新バージョンの Athena Query Federation を確認する
Athena データソースコネクタの最新バージョン番号は、最新の Athena Query Federation バージョンに対応しています。特定のケースでは、GitHub のリリースが AWS Serverless Application Repository (SAR) で入手可能なリリースよりも少し新しい可能性があります。
**最新の Athena Query Federation バージョン番号を確認するには**
1. GitHub URL ([https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)) を確認してください。
1. メインページの見出し次の形式のようになっており、そこからリリース番号を書き留めます。
**Release v** *年*.*年の X 週目*.*週の周期* **of Athena Query Federation **
例えば、**Release v2023.8.3 of Athena Query Federation** のリリース番号は 2023.8.3 です。
## コネクタバージョンの検索
現在使用しているコネクタのバージョンを確認するには、次の手順に従います。
**コネクタバージョンを検索するには**
1. Lambda アプリケーションの Lambda コンソールページで、**[イメージ]** タブを選択します。
1. [イメージ] タブで、イメージ URI を見つけます。URI は次の形式に従います。
```
Image_location_account.dkr.ecr.us-west-2.amazonaws.com/athena-federation-repository:Version
```
1. イメージ URI のバージョン番号は、形式 `year.week_of_year.iteration_of_week` (例: `2021.42.1`) に従います。この数値はコネクタバージョンを表しています。
## 新しいコネクタバージョンのデプロイ
新しいバージョンのコネクタをデプロイするには、次のステップに従います。
**新しいコネクタバージョンをデプロイするには**
1. 最新バージョンの Athena Query Federation を確認する手順に従って、必要なバージョンを検索します。
1. フェデレーティッドコネクタの Lambda 関数で、Image URI を見つけ、タグを希望のバージョンに更新します。例えば、次のようになります。
変更前:
```
509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.15.1
```
変更後:
```
509399631660.dkr.ecr.us-east-1.amazonaws.com/athena-federation-repository:2025.26.1
```
**注記**
現在のバージョンが 2025.15.1 より古い場合は、次の重要な変更点に注意してください。
リポジトリ名が `athena-federation-repository` に更新されました
この更新より前のバージョンでは、コマンドオーバーライドが設定されていない可能性があります。複合ハンドラーに設定する必要があります。
# レガシー接続
## 最新バージョンの Athena Query Federation を確認する
Athena データソースコネクタの最新バージョン番号は、最新の Athena Query Federation バージョンに対応しています。特定のケースでは、GitHub のリリースが AWS Serverless Application Repository (SAR) で入手可能なリリースよりも少し新しい可能性があります。
**最新の Athena Query Federation バージョン番号を確認するには**
1. GitHub URL ([https://github.com/awslabs/aws-athena-query-federation/releases/latest](https://github.com/awslabs/aws-athena-query-federation/releases/latest)) を確認してください。
1. メインページの見出し次の形式のようになっており、そこからリリース番号を書き留めます。
**Release v** *年*.*年の X 週目*.*週の周期* **of Athena Query Federation **
例えば、**Release v2023.8.3 of Athena Query Federation** のリリース番号は 2023.8.3 です。
## リソース名を検索して書き留める
アップグレードの準備として、次の情報を確認して書き留めておく必要があります:
1. コネクタの Lambda 関数名。
1. Lambda 関数の環境変数。
1. コネクタの Lambda 関数を管理する Lambda アプリケーション名。
**Athena コンソールからリソース名を検索するには**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソース名]** 列で、コネクタのデータソースへのリンクを選択します。
1. **[データソースの詳細]** セクションの **[Lambda 関数]** で、Lambda 関数へのリンクを選択します。
![\[Lambda 関数へのリンクを選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-updating-1.png)
1. **[関数]** ページの **[関数名]** 列で、コネクタの関数名を見つけて書き留めます。
![\[関数名を書き留めます。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-updating-2.png)
1. 関数名のリンクを選択します。
1. **[関数の概要]** セクションで、**[構成]** タブを選択します。
1. 左側のペインで、**[環境変数]** をクリックします。
1. 「**環境変数**」セクションで、キーとそれに対応する値を見つけて書き留めます。
1. ページの上部までスクロールします。
1. メッセージ **[この関数はアプリケーションに属しています。] [管理するにはここをクリックししてください]** が表示されたら、**[ここをクリック]** リンクを選択してください。
1. 「**serverlessrepo-*your\$1application\$1name***」ページで、**serverlessrepo** を除いたアプリケーション名を見つけて書き留めてください。例えば、アプリケーション名が **serverlessrepo-DynamoDbTestApp** の場合、アプリケーション名は **DynamoDbTestApp** です。
1. アプリケーションの Lambda コンソールページを開いたままにして、**[使用しているコネクタのバージョンを確認]** のステップに進んでください。
## 使用しているコネクタのバージョンを確認する
使用しているコネクタのバージョンを確認するには、次のステップに従います。
**使用しているコネクタのバージョンを確認するには**
1. Lambda アプリケーションの Lambda コンソールページで、**[デプロイ]** タブを選択します。
1. **[デプロイ]** タブで、**[SAM テンプレート]** を展開します。
1. **CodeUri** を検索します。
1. **CodeUri** 下にある**[キー]** フィールドで、次の文字列を探します:
```
applications-connector_name-versions-year.week_of_year.iteration_of_week/hash_number
```
次の例は、CloudWatch コネクタの文字列を示しています:
```
applications-AthenaCloudwatchConnector-versions-2021.42.1/15151159...
```
1. *年*.*年内の第 X 週*.*週内のイテレーション値*の値を記録します (例えば、**2021.42.1**)。これはお使いのコネクタのバージョンです。
## 新しいバージョンのコネクタをデプロイする
新しいバージョンのコネクタをデプロイするには、次のステップに従います。
**新しいバージョンのコネクタをデプロイするには**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. アップグレードするデータソースを選択し、**[次へ]** を選択します。
1. **[接続の詳細]** セクションで、**[Lambda 関数の作成]** を選択します。これにより、更新したアプリケーションをデプロイできる Lambda コンソールが開きます。
![\[AWS Lambda コンソールのコネクタページ。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-updating-3.png)
1. 実際には新しいデータソースを作成していないため、[Athena コンソール] タブを閉じてかまいません。
1. コネクタの Lambda コンソールページで、次のステップを実行します:
1. アプリケーション名から **serverlessrepo-** プレフィックスを削除したことを確認し、アプリケーション名を **[アプリケーション名]** フィールドにコピーします。
1. Lambda 関数名を **[Athena カタログ名]** フィールドにコピーします。一部のコネクタでは、このフィールドを **[Lambda 関数名]** と呼んでいます。
1. 記録した環境変数を対応するフィールドにコピーします。
1. **[このアプリがカスタム IAM ロールとリソースポリシーを作成することを承認します]** を選択した後、**[デプロイ]** を選択します。
1. アプリケーションが更新されたことを確認するには、**[デプロイ]** タブを選択します。
**[デプロイ履歴]** セクションには、更新が完了したことが表示されます。
![\[これでコネクタの更新が完了しました。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connectors-updating-4.png)
1. 新しいバージョン番号を確認するには、以前と同様に **[SAM テンプレート]** を展開して **CodeUri** を検索し、コネクタのバージョン番号を **[キー]** フィールドで確認します。
これで、更新したコネクタを使用して Athena フェデレーティッドクエリを作成できるようになりました。
# データソース接続を編集または削除する
Athena コンソールを使用して、既存の接続の説明、ホスト、ポート、データベース、およびその他のプロパティを更新できます。Athena コンソールからデータソースを削除することもできます。
## データソース接続を編集する
**データソース接続を編集するには**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで、編集するデータソース接続を選択します。
1. **[AWS Glue 接続の詳細]** で、**[編集]** を選択します。
1. [**次へ**] を選択します。
1. **[ の編集]** ページで、必要に応じて情報を更新します。使用可能なプロパティは、接続タイプによって異なります。
**注記**
シークレット、スピルの場所、または AWS KMS キー ID の接続プロパティを更新するときは、Lambda 実行ロールが更新されたリソースに引き続きアクセスできることを確認します。詳細については、「AWS Lambda デベロッパーガイド」の「[実行ロールでのアクセス許可の表示と更新](https://docs.aws.amazon.com/lambda/latest/dg/permissions-executionrole-update.html)」を参照してください。
+ **説明** – 接続の説明を編集します。
+ **ホスト** – データベースのホスト名を編集します。
+ **ポート** – データベースのポート番号を編集します。
+ **データベース** – データベースの名前を編集します。
+ **JDBC パラメータ** – 接続に必要な追加の JDBC パラメータがあれば編集します。
+ **シークレット** – AWS Secrets Manager からシークレットを選択または作成します。AWS シークレットを使用して、JDBC 接続文字列に機密情報がハードコーディングされないようにします。詳細については、「[What is AWS Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)」を参照してください。Secrets Manager でのシークレットの作成については、「*AWS Secrets Manager ユーザーガイド*」の「[AWS Secrets Manager シークレットを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)」を参照してください。
Athena フェデレーティッドクエリで AWS Secrets Manager を使用するには、Secrets Manager に Amazon VPC プライベートエンドポイントを設定する必要があります。詳細については、「*AWS Secrets Manager ユーザーガイド*」の「[Secrets Manager VPC プライベートエンドポイントを作成する](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html#vpc-endpoint-create)」を参照してください。
+ **Amazon S3 のスピルの場所** – アカウントで Amazon S3 バケットの場所を選択または作成して、Lambda 関数のレスポンスサイズ制限を超えるデータを保存します。
**注記**
スピルしたデータは、その後の実行では再利用されることはなく、12 時間後には安全に削除できます。Athena はこれらのデータを削除しません。これらのオブジェクトを管理するには、Simple Storage Service (Amazon S3) スピルバケットから古いデータを削除するオブジェクトライフサイクルポリシーを追加することを検討してください。詳細については、*Amazon S3 ユーザーガイド*の「[ストレージのライフサイクルの管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)」をご参照ください。
+ **S3 でのクエリ結果の暗号化** – 次のいずれかを選択します。
+ (デフォルト) **ランダムに生成されたキーを使用する** – Amazon S3 にスピルされるデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。
+ **AWS KMS キーを使用する** – AWS KMS で生成されたより強力な暗号化キーを選択または作成します。詳細については、「*AWS Key Management Service デベロッパーガイド*」の「[キーの作成](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)」を参照してください。
+ **オフにする** – スピルデータを暗号化しません。
+ **ネットワーク設定** – 一部の接続には仮想プライベートクラウド (VPC) が必要です。アクセスするデータストアがあり、サブネットと 1 つまたは複数のセキュリティグループを持つ VPC を選択または作成します。詳細については、「[データソースコネクタまたは AWS Glue 接続用の VPC を作成する](athena-connectors-vpc-creation.md)」を参照してください。
**注記**
シークレット、スピルの場所、AWS KMS キー ID などのリソースの接続プロパティを更新した後、Lambda 実行ロールが更新されたリソースに引き続きアクセスできることを確認します。
接続のネットワーク設定を更新したら、Lambda 関数を同じ設定で更新して、接続がデータソースと互換性があるようにします。
その他の接続プロパティの詳細については、「*AWS Glue ユーザーガイド*」の「[AWS Glue 接続プロパティ](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html)」または「*Amazon Athena ユーザーガイド*」の「[使用可能なデータソースコネクタ](connectors-available.md)」を参照してください。
1. **[保存]** を選択します。
データソースのページの **[AWS Glue 接続の詳細]** セクションには、コネクタの更新情報が表示されます。
## データソースの削除
データソースを削除しても、Athena データソースのみが削除され、Glue 接続、IAM 実行ロール、Lambda 関数などのリソースは削除されません。
**データソースを削除するには**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで、削除するデータソースを選択します。
1. **[削除]** を選択します。
1. **[データソースの削除]** ページで、「*confirm*」と入力して削除の確認を行い、**[削除]** を選択します。データソースの削除が完了するまでに時間がかかる場合があります。データソースが削除されると、成功アラートが表示されます。
# フェデレーティッドクエリを実行する
1 つ、または複数のデータコネクタを設定してアカウントにデプロイしたら、それらを Athena クエリで使用できます。
## 単一データソースをクエリする
このセクションの例では、[Amazon Athena CloudWatch コネクタ](connectors-cloudwatch.md) が構成され、アカウントにデプロイされていることを前提としています。他のコネクタを使用する場合も、同じ方法でクエリを実行します。
**CloudWatch コネクタを使用する Athena クエリを作成する**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. Athena クエリエディタで、`FROM` 句に次の構文を使用する SQL クエリを作成します。
```
MyCloudwatchCatalog.database_name.table_name
```
### 例
以下の例では、`/var/ecommerce-engine/order-processor` CloudWatch Logs [ロググループ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html)の `all_log_streams` ビューへの接続に Athena CloudWatch コネクタを使用します。`all_log_streams` ビューは、ロググループ内のすべてのログストリームのビューです。このクエリ例では、返される行数を 100 に制限します。
```
SELECT *
FROM "MyCloudwatchCatalog"."/var/ecommerce-engine/order-processor".all_log_streams
LIMIT 100;
```
次の例では、前の例と同じビューの情報を解析します。この例では、注文 ID とログレベルを抽出し、レベル `INFO` のメッセージをフィルタリングします。
```
SELECT
log_stream as ec2_instance,
Regexp_extract(message '.*orderId=(\d+) .*', 1) AS orderId,
message AS order_processor_log,
Regexp_extract(message, '(.*):.*', 1) AS log_level
FROM MyCloudwatchCatalog."/var/ecommerce-engine/order-processor".all_log_streams
WHERE Regexp_extract(message, '(.*):.*', 1) != 'INFO'
```
## 複数のデータソースをクエリする
さらに複雑な例として、次のデータソースを使用して顧客の購入に関するデータを保存する電子商取引会社があると考えてみましょう。
+ 製品カタログデータを保存ための [Amazon RDS for MySQL](https://aws.amazon.com/rds/mysql/)
+ E メールアドレスや配送先住所などの顧客アカウントデータを保存するための [Amazon DocumentDB](https://aws.amazon.com/documentdb/)
+ 注文の発送と追跡データを保存するための [Amazon DynamoDB](https://aws.amazon.com/dynamodb/)
この電子商取引アプリケーションのデータアナリストが、一部の地域で地域の気象条件により配送時間に影響が出ていることを知ったとしましょう。アナリストは、遅延している注文の数や、影響を受けている顧客のいる場所、最も影響を受けている製品を知りたいと考えます。情報のソースを個別に調査することはせずに、アナリストは Athena を使用して、データを 1 つのフェデレーションクエリに結合します。
**Example**
```
SELECT
t2.product_name AS product,
t2.product_category AS category,
t3.customer_region AS region,
count(t1.order_id) AS impacted_orders
FROM my_dynamodb.default.orders t1
JOIN my_mysql.products.catalog t2 ON t1.product_id = t2.product_id
JOIN my_documentdb.default.customers t3 ON t1.customer_id = t3.customer_id
WHERE
t1.order_status = 'PENDING'
AND t1.order_date between '2022-01-01' AND '2022-01-05'
GROUP BY 1, 2, 3
ORDER BY 4 DESC
```
## フェデレーテッドビューをクエリする
フェデレーションされたソースをクエリする場合、ビューを使用して基になるデータソースを難読化したり、データにクエリする他のアナリストに複雑な結合が表示されないようにすることができます。
### 考慮事項と制限事項
+ フェデレーションされたビューには Athena バージョン 3 が必要です。
+ フェデレーションされたビューは、基になるデータソースではなく、AWS Glue に格納されます。
+ フェデレーティッドビューは、[Glue データカタログとして登録](register-connection-as-gdc.md)されているデータソースではサポートされていません。
+ フェデレーションされたカタログで作成されたビューでは、次の例にあるように、完全に修飾されている名前構文を使用する必要があります。
```
"ddbcatalog"."default"."customers"
```
+ フェデレーションされたソースでクエリを実行するユーザーには、フェデレーションされたソースをクエリする権限が必要です。
+ フェデレーションされたビューには `athena:GetDataCatalog` 権限が必要です。詳細については、「[Athena Federated Query へのアクセスを許可する: ポリシーの例](federated-query-iam-access.md)」を参照してください。
### 例
次の例では、フェデレーションされたデータソースに保存されているデータに基づいて、`customers` と呼ばれるビューを作成しています。
**Example**
```
CREATE VIEW customers AS
SELECT *
FROM my_federated_source.default.table
```
次のクエリ例は、基になるフェデレーションされたデータソースではなく、`customers` ビューを参照するクエリを示しています。
**Example**
```
SELECT id, SUM(order_amount)
FROM customers
GROUP by 1
ORDER by 2 DESC
LIMIT 50
```
次の例では、フェデレーションされたデータソースからのデータと Amazon S3 データソースからのデータを組み合わせた、`order_summary` と呼ばれるビューを作成しています。Athena ですでに作成済みのフェデレーションされたソースからは、ビューは `person` および `profile` テーブルを使用します。Amazon S3 からのデータでは、ビューは `purchase` および `payment` テーブルを使用します。Amazon S3 を参照する場合、ステートメントではキーワード `awsdatacatalog` を使用します。フェデレーションされたデータソースは完全に修飾された名前構文である *federated\$1source\$1name*.*federated\$1source\$1database*.*federated\$1source\$1table* を使用していることに注目してください。
**Example**
```
CREATE VIEW default.order_summary AS
SELECT *
FROM federated_source_name.federated_source_database."person" p
JOIN federated_source_name.federated_source_database."profile" pr ON pr.id = p.id
JOIN awsdatacatalog.default.purchase i ON p.id = i.id
JOIN awsdatacatalog.default.payment pay ON pay.id = p.id
```
### その他のリソース
+ 元のソースから分離され、マルチユーザーモデルでのオンデマンドの分析に使用できるフェデレーティッドビューの例については、*AWS Big Data Blog* の「[Extend your data mesh with Amazon Athena and federated views](https://aws.amazon.com/blogs/big-data/extend-your-data-mesh-with-amazon-athena-and-federated-views/)」を参照してください。
+ Athena のビューを使用するための詳細については、「[ビューを使用する](views.md)」を参照してください。
# フェデレーテッドパススルークエリを使用する
Athena では、データソース自体のクエリ言語を使用してフェデレーテッドデータソースに対するクエリを実行したり、実行のためにクエリ全体をデータソースにプッシュダウンしたりすることができます。これらのクエリはパススルークエリと呼ばれます。パススルークエリを実行するには、Athena クエリでテーブル関数を使用します。データソースで実行するパススルークエリは、テーブル関数に対する引数の 1 つに含めます。パススルークエリは、Athena SQL を使用して分析できるテーブルを返します。
## サポートされるコネクタ
以下の Athena データソースコネクタがパススルークエリをサポートしています。
+ [Azure Data Lake Storage](connectors-adls-gen2.md)
+ [Azure Synapse](connectors-azure-synapse.md)
+ [Cloudera Hive](connectors-cloudera-hive.md)
+ [Cloudera Impala](connectors-cloudera-impala.md)
+ [CloudWatch](connectors-cloudwatch.md)
+ [Db2](connectors-ibm-db2.md)
+ [Db2 iSeries](connectors-ibm-db2-as400.md)
+ [DocumentDB](connectors-docdb.md)
+ [DynamoDB](connectors-dynamodb.md)
+ [HBase](connectors-hbase.md)
+ [Google BigQuery](connectors-bigquery.md)
+ [Hortonworks](connectors-hortonworks.md)
+ [MySQL](connectors-mysql.md)
+ [Neptune](connectors-neptune.md)
+ [OpenSearch](connectors-opensearch.md)
+ [Oracle](connectors-oracle.md)
+ [PostgreSQL](connectors-postgresql.md)
+ [Redshift](connectors-redshift.md)
+ [SAP HANA](connectors-sap-hana.md)
+ [Snowflake](connectors-snowflake.md)
+ [SQL Server](connectors-microsoft-sql-server.md)
+ [Teradata](connectors-teradata.md)
+ [Timestream](connectors-timestream.md)
+ [Vertica](connectors-vertica.md)
## 考慮事項と制限事項
Athena でパススルークエリを使用するときは、以下の点を考慮してください。
+ クエリパススルーがサポートされるのは、Athena `SELECT` ステートメントまたは読み取り操作のみです。
+ クエリのパフォーマンスは、データソースの設定に応じて異なる場合があります。
+ クエリパススルーは、Lake Formation のきめ細かなアクセスコントロールをサポートしていません。
+ パススルークエリは、[Glue データカタログとして登録](register-connection-as-gdc.md)されているデータソースではサポートされていません。
## 構文
以下は、一般的な Athena クエリパススルー構文です。
```
SELECT * FROM TABLE(catalog.system.function_name(arg1 => 'arg1Value'[, arg2 => 'arg2Value', ...]))
```
次の点に注意してください。
+ **catalog** – ターゲット Athena フェデレーションコネクタ名またはデータカタログ名。
+ **system** – 関数を含む名前空間。すべての Athena コネクタ実装で、この名前空間が使用されます。
+ **function\$1name** – パススルークエリをデータソースにプッシュダウンする関数の名前。これはよく `query` と呼ばれます。組み合わせ `catalog.system.function_name` は、関数の完全解決パスです。
+ **arg1、arg2 など** – 関数の引数。ユーザーはこれらの引数を関数に渡す必要があります。ほとんどの場合、これはデータソースに渡されるクエリ文字列です。
ほとんどのデータソースでは、`query` が最初で唯一の引数であり、その後にアロー演算子 `=>` とクエリ文字列が続きます。
```
SELECT * FROM TABLE(catalog.system.query(query => 'query string'))
```
オプションの名前付き引数 `query` とアロー演算子 `=>` は、簡素化のために省略することが可能です。
```
SELECT * FROM TABLE(catalog.system.query('query string'))
```
クエリがターゲットカタログのコンテキスト内で実行されている場合、`catalog` 名を削除することでクエリをさらに簡素化できます。
```
SELECT * FROM TABLE(system.query('query string'))
```
データソースがクエリ文字列以上のものを必要とする場合は、データソースが期待する順序で名前付き引数を使用してください。たとえば、`arg1 => 'arg1Value'` 式には最初の引数とその値が含まれます。*arg1* という名前はデータソースに固有のもので、コネクタによって異なる場合があります。
```
SELECT * FROM TABLE(
system.query(
arg1 => 'arg1Value',
arg2 => 'arg2Value',
arg3 => 'arg3Value'
));
```
引数名を省略することで、上記を簡素化することもできます。ただし、メソッドの署名の順序に従う必要があります。関数の署名の詳細については、各コネクタのドキュメントを参照してください。
```
SELECT * FROM TABLE(catalog.system.query('arg1Value', 'arg2Value', 'arg3Value'))
```
次の例のように、完全な関数解決パスを利用することで、異なる Athena コネクタ間で複数のパススルークエリを実行できます。
```
SELECT c_customer_sk
FROM TABLE (postgresql.system.query('select * from customer limit 10'))
UNION
SELECT c_customer_sk
FROM TABLE(dynamodb.system.query('select * from customer')) LIMIT 10
```
パススルークエリは、フェデレーションビューの一部として使用できます。同じ制限が適用されます。詳細については、「[フェデレーテッドビューをクエリする](https://docs.aws.amazon.com/athena/latest/ug/running-federated-queries.html#running-federated-queries-federated-views)」を参照してください。
```
CREATE VIEW catalog.database.ViewName AS
SELECT * FROM TABLE (
catalog.system.query('query')
)
```
特定のコネクタで使用する正確な構文については、個々のコネクタのドキュメントを参照してください。
### 引用符の使用
引数値 (渡すクエリ文字列を含む) は、以下の例にあるように、一重引用符で囲む必要があります。
```
SELECT * FROM TABLE(system.query(query => 'SELECT * FROM testdb.persons LIMIT 10'))
```
クエリ文字列が二重引用符で囲まれていると、クエリは失敗します。以下のクエリは、COLUMN\$1NOT\$1FOUND: line 1:43: Column 'select \$1 from testdb.persons limit 10' cannot be resolved というエラーメッセージで失敗します。
```
SELECT * FROM TABLE(system.query(query => "SELECT * FROM testdb.persons LIMIT 10"))
```
一重引用符をエスケープするには、元の引用符に一重引用符を追加します (`terry's_group` を `terry''s_group` にするなど)。
## 例
以下のクエリ例は、データソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。
```
SELECT * FROM TABLE(
catalog.system.query(
query => 'SELECT * FROM customer LIMIT 10;'
))
```
以下のステートメントは同じクエリを実行しますが、オプションの名前付き引数 `query` とアロー演算子 `=>` を削除します。
```
SELECT * FROM TABLE(
catalog.system.query(
'SELECT * FROM customer LIMIT 10;'
))
```
これは、再利用しやすいようにフェデレーションビュー内にカプセル化することもできます。ビューで使用する場合は、完全な関数解決パスを使用する必要があります。
```
CREATE VIEW AwsDataCatalog.default.example_view AS
SELECT * FROM TABLE (
catalog.system.query('SELECT * FROM customer LIMIT 10;')
)
```
## クエリパススルーのオプトアウト
パススルークエリを無効にするには、`enable_query_passthrough` という名前の Lambda 環境変数を追加し、`false` に設定します。
# フェデレーテッドテーブル名修飾子を理解する
Athena はデータオブジェクトの階層を指すのに次の用語を使います。
+ **データソース** — データベースのグループ
+ **データベース** — テーブルのグループ
+ **テーブル** — 行または列のグループとして整理されたデータ
これらのオブジェクトは、次のように代替だが同等の名前で呼ばれることもあります。
+ データソースはカタログと呼ばれることもあります。
+ データベースはスキーマと呼ばれることもあります。
## フェデレーションデータソースの用語
フェデレーションデータソースをクエリする場合、基になるデータソースが Athena と同じ用語を使用していない可能性があることに注意してください。フェデレーションクエリを作成する場合、この区別を念頭に置いてください。以下のセクションでは、Athena のデータオブジェクト用語がフェデレーションデータソースのデータオブジェクト用語とどのように対応するかを説明します。
### Amazon Redshift
Amazon Redshift データベースは、Redshift テーブルのグループを含む Redshift スキーマのグループです。
****
| Athena | Redshift |
| --- | --- |
| 共有データソース | Redshift コネクタの Lambda 関数は、Redshift database を指すように設定されています。 |
| data\$1source.database.table | database.schema.table |
クエリの例
```
SELECT * FROM
Athena_Redshift_connector_data_source.Redshift_schema_name.Redshift_table_name
```
このコネクタの詳細については、「[Amazon Athena Redshift コネクタ](connectors-redshift.md)」を参照してください。
### Cloudera Hive
Cloudera Hive サーバーまたはクラスターは、Cloudera Hive テーブルのグループを含む Cloudera Hive データベースのグループです。
****
| Athena | [Hive] |
| --- | --- |
| Cloudera Hive データソース | Cloudera Hive コネクタの Lambda 関数は Cloudera Hive server を指すように設定されています。 |
| data\$1source.database.table | server.database.table |
クエリの例
```
SELECT * FROM
Athena_Cloudera_Hive_connector_data_source.Cloudera_Hive_database_name.Cloudera_Hive_table_name
```
このコネクタの詳細については、「[Amazon Athena Cloudera Hive コネクタ](connectors-cloudera-hive.md)」を参照してください。
### Cloudera Impala
Impala サーバーまたはクラスターは、Impala テーブルのグループを含む Impala データベースのグループです。
****
| Athena | Impala |
| --- | --- |
| Impala データソース | Impala コネクタの Lambda 関数は Impala server を指すように構成されています。 |
| data\$1source.database.table | server.database.table |
クエリの例
```
SELECT * FROM
Athena_Impala_connector_data_source.Impala_database_name.Impala_table_name
```
このコネクタの詳細については、「[Amazon Athena Cloudera Impala コネクタ](connectors-cloudera-impala.md)」を参照してください。
### MySQL
MySQL サーバーは MySQL テーブルのグループを含む MySQL データベースのグループです。
****
| Athena | MySQL |
| --- | --- |
| MySQL データソース | MySQL コネクタの Lambda 関数は MySQL server を指すように設定されています。 |
| data\$1source.database.table | server.database.table |
クエリの例
```
SELECT * FROM
Athena_MySQL_connector_data source.MySQL_database_name.MySQL_table_name
```
このコネクタの詳細については、「[Amazon Athena MySQL コネクタ](connectors-mysql.md)」を参照してください。
### Oracle
Oracle サーバー (またはデータベース) は、Oracle テーブルのグループを含む Oracle スキーマのグループです。
****
| Athena | Oracle |
| --- | --- |
| Oracle データソース | Oracle コネクタの Lambda 関数は Oracle server を指すように設定されています。 |
| data\$1source.database.table | server.schema.table |
クエリの例
```
SELECT * FROM
Athena_Oracle_connector_data_source.Oracle_schema_name.Oracle_table_name
```
このコネクタの詳細については、「[Amazon Athena Oracle コネクタ](connectors-oracle.md)」を参照してください。
### Postgres
Postgres サーバー (またはクラスター) は Postgres データベースのグループです。Postgres データベースは Postgres テーブルのグループを含む Postgres スキーマのグループです。
****
| Athena | Postgres |
| --- | --- |
| Postgres データソース | Postgres コネクタの Lambda 関数は Postgres server とdatabaseを指すように設定されています。 |
| data\$1source.database.table | server.database.schema.table |
クエリの例
```
SELECT * FROM
Athena_Postgres_connector_data_source.Postgres_schema_name.Postgres_table_name
```
このコネクタの詳細については、「[Amazon Athena PostgreSQL コネクタ](connectors-postgresql.md)」を参照してください。
# Athena Query Federation SDK を使用してデータソースコネクタを開発する
独自のデータソースコネクタを記述するには、[Athena Query Federation SDK](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) を使用できます。Athena Query Federation SDK は、Athena がそのクエリ実行プラインの一部をユーザーが記述してデプロイするコードに委託するために使用できる、インターフェイスとワイヤプロトコルの一式を定義します。SDK には、コネクタスイートとコネクタの例が含まれています。
カスタムコネクタは、Glue の設定プロパティを一元化するために Glue 接続を使用しません。接続設定は Lambda を介して行われます。
また、ユーザー独自の使用のために、Amazon Athena の[事前構築](https://github.com/awslabs/aws-athena-query-federation/wiki/Available-Connectors)されたコネクタをカスタマイズすることもできます。GitHub からのソースコードのコピーを変更し、[コネクタ公開ツール](https://github.com/awslabs/aws-athena-query-federation/wiki/Connector_Publish_Tool)を使用して独自の AWS Serverless Application Repository パッケージを作成することができます。この方法でコネクタをデプロイした後は、それを Athena クエリで使用することができます。
SDK をダウンロードする方法と、独自のコネクタを記述するための詳細な手順については、GitHub の「[Example Athena connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-example)」(Example Athena コネクタ) を参照してください。
# Apache Spark のデータソースコネクタを操作する
一部の Athena データソースコネクタは、Spark DSV2 コネクタとして利用できます。Spark DSV2 コネクタ名には `-dsv2` サフィックスが付いています (例: `athena-dynamodb-dsv2`)。
現在利用可能な DSV2 コネクタ、その Spark `.format()` クラス名、および対応する Amazon Athena Federated Query ドキュメントへのリンクを次に示します。
| DSV2 コネクタ | Spark .format() クラス名 | ドキュメント |
| --- | --- | --- |
| athena-cloudwatch-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.CloudwatchTableProvider | [CloudWatch](connectors-cloudwatch.md) |
| athena-cloudwatch-metrics-dsv2 | com.amazonaws.athena.connectors.dsv2.cloudwatch.metrics.CloudwatchMetricsTableProvider | [CloudWatch メトリクス](connectors-cwmetrics.md) |
| athena-aws-cmdb-dsv2 | com.amazonaws.athena.connectors.dsv2.aws.cmdb.AwsCmdbTableProvider | [CMDB](connectors-cmdb.md) |
| athena-dynamodb-dsv2 | com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider | [DynamoDB](connectors-dynamodb.md) |
DSV2 コネクタ用の `.jar` ファイルをダウンロードするには、[Amazon Athena Query Federation DSV2](https://github.com/awslabs/aws-athena-query-federation-dsv2) の GitHub ページにアクセスし、「**リリース**」、「***<バージョン>* のリリース**」、「**アセット**」セクションを参照してください。
## Spark に対する jar を指定する
Spark で Athena DSV2 コネクタを使用するには、使用している Spark 環境にコネクタの `.jar` ファイルを送信します。次のセクションでは、特定のケースについて説明します。
### Athena for Spark
Amazon Athena for Apache Spark にカスタム `.jar` ファイルとカスタム設定を追加するための情報については、「[Spark プロパティを使用してカスタム設定を指定する](notebooks-spark-custom-jar-cfg.md)」を参照してください。
### 一般的な Spark
コネクタ `.jar` ファイルを Spark に渡すには、次の例のように、`spark-submit` コマンドを使用し、`--jars` オプションで `.jar` ファイルを指定します。
```
spark-submit \
--deploy-mode cluster \
--jars https://github.com/awslabs/aws-athena-query-federation-dsv2/releases/download/some_version/athena-dynamodb-dsv2-some_version.jar
```
### Amazon EMR Spark
Amazon EMR で `--jars` パラメータを指定して `spark-submit` コマンドを実行するには、Amazon EMR Spark クラスターにステップを追加する必要があります。Amazon EMR での `spark-submit` の使用方法の詳細については、「Amazon EMR リリースガイド」の「[Spark ステップを追加する](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-spark-submit-step.html)」を参照してください。
### AWS Glue ETL Spark
AWS Glue ETL の場合、`.jar` ファイルの GitHub.com URL を `aws glue start-job-run` コマンドの `--extra-jars` 引数に渡すことができます。AWS Glue ドキュメントでは `--extra-jars` パラメータが Amazon S3 パスを取るように説明されていますが、パラメータは HTTPS URL を取ることもできます。詳細については、「AWS Glue デベロッパーガイド」の「[ジョブパラメータリファレンス](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html#w5aac32c13c11)」を参照してください。
## Spark でのコネクタをクエリする
Apache Spark で既存の Athena フェデレーテッドクエリと同等のクエリを送信するには、`spark.sql()` 関数を使用します。たとえば、Apache Spark で使用する次の Athena クエリがあるとします。
```
SELECT somecola, somecolb, somecolc
FROM ddb_datasource.some_schema_or_glue_database.some_ddb_or_glue_table
WHERE somecola > 1
```
Amazon Athena DynamoDB DSV2 コネクタを使用して Spark で同じクエリを実行するには、次のコードを使用します。
```
dynamoDf = (spark.read
.option("athena.connectors.schema", "some_schema_or_glue_database")
.option("athena.connectors.table", "some_ddb_or_glue_table")
.format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider")
.load())
dynamoDf.createOrReplaceTempView("ddb_spark_table")
spark.sql('''
SELECT somecola, somecolb, somecolc
FROM ddb_spark_table
WHERE somecola > 1
''')
```
## パラメータを指定します
DSV2 バージョンの Athena データソースコネクタは、対応する Athena データソースコネクタと同じパラメータを使用します。パラメータの情報については、対応する Athena データソースコネクタのドキュメントを参照してください。
PySpark コードでは、次の構文を使用してパラメータを設定します。
```
spark.read.option("athena.connectors.conf.parameter", "value")
```
たとえば、次のコードは Amazon Athena DynamoDB コネクタ `disable_projection_and_casing` パラメータを `always` に設定します。
```
dynamoDf = (spark.read
.option("athena.connectors.schema", "some_schema_or_glue_database")
.option("athena.connectors.table", "some_ddb_or_glue_table")
.option("athena.connectors.conf.disable_projection_and_casing", "always")
.format("com.amazonaws.athena.connectors.dsv2.dynamodb.DDBTableProvider")
.load())
```
# Athena で Amazon DataZone を使用する
「[Amazon DataZone](https://aws.amazon.com/datazone)」を使用して、組織の境界を越えてデータを大規模に共有、検索、検出できます。DataZone は、Athena、AWS Glue、AWS Lake Formation などの AWS 分析サービス全体のエクスペリエンスを簡素化します。例えば、さまざまなデータソースに数ペタバイトのデータがある場合、Amazon DataZone を使用して、人、データ、ツールをビジネスユースケースに基づいてグループ化できます。詳細については、「[Amazon DataZone とは?](https://docs.aws.amazon.com/datazone/latest/userguide/what-is-datazone.html)」を参照してください。
Athena では、クエリエディターを使用して DataZone 環境にアクセスしてクエリを実行できます。DataZone 環境では、DataZone プロジェクトとドメインの組み合わせが指定されます。Athena コンソールから DataZone 環境を使用するとき、DataZone 環境の IAM ロールを引き継ぎ、その環境に属するデータベースおよびテーブルのみが表示されます。許可は DataZone で指定したロールによって決まります。
Athena では、クエリエディタページの **[DataZone 環境]** セレクターを使用して DataZone 環境を選択できます。
**Athena で DataZone 環境を開く方法**
1. [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) で Athena コンソールを開きます。
1. Athena コンソールの右上にある **[ワークグループ]** の横で、**[DataZone 環境]** を選択します。
**注記**
**[DataZone 環境]** オプションは、DataZone で利用可能なドメインが 1 つ以上ある場合にのみ表示されます。
![\[[DataZone 環境] を選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datazone-using-1.png)
1. **[DataZone 環境]** セレクタを使用して DataZone 環境を選択します。
![\[DataZone 環境を選択してください\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datazone-using-2.png)
1. **[DataZone 環境に切り替え]** ダイアログボックスで目的の環境が表示されていることを確認し、**[DataZone 環境に切り替え]** を選択します。
![\[DataZone 環境への変更を確認します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datazone-using-3.png)
DataZone および Athena の開始方法の詳細については、「Amazon DataZone ユーザーガイド」の「[入門](https://docs.aws.amazon.com/datazone/latest/userguide/getting-started.html)」チュートリアルを参照してください。
# 外部の Hive メタストアを使用する
Apache Hive メタストアを使用する Amazon S3 内のデータセットをクエリするには、外部 Hive メタストア用の Amazon Athena データコネクタを使用できます。AWS Glue Data Catalog へのメタデータの移行は不要です。Athena マネジメントコンソールでプライベート VPC 内の Hive メタストアと通信する Lambda 関数を設定してから、それをメタストアに接続します。Lambda から Hive メタストアへの接続はプライベート Amazon VPC チャンネルによって保護されており、パブリックインターネットを使用しません。独自の Lambda 関数コードを提供することも、外部 Hive メタストア用の Athena データコネクタのデフォルト実装を使用することもできます。
**Topics**
+ [機能の概要](#connect-to-a-data-source-hive-features)
+ [ワークフロー](#connect-to-data-source-hive-workflow)
+ [考慮事項と制限事項](#connect-to-a-data-source-hive-considerations)
+ [Athena を Apache Hive メタストアに接続する](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md)
+ [AWS Serverless Application Repository を使用して Hive データソースコネクタをデプロイする](connect-data-source-sar-hive.md)
+ [既存の IAM 実行ロールを使用して Hive メタストアに Athena を接続する](connect-data-source-hive-existing-iam-role.md)
+ [デプロイ済みの Hive メタストアコネクタを使用するように Athena を設定する](connect-data-source-hive-existing-lambda.md)
+ [外部 Hive メタストアクエリでカタログ名を省略する](datastores-hive-default-catalog.md)
+ [Hive ビューを使用する](hive-views.md)
+ [Hive メタストアで AWS CLI を使用する](datastores-hive-cli.md)
+ [Athena 外部 Hive メタストアコネクタを変更する](datastores-hive-reference-implementation.md)
## 機能の概要
外部 Hive メタストア用の Athena データコネクタを使用することで、以下のタスクを実行できます。
+ Athena コンソールを使用して、カスタムカタログを登録し、それらを使用してクエリを実行する。
+ 異なる外部 Hive メタストアの Lambda 関数を定義して、Athena クエリでそれらを結合する。
+ AWS Glue Data Catalog と外部 Hive メタストアを同じ Athena クエリで使用する。
+ クエリ実行コンテキストのカタログを現在のデフォルトカタログとして指定する。これにより、クエリのデータベース名にカタログ名のプレフィックスを付ける必要がなくなります。構文 `catalog.database.table` を使用する代わりに、`database.table` を使用できます。
+ さまざまなツールを使用して、外部 Hive メタストアを参照するクエリを実行する。これには、Athena コンソール、AWS CLI、AWS SDK、Athena API、更新された Athena JDBC および ODBC ドライバーを使用できます。更新されたドライバーは、カスタムカタログをサポートしています。
### API サポート
外部 Hive メタデータ用の Athena データコネクタには、カタログ登録 API オペレーションとメタデータ API オペレーションのサポートが含まれています。
+ **カタログ登録** – 外部 Hive メタストアと[フェデレーティッドデータソース](federated-queries.md)用のカスタムカタログを登録します。
+ **メタデータ** – メタデータ API を使用して、AWS Glue と、Athena に登録した任意のカタログのデータベースとテーブル情報を提供します。
+ **Athena JAVA SDK クライアント** – 更新された Athena Java SDK クライアントのカタログ登録 API、メタデータ API、および `StartQueryExecution` オペレーションでのカタログのサポートを使用します。
### リファレンス実装
Athena は、外部 Hive メタストアに接続する Lambda 関数のリファレンス実装を提供します。リファレンス実装は、[Athena Hive メタストア](https://github.com/awslabs/aws-athena-hive-metastore)のオープンソースプロジェクトとして GitHub で提供されています。
リファレンス実装は、AWS SAM (SAR) で次の 2 つの AWS Serverless Application Repository アプリケーションとして利用できます。これらのアプリケーションのいずれかを SAR で使用して、独自の Lambda 関数を作成できます。
+ `AthenaHiveMetastoreFunction` – Uber Lambda 関数 `.jar` ファイルです。「uber」JAR (fat JAR、または依存関係が含まれる JAR としても知られています) は、Java プログラムとその依存関係の両方を単一のファイルに収めた `.jar` ファイルです。
+ `AthenaHiveMetastoreFunctionWithLayer` – Lambda レイヤーと thin Lambda 関数 `.jar` ファイルです。
## ワークフロー
以下の図は、Athena が外部 Hive メタストアとどのようにやり取りするかを説明しています。
![\[Athena が外部の Hive メタストアとやり取りする方法です。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-to-data-source-hive-workflow.png)
このワークフローでは、データベースに接続された Hive メタストアが VPC 内にあります。Hive Server2 を使用して、Hive CLI を使用して Hive メタストアを管理します。
Athena から外部 Hive メタストアを使用するワークフローには、以下のステップが含まれます。
1. VPC 内の Hive メタストアに Athena を接続する Lambda 関数を作成します。
1. Hive メタストアの一意のカタログ名をアカウントに登録し、対応する関数名を登録します。
1. カタログ名を使用する Athena DML または DDL クエリを実行すると、Athena クエリエンジンがそのカタログ名に関連付けられた Lambda 関数名を呼び出します。
1. AWS PrivateLink を使用すると、Lambda 関数が VPC 内の外部 Hive メタストアと通信し、メタデータリクエストに対する応答を受け取ります。Athena は、デフォルトの AWS Glue Data Catalogからのメタデータを使用する場合と同様に、外部 Hive メタストアからのメタデータを使用します。
## 考慮事項と制限事項
外部 Hive メタストア用の Athena データコネクタを使用するときは、以下の点を考慮してください。
+ CTAS を使用して、外部の Hive メタストアにテーブルを作成できます。
+ INSERT INTO を使用して、外部 Hive メタストアにデータを挿入できます。
+ 外部 Hive メタストアに対する DDL サポートは、以下のステートメントに限定されています。
+ ALTER DATABASE SET DBPROPERTIES
+ ALTER TABLE ADD COLUMNS
+ ALTER TABLE ADD PARTITION
+ ALTER TABLE DROP PARTITION
+ ALTER TABLE RENAME PARTITION
+ テーブルの変更列の置き換え
+ ALTER TABLE SET LOCATION
+ ALTER TABLE SET TBLPROPERTIES
+ CREATE DATABASE
+ CREATE TABLE
+ CREATE TABLE AS
+ DESCRIBE TABLE
+ DROP DATABASE
+ DROP TABLE
+ SHOW COLUMNS
+ SHOW CREATE TABLE
+ SHOW PARTITIONS
+ SHOW SCHEMAS
+ SHOW TABLES
+ SHOW TBLPROPERTIES
+ 登録できるカタログの最大数は 1,000 です。
+ Hive メタストアの Kerberos 認証はサポートされていません。
+ 外部 Hive メタストア、または[フェデレーティッドクエリ](federated-queries.md)で JDBC ドライバーを使用するには、JDBC 接続文字列に `MetadataRetrievalMethod=ProxyAPI` を含めます。JDBC ドライバーの詳細については、「[JDBC で Amazon Athena に接続する](connect-with-jdbc.md)」を参照してください。
+ Hive の非表示列 である `$path`、`$bucket`、`$file_size`、`$file_modified_time`、`$partition`、`$row_id` はきめ細かいアクセス制御フィルタリングには使用できません。
+ `example_table$partitions` や `example_table$properties` などの Hive 非表示システムテーブルでは、きめ細かなアクセス制御はサポートされていません。
### アクセス許可
構築済みのデータソースコネクタは、正しく機能するために、次のリソースへのアクセスが必要になる場合があります。使用するコネクタの情報をチェックして、VPC が正しく設定されていることを確認します。Athena でクエリを実行してデータソースコネクタを作成するために必要な IAM 許可については、「[外部 Hive メタストア用の Athena データコネクタへのアクセスを許可する](hive-metastore-iam-access.md)」および「[外部 Hive メタストアへの Lambda 関数アクセスを許可する](hive-metastore-iam-access-lambda.md)」を参照してください。
+ **Simple Storage Service (Amazon S3)** – データコネクタは、Athena のクエリ結果が保存される Amazon S3 内の場所にクエリ結果を書き込むほか、Amazon S3 のスピルバケットにも書き込みます。この Amazon S3 の場所に対する接続と許可が必要です。詳細については、このトピックで後述する「[Amazon S3 のスピルの場所](#connect-to-data-source-hive-spill-location)」を参照してください。
+ **Athena** – クエリのステータスをチェックして、オーバースキャンを防止するためのアクセス権が必要です。
+ **AWS Glue** – コネクタが補足メタデータまたはプライマリメタデータに AWS Glue を使用する場合、アクセス権が必要です。
+ **AWS Key Management Service**
+ **ポリシー** – Hive メタストア、Athena Query Federation、および UDF には、[AWS 管理ポリシー: AmazonAthenaFullAccess](security-iam-awsmanpol.md#amazonathenafullaccess-managed-policy) 以外にポリシーが必要です。詳細については、「[Athena でのアイデンティティとアクセス権の管理](security-iam-athena.md)」を参照してください。
### Amazon S3 のスピルの場所
Lambda 関数のレスポンスサイズに対する[制限](https://docs.aws.amazon.com/lambda/latest/dg/limits.html)のため、しきい値を超えるサイズのレスポンスは、Lambda 関数の作成時に指定する Amazon S3 の場所にスピルされます。Athena は、これらのレスポンスを Amazon S3 から直接読み込みます。
**注記**
Athena は Amazon S3 上のレスポンスファイルを削除しません。レスポンスファイルを自動的に削除するように保持ポリシーをセットアップすることが推奨されます。
# Athena を Apache Hive メタストアに接続する
Athena を Apache Hive メタストアに接続するには、Lambda 関数を作成して設定する必要があります。基本的な実装では、Athena マネジメントコンソールから必要なステップのすべてを実行できます。
**注記**
以下の手順には、Lambda 関数にカスタム IAM ロールを作成するための許可が必要です。カスタムロールを作成するアクセス許可がない場合は、Athena の[リファレンス実装](connect-to-data-source-hive.md#connect-to-a-data-source-hive-features-reference-implementation)を使用して Lambda 関数を個別に作成してから、AWS Lambda コンソールを使用してこの関数に既存の IAM ロールを選択することができます。詳細については、「」を参照してください[既存の IAM 実行ロールを使用して Hive メタストアに Athena を接続する](connect-data-source-hive-existing-iam-role.md)
**Athena を Hive メタストアに接続する**
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. **[データソースとカタログ]** を選択します。
1. コンソールの右上で、[**Create data source**] (データソースの作成) を選択します。
1. [**Choose a data source**] (データソースの選択) ページの [**Data sources**] (データソース) で、**[S3 - Apache Hive metastore]** (S3 – Apache Hive メタストア) を選択します。
1. [**次へ**] を選択します。
1. **[Data source details]** (データソースの詳細) セクションの **[Data source name]** (データソース名) に、Athena からデータソースをクエリする際に SQL ステートメントで使用する名前を入力します。名前は最大 127 文字で、アカウント内で一意である必要があります。この設定は、作成後に変更することはできません。有効な文字は、a～z、A～Z、0～9、\$1 (アンダースコア)、@ (at マーク)、および - (ハイフン) です。`awsdatacatalog`、`hive`、`jmx`、および `system` の名前は Athena によって予約されており、データソース名には使用できません。
1. **[Lambda 関数]** で **[Lambda 関数の作成]** を選択してから、**[AWS Lambda で新しい関数を作成]** を選択します。
AWS Lambda コンソールに [**AthenaHiveMetastoreFunction**] ページが開きます。このページには、コネクタに関する詳細情報が表示されます。
![\[AWS Lambda コンソールの[AthenaHiveMetastoreFunction] ページ。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-to-data-source-hive-4.png)
1. [**Application settings**] (アプリケーションの設定) で Lambda 関数のパラメータを入力します。
+ **[LambdaFuncName]** – 関数の名前を指定します。たとえば、**myHiveMetastore** です。
+ **[SpillLocation]** (スピル場所) - Lambda 関数のレスポンスサイズが 4 MB を超える場合にスピルオーバーメタデータを保持するための、このアカウント内の Amazon S3 の場所を指定します。
+ **[HMSUris]** – ポート 9083 で Thrift プロトコルを使用する Hive メタストアホストの URI を入力します。`thrift://:9083` 構文を使用してください。
+ **[LambdaMemory]** - 128 MB から 3,008 MB までの値を指定します。Lambda 関数には、設定するメモリ量に比例した CPU サイクルが割り当てられます。デフォルトは 1024 です。
+ **[LambdaTimeout]** – Lambda 呼び出しの最大許容実行時間を 1～900 (900 秒は 15 分) の秒数で指定します。デフォルトは 300 秒 (5 分) です。
+ **[VPCSecurityGroupIds]** – Hive メタストアの VPC セキュリティグループ ID のカンマ区切りリストを入力します。
+ **[VPCSubnetIds]** – Hive メタストアの VPC サブネット ID のカンマ区切りリストを入力します。
1. **[I acknowledge that this app creates custom IAM roles and resource policies]** (このアプリがカスタム IAM ロールとリソースポリシーを作成することを承認します) を選択した後、**[Deploy]** (デプロイ) を選択します。
![\[AWS Lambda コンソールから Lambda 関数アプリをデプロイします。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-to-data-source-hive-4a.png)
デプロイが完了すると、Lambda アプリケーションのリストにこの関数が表示されます。Hive メタストア関数がアカウントにデプロイされたところで、それを使用するように Athena を設定できます。
1. Athena コンソールの [**Connect data sources**] (データソースを接続) ページに戻ります。
1. [**Lambda function**] セクションで、Lambda 関数の検索ボックスの横にある更新アイコンをクリックします。利用できる関数のリストを更新すると、新しく作成した関数がリストに表示されます。
1. Lambda コンソールで作成した関数の名前を選択します。Lambda 関数の ARN が表示されます。
1. (オプション) **[Tags]** (タグ) でキーと値のペアを追加して、このデータソースに関連付けます。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**次へ**] を選択します。
1. [**Review and create**] (確認と作成) ページで、データソースの詳細について確認し、[**Add data source**] (データソースの追加) を選択します。
1. データソースのページの [**データソースの詳細**] セクションには、新しいコネクタに関する情報が表示されます。
これで、指定した **[Data source name]** (データソース名) を使用して、Athena の SQL クエリで Hive メタストアを参照できるようになります。SQL クエリで、次の構文例を使用し、`hms-catalog-1` を以前に指定したカタログ名に置き換えます。
```
SELECT * FROM hms-catalog-1.CustomerData.customers
```
1. 作成したデータソースを表示、編集、または削除する方法については、「[データソースを管理する](data-sources-managing.md)」を参照してください。
# AWS Serverless Application Repository を使用して Hive データソースコネクタをデプロイする
Hive 用の Athena データソースコネクタをデプロイする際は、Athena コンソールから始める代わりに [AWS Serverless Application Repository](https://aws.amazon.com/serverless/serverlessrepo/) を使用できます。AWS Serverless Application Repository により、使用する対象のコネクタを検索し、コネクタに必要なパラメータを指定した上で、そのコネクタをアカウントにデプロイします。コネクタのデプロイが完了したら、Athena コンソールを使用して Athena がデータソースを使用できるようにします。
**AWS Serverless Application Repository を使用して Hive のデータソースコネクタをアカウントにデプロイするには**
1. AWS マネジメントコンソール にサインインし、**サーバーレスアプリケーションリポジトリ**を開きます。
1. ナビゲーションペインで、[**Available applications**] (利用可能なアプリケーション) を選択します。
1. **[Show apps that create custom roles or resource policies]** (カスタム IAM ロールまたはリソースポリシーを作成するアプリを表示する) オプションを選択します。
1. 検索ボックスに「**Hive**」と入力します。表示されるコネクタには、次の 2 つがあります。
+ **AthenaHiveMetastoreFunction** – Uber Lambda 関数の `.jar` ファイル。
+ **AthenaHiveMetastoreFunctionWithLayer** – Lambda レイヤーと thin Lambda 関数の `.jar` ファイル。
2 つのアプリケーションの機能は同じで、実装のみが異なります。どちらか 1 つを使用して、Athena を Hive メタストアに接続する Lambda 関数を作成できます。
1. 使用するコネクタの名前を選択します。このチュートリアルでは **AthenaHiveMetastoreFunction** を使用します。
![\[Hive 用の Athena データソースコネクタの名前を選択します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-data-source-sar-hive-1.png)
1. [**Application settings**] (アプリケーションの設定) で Lambda 関数のパラメータを入力します。
+ **[LambdaFuncName]** – 関数の名前を指定します。たとえば、**myHiveMetastore** です。
+ **[SpillLocation]** (スピル場所) - Lambda 関数のレスポンスサイズが 4 MB を超える場合にスピルオーバーメタデータを保持するための、このアカウント内の Amazon S3 の場所を指定します。
+ **[HMSUris]** – ポート 9083 で Thrift プロトコルを使用する Hive メタストアホストの URI を入力します。`thrift://:9083` 構文を使用してください。
+ **[LambdaMemory]** - 128 MB から 3,008 MB までの値を指定します。Lambda 関数には、設定するメモリ量に比例した CPU サイクルが割り当てられます。デフォルトは 1024 です。
+ **[LambdaTimeout]** – Lambda 呼び出しの最大許容実行時間を 1～900 (900 秒は 15 分) の秒数で指定します。デフォルトは 300 秒 (5 分) です。
+ **[VPCSecurityGroupIds]** – Hive メタストアの VPC セキュリティグループ ID のカンマ区切りリストを入力します。
+ **[VPCSubnetIds]** – Hive メタストアの VPC サブネット ID のカンマ区切りリストを入力します。
1. [**Application details**] (アプリケーションの詳細)ページの右下で [**I acknowledge that this app creates custom IAM roles**] (このアプリがカスタム IAM ロールを作成することを承認します) を選択してから、[**Deploy**] (デプロイ) をクリックします。
この時点で、Lambda 関数を使用して Hive メタストアに接続するように Athena を設定できます。手順については、「[デプロイ済みの Hive メタストアコネクタを使用するように Athena を設定する](connect-data-source-hive-existing-lambda.md)」を参照してください。
# 既存の IAM 実行ロールを使用して Hive メタストアに Athena を接続する
既存の IAM ロールを使用する Lambda 関数を使用して外部 Hive メタストアを Athena に接続するには、外部 Hive メタストア用の Athena コネクタのリファレンス実装を使用できます。
以下は、3 つの主なステップです。
1. **[クローンと構築](#connect-data-source-hive-existing-iam-role-clone-and-build-the-lambda-function)** – Athena リファレンス実装をクローンし、Lambda 関数コードが含まれる JAR ファイルを構築します。
1. **[AWS Lambda コンソール](#connect-data-source-hive-existing-iam-role-aws-lambda-console)** – AWS Lambda コンソールで Lambda 関数を作成し、それに既存の IAM 実行ロールを割り当てて、生成した関数コードをアップロードします。
1. **[Amazon Athena コンソール](connect-data-source-hive-existing-lambda.md)** – Amazon Athena コンソールで、Athena クエリで外部 Hive メタストアを参照する際に使用するデータソース名を作成します。
カスタム IAM ロールを作成するアクセス許可がすでにある場合は、Lambda 関数の作成と設定に Athena コンソールと AWS Serverless Application Repository を使用する、よりシンプルなワークフローを使用できます。詳細については、「[Athena を Apache Hive メタストアに接続する](connect-to-data-source-hive-connecting-athena-to-an-apache-hive-metastore.md)」を参照してください。
## 前提条件
+ Git がシステムにインストールされている。
+ [Apache Maven](https://maven.apache.org/) がインストールされている。
+ Lambda 関数に割り当てることができる IAM 実行ロールがある。詳細については、「」を参照してください[外部 Hive メタストアへの Lambda 関数アクセスを許可する](hive-metastore-iam-access-lambda.md)
## Lambda 関数をクローンして構築する
Athena リファレンス実装の関数コードは、GitHub ([awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)) にある Maven プロジェクトです。プロジェクトの詳細については、GitHub の対応する README ファイル、または本書の「[Athena 外部 Hive メタストアコネクタを変更する](datastores-hive-reference-implementation.md)」トピックを参照してください。
**Lambda 関数コードをクローンして構築する**
1. 以下のコマンドを入力して、Athena リファレンス実装をクローンします。
```
git clone https://github.com/awslabs/aws-athena-hive-metastore
```
1. 以下のコマンドを実行して、Lambda 関数の `.jar` ファイルを構築します。
```
mvn clean install
```
プロジェクトが正常に構築されると、以下の `.jar` ファイルがプロジェクトのターゲットフォルダに作成されます。
`hms-lambda-func-1.0-SNAPSHOT-withdep.jar`
次のセクションでは、AWS Lambda コンソールを使用してこのファイルを Amazon Web Services アカウントにアップロードします。
## AWS Lambda コンソールで Lambda 関数を作成して設定する
このセクションでは、AWS Lambda コンソールを使用して、既存の IAM 実行ロールを使用する関数を作成します。関数用の VPC を設定したら、関数コードをアップロードして、関数の環境変数を設定します。
### Lambda 関数を作成する
このステップでは、既存の IAM ロールを使用する関数を AWS Lambda コンソールで作成します。
**既存の IAM ロールを使用する Lambda 関数を作成する**
1. AWS マネジメントコンソール にサインインして AWS Lambda コンソール ([https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/)) を開きます。
1. ナビゲーションペインで、[**Functions**] (関数) を選択します。
1. **関数の作成** を選択します。
1. **Author from scratch** (製作者を最初から) を選択します。
1. **[Function name]** (関数名) には、Lambda 関数の名前 (**EHMSBasedLambda** など) を入力します。
1. **[Runtime]** (ランタイム) には **[Java 8]** を選択します。
1. **[Permissions]** (許可) で、**[Change default execution role]** (デフォルトの実行ロールの変更) を展開します。
1. [**Execution role (実行ロール)**] で、[**Use an existing role (既存のロールを使用する)**] を選択します。
1. **[Existing role]** (既存のロール) には、Lambda 関数が Athena 向けに使用する IAM 実行ロールを選択します (この例では `AthenaLambdaExecutionRole` と呼ばれるロールを使用しています)。
1. **[詳細設定]** を展開します。
1. **[Enable Network]** (ネットワークの有効化) を選択します。
1. **[VPC]** で、関数がアクセスする VPC を選択します。
1. **[Subnets]** (サブネット) には、Lambda が使用する VPC サブネットを選択します。
1. **[Security groups]** (セキュリティグループ) には、Lambda が使用する VPC セキュリティグループを選択します。
1. [**Create function**] (関数の作成) をクリックします。AWS Lambda コンソールが関数の設定ページを開き、関数の作成を開始します。
### コードをアップロードして Lambda 関数を設定する
コンソールから関数が正常に作成されたことが通知されると、関数コードをアップロードして、その環境変数を設定する準備が整います。
**Lambda 関数コードをアップロードしてその環境変数を設定する**
1. Lambda コンソールで、指定した関数ページの **[Code]** (コード) タブが開かれていることを確認します。
1. **[Code source]** (コードソース) で、**[Upload from]** (アップロード元) をクリックした後、**[.zip or .jar file]** (.zip または.jar ファイル) を選択します。
1. 先ほど生成した `hms-lambda-func-1.0-SNAPSHOT-withdep.jar` ファイルをアップロードします。
1. [Lambda 関数] ページで、[**設定**] タブを選択します。
1. 左側のペインで、**[Environment variables]** (環境変数) をクリックします。
1. [**環境変数**] セクションで、[**編集**] を選択します。
![\[[Edit] (編集) をクリックして Lambda 関数の環境変数を編集します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-5.png)
1. **[Edit environment variables]** (環境変数の編集) ページで、**[Add environment variable]** (環境変数の追加) オプションを使用し、以下の環境変数のキーと値を追加します。
+ **HMS\$1URIS** – 以下の構文を使用して、ポート 9083 で Thrift プロトコルを使用する Hive メタストアホストの URI を入力します。
```
thrift://:9083
```
+ **SPILL\$1LOCATION** - Lambda 関数のレスポンスサイズが 4 MB を超える場合、スピルオーバーメタデータを保持するために Amazon Web Services アカウントの Amazon S3 ロケーションを指定します。
![\[Lambda 関数環境変数の値を指定します。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/connect-data-source-hive-existing-iam-role-6.png)
1. **[保存]** を選択します。
これで、Lambda 関数を使用して Hive メタストアに接続するように、Athena を設定するための準備ができました。手順については、「[デプロイ済みの Hive メタストアコネクタを使用するように Athena を設定する](connect-data-source-hive-existing-lambda.md)」を参照してください。
# デプロイ済みの Hive メタストアコネクタを使用するように Athena を設定する
アカウントに `AthenaHiveMetastoreFunction` のような Lambda データソースコネクタをデプロイした後、その使用を Athena に設定します。これを行うには、Athena クエリで使用する外部 Hive メタストアを参照するためのデータソース名を作成します。
**既存の Lambda 関数を使用して Athena を Hive メタストアに接続するには**
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. **[データソースとカタログ]** を選択します。
1. **[データソースとカタログ]** ページで **[データソースを作成]** を選択します。
1. [**Choose a data source**] (データソースの選択) ページの [**Data sources**] (データソース) で、**[S3 - Apache Hive metastore]** (S3 – Apache Hive メタストア) を選択します。
1. [**次へ**] を選択します。
1. **[Data source details]** (データソースの詳細) セクションの **[Data source name]** (データソース名) に、Athena からデータソースをクエリする際に SQL ステートメントで使用する名前 (例えば `MyHiveMetastore`) を入力します。名前は最大 127 文字で、アカウント内で一意である必要があります。この設定は、作成後に変更することはできません。有効な文字は、a～z、A～Z、0～9、\$1 (アンダースコア)、@ (at マーク)、および - (ハイフン) です。`awsdatacatalog`、`hive`、`jmx`、および `system` の名前は Athena によって予約されており、データソース名には使用できません。
1. [**接続の詳細**] セクションで、[**Lambda 関数を選択または入力**] ボックスを使って、先ほど作成した関数の名前を選択します。Lambda 関数の ARN が表示されます。
1. (オプション) **[Tags]** (タグ) でキーと値のペアを追加して、このデータソースに関連付けます。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**次へ**] を選択します。
1. [**Review and create**] (確認と作成) ページで、データソースの詳細について確認し、[**Add data source**] (データソースの追加) を選択します。
1. データソースのページの [**データソースの詳細**] セクションには、新しいコネクタに関する情報が表示されます。
これで、指定した **[Data source name]** (データソース名) を使用して、Athena の SQL クエリで Hive メタストアを参照できるようになります。
SQL クエリで次の構文例を使用する際には、`ehms-catalog` の部分を先に指定したデータソース名に置き換えます。
```
SELECT * FROM ehms-catalog.CustomerData.customers
```
1. 作成したデータソースを表示、編集、または削除するには、「[データソースを管理する](data-sources-managing.md)」を参照してください 。
# 外部 Hive メタストアクエリでカタログ名を省略する
外部 Hive メタストアで DML クエリと DDL クエリを実行するとき、クエリエディタでカタログ名が選択されている場合は、カタログ名を省略することでクエリ構文を簡略化できます。この機能には一定の制限が適用されます。
## DML ステートメント
**登録済みカタログでクエリを実行するには**
1. 次の例のように、構文 `[[data_source_name].database_name].table_name` を使用してデータベースの前にデータソース名を配置できます。
```
select * from "hms-catalog-1".hms_tpch.customer limit 10;
```
1. 使用するデータソースが、クエリエディタ内ですでに選択されている場合は、次の例のようにクエリからカタログ名を省略できます。
```
select * from hms_tpch.customer limit 10:
```
![\[デフォルトのデータソースを使用した DML クエリ。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datastores-hive-default-catalog-2.png)
1. クエリで複数のデータソースを使用する場合、デフォルトのデータソース名のみ省略が可能で、デフォルト以外のすべてのデータソースについては、フルネームを指定する必要があります。
例えば、クエリエディタでデフォルトのデータソースとして `AwsDataCatalog` が選択されているとします。次に抜粋した、クエリの `FROM` ステートメントでは、最初の 2 つのデータソース名については完全修飾名で指定していますが、3 番目のデータソースの名前は、AWS Glue データカタログに含まれているため省略しています。
```
...
FROM ehms01.hms_tpch.customer,
"hms-catalog-1".hms_tpch.orders,
hms_tpch.lineitem
...
```
## DDL ステートメント
以下の Athena DDL ステートメントは、カタログ名のプレフィックスをサポートします。他の DDL ステートメントのカタログ名プレフィックスは、構文エラーの原因となります。
```
SHOW TABLES [IN [catalog_name.]database_name] ['regular_expression']
SHOW TBLPROPERTIES [[catalog_name.]database_name.]table_name [('property_name')]
SHOW COLUMNS IN [[catalog_name.]database_name.]table_name
SHOW PARTITIONS [[catalog_name.]database_name.]table_name
SHOW CREATE TABLE [[catalog_name.][database_name.]table_name
DESCRIBE [EXTENDED | FORMATTED] [[catalog_name.][database_name.]table_name [PARTITION partition_spec] [col_name ( [.field_name] | [.'$elem$'] | [.'$key$'] | [.'$value$'] )]
```
クエリエディタでデータソースとデータベースが選択されている場合には、DML のステートメントと同様に、クエリからデータソースとデータベースのプレフィックスを省略できます。
次の図では、クエリエディタでデータソース `hms-catalog-1` とデータベース `hms_tpch` が選択されています。クエリ自体から、プレフィックス `hms-catalog-1` と データベース名 `hms_tpch` が省略されていても、`show create table customer` ステートメントは成功します。
![\[デフォルトのカタログを使用する DDL ステートメント。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datastores-hive-default-catalog-4.png)
## JDBC 接続文字列でのデフォルトデータソースの指定
Athena JDBC ドライバーを使用して Athena を外部 Hive メタストアに接続する場合、[SQL Workbench](https://www.sql-workbench.eu/index.html) などの SQL エディタで、`Catalog` パラメータを使用して接続文字列にデフォルトのデータソース名を指定します。
**注記**
最新の Athena JDBC ドライバーをダウンロードするには、「[Athena での JDBC ドライバーの使用](https://docs.aws.amazon.com/athena/latest/ug/connect-with-jdbc.html)」を参照してください。
次の接続文字列は、デフォルトのデータソースに *hms-catalog-name* を指定しています。
```
jdbc:awsathena://AwsRegion=us-east-1;S3OutputLocation=s3://amzn-s3-demo-bucket/lambda/results/;Workgroup=AmazonAthenaPreviewFunctionality;Catalog=hms-catalog-name;
```
以下の画像は、SQL Workbench で設定されている、JDBC 接続 URL の例を示しています。
![\[SQL Workbench での JDBC 接続 URL の設定。\]](http://docs.aws.amazon.com/ja_jp/athena/latest/ug/images/datastores-hive-default-catalog-jdbc-1.jpg)
# Hive ビューを使用する
Athena を使用して、外部 Apache Hive メタストア内の既存のビューをクエリできます。Athena は、元のビューを変更したり、翻訳を保存したりすることなく、ランタイムにその場でビューを翻訳します。
例えば、Athena ではサポートされていない構文 (`LATERAL VIEW explode()`) を使用する次のような Hive ビューがあるとします。
```
CREATE VIEW team_view AS
SELECT team, score
FROM matches
LATERAL VIEW explode(scores) m AS score
```
Athena は、Hive ビューのクエリ文字列を、Athena が実行できる次のようなステートメントに翻訳します。
```
SELECT team, score
FROM matches
CROSS JOIN UNNEST(scores) AS m (score)
```
外部の Hive メタストアを Athena に接続する方法の詳細については、「[外部の Hive メタストアを使用する](connect-to-data-source-hive.md)」(Athena データコネクタを外部の Hive メタストアに使用する) を参照してください。
## 考慮事項と制限事項
Athena から Hive ビューをクエリする際は、以下の点を考慮してください。
+ Athena では、Hive ビューの作成をサポートしていません。外部 Hive メタストアに Hive ビューを作成し、そこに Athena からクエリを実行することができます。
+ Athena では、Hive ビューのカスタム UDF をサポートしていません。
+ Athena コンソールの既知の問題により、Hive ビューは、ビューのリストではなくテーブルのリストに表示されます。
+ 翻訳プロセスは自動的に実行されますが、ある特定の Hive 関数は、Hive ビューでサポートされていないか、特別な処理が必要になります。詳細については、以下のセクションを参照してください。
## Hive 関数のサポート制限
このセクションでは、Athena が Hive ビューでサポートしていない Hive 関数、および特別な処理が必要な Hive 関数について取り上げます。現在、Athena は主に Hive 2.2.0 の関数をサポートしているため、上位バージョン (Hive 4.0.0 など) でのみ有効な関数を使用することはできません。Hive 関数の全リストについては、Hive の「[LanguageManual UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf)」(言語マニュアル UDF) を参照してください。
### 集計関数
#### 特別な処理を必要とする集計関数
Hive ビューの次の集計関数では、特別な処理が必要です。
+ **平均** — `avg(INT i)` の代わりに `avg(CAST(i AS DOUBLE))` を使用します。
#### サポートされていない集計関数
Athena の Hive ビューでは、次の Hive 集計関数はサポートされていません。
```
covar_pop
histogram_numeric
ntile
percentile
percentile_approx
```
Athena の Hive ビューでは、`regr_count`、`regr_r2`、`regr_sxx` などの回帰関数はサポートされていません。
### サポートされていない日付関数
Athena の Hive ビューでは、次の Hive 日付関数はサポートされていません。
```
date_format(date/timestamp/string ts, string fmt)
day(string date)
dayofmonth(date)
extract(field FROM source)
hour(string date)
minute(string date)
month(string date)
quarter(date/timestamp/string)
second(string date)
weekofyear(string date)
year(string date)
```
### サポートされていないマスク関数
Athena の Hive ビューでは、`mask()` や `mask_first_n()` などの Hive マスク関数はサポートされていません。
### その他の関数
#### 特別な処理を必要とするその他の関数
Hive ビューの次の種々の関数では、特別な処理が必要です。
+ **md5** – Athena では `md5(binary)` はサポートされますが、`md5(varchar)` はサポートされません。
+ **Explode** – 次の構文で使用される場合は、Athena で `explode` がサポートされます。
```
LATERAL VIEW [OUTER] EXPLODE()
```
+ **Posexplode** – 次の構文で使用される場合は、Athena で `posexplode` がサポートされます。
```
LATERAL VIEW [OUTER] POSEXPLODE()
```
`(pos, val)` 出力で、Athena は `pos` 列を `BIGINT` として扱います。このため、古いビューを回避するには、`pos` 列を `BIGINT` にキャストする必要がある場合があります。以下に示しているのはこの手法の例です。
```
SELECT CAST(c AS BIGINT) AS c_bigint, d
FROM table LATERAL VIEW POSEXPLODE() t AS c, d
```
#### サポートされていないその他の関数
Athena の Hive ビューでは、次の Hive 関数はサポートされていません。
```
aes_decrypt
aes_encrypt
current_database
current_user
inline
java_method
logged_in_user
reflect
sha/sha1/sha2
stack
version
```
### オペレータ
#### 特別な処理を必要とする演算子
Hive ビューの次の演算子では、特別な処理が必要です。
+ **Mod 演算子 (%)** – `DOUBLE` 型は暗黙的に `DECIMAL(x,y)` にキャストされるため、次の構文は View is stale (ビューが古くなっています) エラーメッセージの原因となる可能性があります。
```
a_double % 1.0 AS column
```
この問題を回避するには、次の例のように `CAST` を使用します。
```
CAST(a_double % 1.0 as DOUBLE) AS column
```
+ **除算演算子 (/)** – Hive では、`int` を `int` で除算すると `double` になります。Athena では、同じ演算で、切り捨てられた `int` が生成されます。
#### サポートされていない演算子
Athena の Hive ビューでは、次の演算子はサポートされていません。
**\$1A** – ビット単位の `NOT`
**A ^ b** – ビット単位の `XOR`
**A & b** – ビット単位の `AND`
**A \$1 b** – ビット単位の `OR`
**A <=> b** – Null 以外のオペランドの等価 (`=`) 演算子と同じ結果を返します。両方とも `NULL` の場合は `TRUE` を返し、いずれかが `NULL` の場合は `FALSE` を返します。
### 文字列関数
#### 特別な処理を必要とする文字列関数
Hive ビューの次の Hive 文字列関数では、特別な処理が必要です。
+ **chr(bigint\$1double a)** – Hive では負の引数を使用できますが、Athena では使用できません。
+ **instr(string str, string substr)** – `instr` 関数の Athena マッピングでは、`INT` ではなく `BIGINT` が返されるため、次の構文を使用します。
```
CAST(instr(string str, string substr) as INT)
```
このステップがない場合、ビューは古いものと見なされます。
+ **length(string a)** – `length` 関数の Athena マッピングでは、`INT` ではなく `BIGINT` が返されるため、ビューが古いものと見なされないように、次の構文を使用します。
```
CAST(length(string str) as INT)
```
#### サポートされていない文字列関数
Athena の Hive ビューでは、次の Hive 文字列関数はサポートされていません。
```
ascii(string str)
character_length(string str)
decode(binary bin, string charset)
encode(string src, string charset)
elt(N int,str1 string,str2 string,str3 string,...)
field(val T,val1 T,val2 T,val3 T,...)
find_in_set(string str, string strList)
initcap(string A)
levenshtein(string A, string B)
locate(string substr, string str[, int pos])
octet_length(string str)
parse_url(string urlString, string partToExtract [, string keyToExtract])
printf(String format, Obj... args)
quote(String text)
regexp_extract(string subject, string pattern, int index)
repeat(string str, int n)
sentences(string str, string lang, string locale)
soundex(string A)
space(int n)
str_to_map(text[, delimiter1, delimiter2])
substring_index(string A, string delim, int count)
```
### サポートされていない XPath 関数
Athena の Hive ビューでは、`xpath`、`xpath_short`、`xpath_int` などの Hive XPath 関数はサポートされていません。
## トラブルシューティング
Athena で Hive ビューを使用すると、次の問題が発生する場合があります。
+ **View ** is stale** (ビュー <ビュー名> が古くなっています) – このメッセージは通常、Hive と Athena のビューで型の不一致が存在することを示します。Hive の「[LanguageManual UDF](https://cwiki.apache.org/confluence/display/hive/languagemanual+udf)」(言語マニュアル UDF) ドキュメントと Presto の「[Functions and Operators](https://prestodb.io/docs/current/functions.html)」(関数と演算子) ドキュメントの同じ関数が異なるシグネチャを持つ場合は、不一致のデータ型をキャストしてみてください。
+ **Function not registered** (関数が登録されていません) – 現在、Athena では、この関数をサポートしていません。詳細については、このドキュメントの前述の情報を参照してください。
# Hive メタストアで AWS CLI を使用する
`aws athena` CLI コマンドを使用して、Athena で使用する Hive メタストアデータカタログを管理できます。Athena で使用するカタログを 1 つ、または複数定義したら、`aws athena` DDL コマンドと DML コマンドでこれらのカタログを参照できます。
## AWS CLI を使用して Hive メタストアカタログを管理する
### カタログの登録: Create-data-catalog
データカタログを登録するには、`create-data-catalog` コマンドを使用します。`name` パラメータを使用して、カタログに使用する名前を指定します。Lambda 関数の ARN を `parameters` 引数の `metadata-function` オプションに渡します。新しいカタログのタグを作成するには、`tags` パラメータを、スペースで区切った 1 つ以上の `Key=key,Value=value` 引数ペアとともに使用します。
次の例では、`hms-catalog-1` という名前の Hive メタストアカタログを登録します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena create-data-catalog
--name "hms-catalog-1"
--type "HIVE"
--description "Hive Catalog 1"
--parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3,sdk-version=1.0"
--tags Key=MyKey,Value=MyValue
--region us-east-1
```
### カタログの詳細の表示: Get-data-catalog
カタログの詳細を表示するには、次の例のように、カタログの名前を `get-data-catalog` コマンドに渡します。
```
$ aws athena get-data-catalog --name "hms-catalog-1" --region us-east-1
```
次のサンプル結果は JSON 形式です。
```
{
"DataCatalog": {
"Name": "hms-catalog-1",
"Description": "Hive Catalog 1",
"Type": "HIVE",
"Parameters": {
"metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3",
"sdk-version": "1.0"
}
}
}
```
### 登録済みカタログのリスト化: List-data-catalogs
登録されたカタログをリスト化するには、`list-data-catalogs` コマンドを使用し、必要に応じて次の例のようにリージョンを指定します。リストされているカタログには、常に AWS Glue が含まれます。
```
$ aws athena list-data-catalogs --region us-east-1
```
次のサンプル結果は JSON 形式です。
```
{
"DataCatalogs": [
{
"CatalogName": "AwsDataCatalog",
"Type": "GLUE"
},
{
"CatalogName": "hms-catalog-1",
"Type": "HIVE",
"Parameters": {
"metadata-function": "arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-v3",
"sdk-version": "1.0"
}
}
]
}
```
### カタログの更新: Update-data-catalog
データカタログを更新するには、次の例のように `update-data-catalog` コマンドを使用します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena update-data-catalog
--name "hms-catalog-1"
--type "HIVE"
--description "My New Hive Catalog Description"
--parameters "metadata-function=arn:aws:lambda:us-east-1:111122223333:function:external-hms-service-new,sdk-version=1.0"
--region us-east-1
```
### カタログの削除: Delete-data-catalog
データカタログを削除するには、次の例のように `delete-data-catalog` コマンドを使用します。
```
$ aws athena delete-data-catalog --name "hms-catalog-1" --region us-east-1
```
### データベース詳細の表示: Get-database
データベースの詳細を表示するには、次の例のように、カタログとデータベースの名前を `get-database` コマンドに渡します。
```
$ aws athena get-database --catalog-name hms-catalog-1 --database-name mydb
```
次のサンプル結果は JSON 形式です。
```
{
"Database": {
"Name": "mydb",
"Description": "My database",
"Parameters": {
"CreatedBy": "Athena",
"EXTERNAL": "TRUE"
}
}
}
```
### カタログ内のデータベースのリスト化: List-databases
カタログのデータベースをリスト化するには、`list-databases` コマンドを使用し、必要に応じて次の例のようにリージョンを指定します。
```
$ aws athena list-databases --catalog-name AwsDataCatalog --region us-west-2
```
次のサンプル結果は JSON 形式です。
```
{
"DatabaseList": [
{
"Name": "default"
},
{
"Name": "mycrawlerdatabase"
},
{
"Name": "mydatabase"
},
{
"Name": "sampledb",
"Description": "Sample database",
"Parameters": {
"CreatedBy": "Athena",
"EXTERNAL": "TRUE"
}
},
{
"Name": "tpch100"
}
]
}
```
### テーブルの詳細の表示: Get-table-metadata
カラム名やデータ型を含むテーブルのメタデータを表示するには、次の例のように、カタログ、データベース、およびテーブル名を `get-table-metadata` コマンドに渡します。
```
$ aws athena get-table-metadata --catalog-name AwsDataCatalog --database-name mydb --table-name cityuseragent
```
次のサンプル結果は JSON 形式です。
```
{
"TableMetadata": {
"Name": "cityuseragent",
"CreateTime": 1586451276.0,
"LastAccessTime": 0.0,
"TableType": "EXTERNAL_TABLE",
"Columns": [
{
"Name": "city",
"Type": "string"
},
{
"Name": "useragent1",
"Type": "string"
}
],
"PartitionKeys": [],
"Parameters": {
"COLUMN_STATS_ACCURATE": "false",
"EXTERNAL": "TRUE",
"inputformat": "org.apache.hadoop.mapred.TextInputFormat",
"last_modified_by": "hadoop",
"last_modified_time": "1586454879",
"location": "s3://amzn-s3-demo-bucket/",
"numFiles": "1",
"numRows": "-1",
"outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat",
"rawDataSize": "-1",
"serde.param.serialization.format": "1",
"serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe",
"totalSize": "61"
}
}
}
```
### データベース内のすべてのテーブルのメタデータの表示: List-table-metadata
データベース内のすべてのテーブルのメタデータを表示するには、カタログの名前とデータベース名を `list-table-metadata` コマンドに渡します。`list-table-metadata` コマンドは、テーブル名を指定しない点を除いて、`get-table-metadata` コマンドに似ています。結果件数を制限するには、次の例のように `--max-results` オプションを使用します。
```
$ aws athena list-table-metadata --catalog-name AwsDataCatalog --database-name sampledb --region us-east-1 --max-results 2
```
次のサンプル結果は JSON 形式です。
```
{
"TableMetadataList": [
{
"Name": "cityuseragent",
"CreateTime": 1586451276.0,
"LastAccessTime": 0.0,
"TableType": "EXTERNAL_TABLE",
"Columns": [
{
"Name": "city",
"Type": "string"
},
{
"Name": "useragent1",
"Type": "string"
}
],
"PartitionKeys": [],
"Parameters": {
"COLUMN_STATS_ACCURATE": "false",
"EXTERNAL": "TRUE",
"inputformat": "org.apache.hadoop.mapred.TextInputFormat",
"last_modified_by": "hadoop",
"last_modified_time": "1586454879",
"location": "s3://amzn-s3-demo-bucket/",
"numFiles": "1",
"numRows": "-1",
"outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat",
"rawDataSize": "-1",
"serde.param.serialization.format": "1",
"serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe",
"totalSize": "61"
}
},
{
"Name": "clearinghouse_data",
"CreateTime": 1589255544.0,
"LastAccessTime": 0.0,
"TableType": "EXTERNAL_TABLE",
"Columns": [
{
"Name": "location",
"Type": "string"
},
{
"Name": "stock_count",
"Type": "int"
},
{
"Name": "quantity_shipped",
"Type": "int"
}
],
"PartitionKeys": [],
"Parameters": {
"EXTERNAL": "TRUE",
"inputformat": "org.apache.hadoop.mapred.TextInputFormat",
"location": "s3://amzn-s3-demo-bucket/",
"outputformat": "org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat",
"serde.param.serialization.format": "1",
"serde.serialization.lib": "org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe",
"transient_lastDdlTime": "1589255544"
}
}
],
"NextToken": "eyJsYXN0RXZhbHVhdGVkS2V5Ijp7IkhBU0hfS0VZIjp7InMiOiJ0Ljk0YWZjYjk1MjJjNTQ1YmU4Y2I5OWE5NTg0MjFjYTYzIn0sIlJBTkdFX0tFWSI6eyJzIjoiY2xlYXJpbmdob3VzZV9kYXRhIn19LCJleHBpcmF0aW9uIjp7InNlY29uZHMiOjE1ODkzNDIwMjIsIm5hbm9zIjo2NTUwMDAwMDB9fQ=="
}
```
## DDL および DML ステートメントの実行
AWS CLI を使用して DDL および DML 文を実行する場合、次の 2 つの方法のいずれかで Hive メタストアカタログの名前を渡すことができます。
+ それをサポートするステートメントに直接渡す。
+ `--query-execution-context` `Catalog` パラメータに渡す。
### DDL ステートメント
次の例では、`show create table` DDL ステートメントの一部としてカタログ名に直接渡します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena start-query-execution
--query-string "show create table hms-catalog-1.hms_tpch_partitioned.lineitem"
--result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results"
```
次の DDL `show create table` ステートメントの例では、`Catalog` の `--query-execution-context` パラメータを使用して Hive メタストアカタログ名 `hms-catalog-1` に渡します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena start-query-execution
--query-string "show create table lineitem"
--query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned"
--result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results"
```
### DML ステートメント
次の DML `select` ステートメントの例では、カタログ名をクエリに直接渡します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena start-query-execution
--query-string "select * from hms-catalog-1.hms_tpch_partitioned.customer limit 100"
--result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results"
```
次の DML `select` ステートメントの例では、`Catalog` の `--query-execution-context` パラメータを使用して Hive メタストアカタログ名 `hms-catalog-1` に渡します。コマンドは、読みやすい形式にしてあります。
```
$ aws athena start-query-execution
--query-string "select * from customer limit 100"
--query-execution-context "Catalog=hms-catalog-1,Database=hms_tpch_partitioned"
--result-configuration "OutputLocation=s3://amzn-s3-demo-bucket/lambda/results"
```
# Athena 外部 Hive メタストアコネクタを変更する
特別な要件がある場合は、外部 Hive メタストア用の Athena コネクタを独自に使用するために変更できます。Athena は、GitHub.com ([https://github.com/awslabs/aws-athena-hive-metastore](https://github.com/awslabs/aws-athena-hive-metastore)) でコネクタのリファレンス実装を提供します。ほとんどのユースケースでは、リファレンス実装を変更する必要はありません。ただし、必要に応じて、ソースコードを変更し、アーティファクトを自分で構築することもできます。
リファレンス実装は、次のモジュールを持つ [Apache Maven](https://maven.apache.org/) プロジェクトです。
+ `hms-service-api` – Lambda 関数と Athena サービスクライアント間の API オペレーションが含まれています。これらの API オペレーションは、`HiveMetaStoreService` インターフェイスで定義されます。これはサービス契約であるため、このモジュールでは何も変更しないでください。
+ `hms-lambda-handler` – すべての Hive メタストア API コールを処理する一連のデフォルト Lambda ハンドラーです。クラス `MetadataHandler` は、すべての API コールのディスパッチャーです。このパッケージを変更する必要はありません。
+ `hms-lambda-func` – 以下のコンポーネントを持つ Lambda 関数の例です。
+ `HiveMetaStoreLambdaFunc` – `MetadataHandler` を拡張する Lambda 関数の例。
+ `ThriftHiveMetaStoreClient` – Hive メタストアと通信する Thrift クライアント。このクライアントは Hive 2.3.0 用に書かれています。別の Hive バージョンを使用する場合は、このクラスを更新して、応答オブジェクトに互換性があることを確認する必要があります。
+ `ThriftHiveMetaStoreClientFactory` – Lambda 関数の動作を制御します。たとえば、 `getHandlerProvider()` メソッドをオーバーライドして、独自のハンドラープロバイダーを提供できます。
+ `hms.properties` – Lambda 関数を設定します。ほとんどの場合、次の 2 つのプロパティのみを更新する必要があります。
+ `hive.metastore.uris` – `thrift://:9083` 形式の Hive メタストアの URI。
+ `hive.metastore.response.spill.location` - レスポンスオブジェクトのサイズが所定のしきい値 (4 MB など) を超える場合にこれらを保存する Amazon S3 の場所。しきい値はプロパティ `hive.metastore.response.spill.threshold` で定義されます。デフォルト値を変更することは推奨されません。
**注記**
これら 2 つのプロパティは、[Lambda 環境変数](https://docs.aws.amazon.com/lambda/latest/dg/env_variables.html)の `HMS_URIS` および `SPILL_LOCATION` で上書きできます。これらの変数は、異なる Hive メタストアまたはスピルの場所で Lambda 関数を使用するときに、関数のソースコードを再コンパイルする代わりに使用します。
+ `hms-lambda-layer` – `hms-service-api`、`hms-lambda-handler`、およびその依存関係を `.zip` ファイルに入れる Maven アセンブリプロジェクト。`.zip` ファイルは、複数の Lambda 関数による使用のために、Lambda レイヤーとして登録されます。
+ `hms-lambda-rnp` - Lambda 関数からのレスポンスを記録し、それを使用してレスポンスを再生します。このモデルを使用して、テスト用の Lambda レスポンスをシミュレートできます。
## アーティファクトを自分で構築する
ソースコードを変更した後、自分でアーティファクトを構築し、Amazon S3 の場所にアップロードできます。
アーティファクトを構築する前に、`hive.metastore.uris` モジュール内の `hive.metastore.response.spill.location` ファイルにあるプロパティ `hms.properties` および `hms-lambda-func` を更新します。
アーティファクトを構築するには、Apache Maven をインストールし、`mvn install` コマンドを実行する必要があります。これは、モジュール `hms-lambda-layer` の `target` と呼ばれる出力フォルダにレイヤー `.zip` ファイルを生成し、モジュール `hms-lambd-func` に Lambda 関数 `.jar` ファイルを生成します。
# データソースを管理する
Athena コンソールの **[データソースとカタログ]** ページを使用して、作成したデータソースを管理できます。
**データソースを表示する**
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. ナビゲーションペインで、**[データソースとカタログ]** を選択します。
1. データソースのリストから、表示するデータソースの名前を選択します。
**注記**
**[Data source name]** (データソース名) 列の項目は、[ListDataCatalogs](https://docs.aws.amazon.com/athena/latest/APIReference/API_ListDataCatalogs.html) API アクションと [list-data-catalogs](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/athena/list-data-catalogs.html) CLI コマンドの出力に対応しています。
**データソースを編集する**
1. **[データソースとカタログ]** ページで、以下のいずれかを行います。
+ カタログ名の横にあるボタンをクリックした後、**[Actions]** (アクション)、**[Edit]** (編集) の順にクリックします。
+ データソースの名前を選択します。その後、詳細ページで、**[Actions]** (アクション)、**[Edit]** (編集) の順にクリックします。
1. **[Edit]** (編集) ページでは、データソースのために異なる Lambda 関数を選択することや、説明の変更、またはカスタムタグの追加などが行えます。タグの詳細については、[Athena リソースにタグ付けする](tags.md)を参照してください。
1. [**Save**] を選択します。
1. **[AwsDataCatalog]** データソースを編集するには、**[AwsDataCatalog]** のリンクをクリックして、詳細ページを開きます。次にその詳細ページで、カタログを編集する AWS Glue コンソールへのリンクをクリックします。
**データソースを共有するには**
データソース共有に関する情報ついては、以下のリンクをご覧ください。
+ Hive 以外の Lambda ベースのデータソースについては、「[クロスアカウントフェデレーテッドクエリを有効にする](xacct-fed-query-enable.md)」を参照してください。
+ AWS Glue Data Catalog を使用する場合は、「[AWS Glue データカタログへのクロスアカウントアクセスを構成する](security-iam-cross-account-glue-catalog-access.md)」を参照してください。
**データソースを削除するには**
1. **[データソースとカタログ]** ページで、以下のいずれかを行います。
+ カタログ名の横にあるボタンをクリックした上で、**[Actions]** (アクション)、**[Delete]** (削除) の順にクリックします。
+ データソースの名前を選択し、次に詳細ページで **[Actions]** (アクション)、**[Delete]** (削除) の順にクリックします。
**注記**
**AwsDataCatalog** はアカウントにおけるデフォルトのデータソースなので、これを削除することはできません。
データソース、それに対応するデータカタログ、テーブルを削除すると警告が表示され、クエリエディタからはビューが削除されます。このデータソースを使用している保存済みのクエリは、Athena で実行できなくなります。
1. 削除を確認する場合は、データソースの名前を入力した上で **[Delete]** (削除) をクリックします。