前提条件用語パラメータ AWS Glue でのデータベースとテーブルのセットアップ SQL クエリの実行パフォーマンスパススルークエリ追加リソース

Amazon Athena OpenSearch コネクタ

OpenSearch Service

Amazon Athena OpenSearch コネクタは、Amazon Athena でのOpenSearch インスタンスとの通信を可能にし、OpenSearch データを SQL でクエリできるようにします。

注記

既知の問題により、OpenSearch コネクタは VPC では使用できません。

アカウントで Lake Formation を有効にしている場合、AWS Serverless Application Repository でデプロイした Athena フェデレーション Lambda コネクタの IAM ロールには、Lake Formation での AWS Glue Data Catalog への読み取りアクセス権が必要です。

前提条件

Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウントにコネクタをデプロイします。詳細については、「データソースコネクタをデプロイする」または「AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする」を参照してください。

用語

OpenSearch コネクタに関連する用語を次に示します。

ドメイン – このコネクタが OpenSearch インスタンスのエンドポイントに関連付ける名前。ドメインはデータベース名としても使用されます。Amazon OpenSearch Service 内で定義されている OpenSearch インスタンスの場合、ドメインは自動検出可能です。他のインスタンスでは、ドメイン名とエンドポイント間のマッピングを指定する必要があります。
インデックス – OpenSearch インスタンスで定義されているデータベーステーブル。
マッピング – インデックスがデータベーステーブルの場合、マッピングはそのスキーマ (すなわち、フィールドと属性の定義) です。

このコネクタは、OpenSearch インスタンスからのメタデータ取得と AWS Glue Data Catalog からのメタデータ取得の両方をサポートします。OpenSearch ドメインとインデックス名に一致する AWS Glue データベースとテーブルをコネクタが検出した場合、コネクタはそれらをスキーマ定義に使用しようとします。AWS Glue テーブルは、OpenSearch インデックスのすべてのフィールドのスーパーセットになるように作成することをお勧めします。
ドキュメント – データベーステーブル内のレコード。
データストリーム — 複数のバッキングインデックスで構成される時間ベースのデータ。詳細については、OpenSearch ドキュメントの「Data Streams」および、「Amazon OpenSearch Service 開発者ガイド」の「Data Streams の使用開始」を参照してください。

注記
データストリームインデックスは OpenSearch によって内部で作成管理されるため、コネクタは最初の使用可能なインデックスからスキーママッピングを選択します。このため、補足メタデータのソースとして AWS Glue テーブルを設定することを強く推奨します。詳細については、「AWS Glue でのデータベースとテーブルのセットアップ」を参照してください。

パラメータ

このセクションの Lambda 環境変数を使用して OpenSearch コネクタを設定します。

spill_bucket – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。
spill_prefix – (オプション) 指定された athena-federation-spill という spill_bucket の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 のストレージライフサイクルを設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。
spill_put_request_headers – (オプション) スピリングに使用されるAmazon S3 の putObject リクエスト (例:{"x-amz-server-side-encryption" : "AES256"}) に関する、 JSON でエンコードされたリクエストヘッダーと値のマッピング。利用可能な他のヘッダーについては、「Amazon Simple Storage Service API リファレンス」の「PutObject」を参照してください。
kms_key_id – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (たとえば a7e63k4b-8loc-40db-a2a1-4d0en2cd8331) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。
disable_spill_encryption – (オプション) True に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は False です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先でサーバー側の暗号化を使用している場合に、パフォーマンスが向上します。
disable_glue – (オプション) これが存在し、true に設定されている場合、コネクタは AWS Glue からの補足メタデータ取得は試みません。
query_timeout_cluster – 並列スキャンの生成に使用されるクラスターヘルスクエリのタイムアウト時間 (秒単位)。
query_timeout_search – インデックスからのドキュメントの取得に使用される検索クエリのタイムアウト時間 (秒単位)。
auto_discover_endpoint – ブール値。デフォルト: 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_mapping – auto_discover_endpoint が false に設定されている場合にのみ使用され、ドメイン名とそれに関連付けられているエンドポイントとのマッピングを定義します。domain_mapping 変数は、次の形式の複数の OpenSearch エンドポイントに対応できます。
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...       
```
OpenSearch エンドポイントへの認証を目的として、コネクタは AWS Secrets Manager から取得したユーザー名とパスワードを含む ${SecretName}: の形式を使用して挿入された置換文字列をサポートします。式の最後のコロン (:) は、エンドポイントの残りの部分との区切り文字として機能します。

重要
セキュリティ上のベストプラクティスとして、環境変数や接続文字列にハードコードされた認証情報を使用しないでください。ハードコードされたシークレットを AWS Secrets Manager に移動する方法については、「AWS Secrets Manager ユーザーガイド」の「ハードコードされたシークレットを AWS Secrets Manager に移動する」を参照してください。

次の例では、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_float	BIGINT	SCALED_FLOAT(...)
integer	INT	整数
short	SMALLINT	smallint
バイト	TINYINT	tinyint
double	FLOAT8	double
float、half_float	FLOAT4	float
ブール値	BIT	ブール値
date、date_nanos	DATEMILLI	timestamp
JSON の構造	STRUCT	STRUCT
_meta (詳細については、「OpenSearch での配列のメタデータの定義」セクションを参照してください)	LIST	配列

データ型に関する注意事項

現在、コネクタは OpenSearch と前の表にリストされている AWS Glue データタイプのみをサポートしています。
scaled_float は、浮動小数点数を固定の double 型のスケーリング係数でスケーリングしたもので、Apache Arrow では BIGINT として表されます。たとえば、0.756 は、スケーリング係数が 100 の場合、四捨五入されて 76 になります。
AWS Glue で scaled_float を定義するには、列に array 型を選択し、SCALED_FLOAT(スケーリング係数) という形式を使用してフィールドを宣言する必要があります。

有効な例を次に示します。
```
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_name は 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 インスタンスから取得したクラスターヘルス情報を使用して、ドキュメント検索クエリに対する複数のリクエストを生成します。リクエストはシャードごとに分割され、同時に実行されます。

また、コネクタはドキュメント検索クエリの一部として述語をプッシュダウンします。次のクエリと述語の例は、コネクタがどのように述語プッシュダウンを使用するかを示しています。

Query


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 コネクタは、パススルークエリをサポートし、Query DSL 言語を使用します。Query DSL を使用したクエリの詳細については、Elasticsearch ドキュメントの「Query DSL」、または OpenSearch ドキュメントの「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」を参照してください。
このコネクタに関するその他の情報については、GitHub.com で対応するサイトを参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Neptune

Oracle