# 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)を参照してください。