# 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=<{{number of decimal places}}>` を指定します。 ## 用語 Oracle コネクタに関連する用語を次に示します。 + **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。 + **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。 + **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。 + **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。 + **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。 + **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。 + **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。 + **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。 + **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。 ## パラメータ このセクションのパラメータを使用して Oracle コネクタを設定します。 ### AWS Glue Data Catalog フェデレーションコネクタ Glue 接続オブジェクトを使用して Oracle コネクタを設定することをお勧めします。そのためには、Oracle コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。 **Glue 接続プロパティ** 次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。 ``` aws glue describe-connection-type --connection-type ORACLE ``` **Lambda 環境プロパティ** 次の Lambda 環境プロパティは、お客様のアカウントの Lambda 関数でコネクタを使用する場合にのみ適用されます。 + **glue\_connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。 + **is\_fips\_enabled** – (オプション) FIPS モードが有効になっている場合は True に設定します。デフォルトは False です。 + **casing\_mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。 + **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。これは、グルー接続が関連付けられているコネクタのデフォルトです。 + **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。これは、グルー接続が関連付けられていないコネクタのデフォルトです。 + **case\_insensitive\_search** – Oracle のスキーマ名とテーブル名に対して大文字と小文字を区別しない検索を実行します。クエリにコネクタのデフォルトの大文字と小文字に一致しないスキーマ名またはテーブル名が含まれている場合は、この値を使用します。 **注記** AWS Glue Data Catalog フェデレーション接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。 AWS Glue Data Catalog フェデレーション接続を使用して作成された Oracle コネクタは、マルチプレックスハンドラーの使用をサポートしていません。 AWS Glue Data Catalog フェデレーション接続を使用して作成された Oracle コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。 ### Athena データカタログフェデレーションコネクタ **注記** 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\_connection\_string** – マルチプレックスハンドラーによって使用されます (Glue 接続を使用する場合はサポートされていません)。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myoraclecatalog の場合、環境変数の名前は myoraclecatalog\_connection\_string になります。 + **spill\_bucket** – Lambda 関数の上限を超えたデータに対して、Amazon S3 バケットを指定します。 + **spill\_prefix** – (オプション) 指定された `athena-federation-spill` という `spill_bucket` の、デフォルトのサブフォルダに設定します。このロケーションで、Amazon S3 の[ストレージライフサイクル](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)を設定し、あらかじめ決められた日数または時間数以上経過したスピルを削除することをお勧めします。 + **spill\_put\_request\_headers** – (オプション) スピリングに使用される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\_key\_id** – (オプション) デフォルトでは、Amazon S3 に送信されるすべてのデータは、AES-GCM で認証された暗号化モードとランダムに生成されたキーを使用して暗号化されます。KMS が生成したより強力な暗号化キー (例えば `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`) を Lambda 関数に使用させる場合は、KMS キー ID を指定します。 + **disable\_spill\_encryption** – (オプション) `True` に設定されている場合、スピルに対する暗号化を無効にします。デフォルト値は `False` です。この場合、S3 にスピルされたデータは、AES-GCM を使用して (ランダムに生成されたキー、または KMS により生成したキーにより) 暗号化されます。スピル暗号化を無効にすると、特にスピルされる先で[サーバー側の暗号化](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)を使用している場合に、パフォーマンスが向上します。 + **is\_fips\_enabled** – (オプション) FIPS モードが有効になっている場合は True に設定します。デフォルトは False です。 + **casing\_mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。 + **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。これは、グルー接続が関連付けられているコネクタのデフォルトです。 + **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。これは、グルー接続が関連付けられていないコネクタのデフォルトです。 + **case\_insensitive\_search** – 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:${Test/RDS/Oracle}@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\_DATA=(SID=))(SECURITY=(SSL\_SERVER\_CERT\_DN=))) | #### 認証情報の提供 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 | ##### マルチプレックスハンドラーのパラメータ **** | パラメータ | 説明 | | --- | --- | | ${{catalog}}\_connection\_string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが myoraclecatalog の場合、環境変数の名前は myoraclecatalog\_connection\_string になります。 | | default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:${{{AWS\_LAMBDA\_FUNCTION\_NAME}}} の場合に使用されます。 | `oracle1` (デフォルト) と `oracle2` の 2 つのデータベースインスタンスをサポートする Oracle MUX Lambda 関数用のプロパティを次に示します。 **** | プロパティ | 値 | | --- | --- | | default | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog1\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog2\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle2}@//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\_EQUAL、LESS\_THAN、LESS\_THAN\_OR\_EQUAL、GREATER\_THAN、GREATER\_THAN\_OR\_EQUAL、IS\_NULL + **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、NEGATE + **その他: **LIKE\_PATTERN、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)を参照してください。