# Amazon Athena SAP HANA コネクタ
<a name="connectors-sap-hana"></a>

このコネクタは、Glue データカタログにフェデレーティッドカタログとして登録できます。Lake Formation で定義されたデータアクセスコントロールを、カタログ、データベース、テーブル、列、行、タグレベルでサポートします。このコネクタは、Glue 接続を使用して Glue の設定プロパティを一元管理しています。

## 前提条件
<a name="connectors-saphana-prerequisites"></a>
+ Athena コンソールまたは AWS Serverless Application Repository を使用して AWS アカウント にコネクタをデプロイします。詳細については「[データソース接続を作成する](connect-to-a-data-source.md)」または「[AWS Serverless Application Repository を使用してデータソースコネクタをデプロイする](connect-data-source-serverless-app-repo.md)」を参照してください。

## 制限事項
<a name="connectors-sap-hana-limitations"></a>
+ 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"
  ```

## 用語
<a name="connectors-sap-hana-terms"></a>

SAP HANA コネクタに関連する用語を次に示します。
+ **データベースインスタンス** – オンプレミス、Amazon EC2、または Amazon RDS にデプロイされたデータベースの任意のインスタンス。
+ **ハンドラー** – データベースインスタンスにアクセスする Lambda ハンドラー。ハンドラーには、メタデータ用とデータレコード用があります。
+ **メタデータハンドラー** – データベースインスタンスからメタデータを取得する Lambda ハンドラー。
+ **レコードハンドラー** – データベースインスタンスからデータレコードを取得する Lambda ハンドラー。
+ **複合ハンドラー** — データベースインスタンスからメタデータとデータレコードの両方を取得する Lambda ハンドラー。
+ **プロパティまたはパラメータ** – ハンドラーがデータベース情報を抽出するために使用するデータベースプロパティ。これらのプロパティは Lambda の環境変数で設定します。
+ **接続文字列** – データベースインスタンスへの接続を確立するために使用されるテキスト文字列。
+ **カタログ** – Athena に登録された AWS Glue ではないカタログ。これは、`connection_string` プロパティに必須のプレフィックスです。
+ **マルチプレックスハンドラー** – 複数のデータベース接続を受け入れて使用することが可能な Lambda ハンドラー。

## パラメータ
<a name="connectors-sap-hana-parameters"></a>

このセクションのパラメータを使用して 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 接続 (推奨)
<a name="connectors-sap-hana-gc"></a>

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 のみをサポートします。

### レガシー接続
<a name="connectors-sap-hana-legacy"></a>

#### 接続文字列
<a name="connectors-sap-hana-connection-string"></a>

次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。

```
saphana://${jdbc_connection_string}
```

#### マルチプレックスハンドラーの使用
<a name="connectors-sap-hana-using-a-multiplexing-handler"></a>

マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では以下のクラスを使用します。


****  

| Handler | Class | 
| --- | --- | 
| 複合ハンドラー | SaphanaMuxCompositeHandler | 
| メタデータハンドラー | SaphanaMuxMetadataHandler | 
| レコードハンドラー | SaphanaMuxRecordHandler | 

##### マルチプレックスハンドラーのパラメータ
<a name="connectors-sap-hana-multiplexing-handler-parameters"></a>


****  

| パラメータ | 説明 | 
| --- | --- | 
| \$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 | 

##### 認証情報の提供
<a name="connectors-sap-hana-providing-credentials"></a>

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 プロパティを認識します。

#### 単一接続ハンドラーの使用
<a name="connectors-sap-hana-using-a-single-connection-handler"></a>

次の単一接続のメタデータハンドラーとレコードハンドラーを使用して、単一の SAP HANA インスタンスに接続できます。


****  

| ハンドラーのタイプ | Class | 
| --- | --- | 
| 複合ハンドラー | SaphanaCompositeHandler | 
| メタデータハンドラー | SaphanaMetadataHandler | 
| レコードハンドラー | SaphanaRecordHandler | 

##### 単一接続ハンドラーのパラメータ
<a name="connectors-sap-hana-single-connection-handler-parameters"></a>


****  

| パラメータ | 説明 | 
| --- | --- | 
| default | 必須。デフォルトの接続文字列。 | 

単一接続ハンドラーでは、1 つのデータベースインスタンスがサポートされます。また、`default` 接続文字列パラメータを指定する必要があります。他のすべての接続文字列は無視されます。

Lambda 関数でサポートされる単一の SAP HANA インスタンス用のプロパティ例を次に示します。


****  

| プロパティ | 値 | 
| --- | --- | 
| default | saphana://jdbc:sap://saphana1.host:port/?secret=Test/RDS/Saphana1 | 

#### スピルパラメータ
<a name="connectors-sap-hana-spill-parameters"></a>

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

## サポートされるデータ型
<a name="connectors-sap-hana-data-type-support"></a>

次の表に、JDBC と Apache Arrow に対応するデータ型を示します。


****  

| JDBC | Arrow | 
| --- | --- | 
| ブール値 | Bit | 
| 整数 | Tiny | 
| ショート | Smallint | 
| 整数 | Int | 
| Long | Bigint | 
| float | Float4 | 
| ダブル | Float8 | 
| 日付 | DateDay | 
| タイムスタンプ | DateMilli | 
| String | Varchar | 
| バイト | Varbinary | 
| BigDecimal | 10 進数 | 
| 配列 | リスト | 

## データ型変換
<a name="connectors-sap-hana-data-type-conversions"></a>

JDBC から Arrow への変換に加えて、コネクタは特定の別の変換を実行して SAP HANA ソースと Athena データ型との互換性を保ちます。これらの変換は、クエリを正常に実行するのに役立ちます。次の表に、これらの変換を示します。


****  

| ソースデータタイプ (SAP HANA) | 変換されたデータ型 (Athena) | 
| --- | --- | 
| DECIMAL | BIGINT | 
| INTEGER | INT | 
| DATE | DATEDAY | 
| TIMESTAMP | DATEMILLI | 

その他のサポートされていないデータ型はすべて `VARCHAR` に変換されます。

## パーティションと分割
<a name="connectors-sap-hana-partitions-and-splits"></a>

パーティションは、`Integer` 型の単一パーティション列で表されます。この列には、SAP HANA テーブルで定義されているパーティションのパーティション名が含まれます。パーティション名のないテーブルの場合、\$1 が返されます。これは 1 つのパーティションと同じです。パーティションはスプリットと同等です。


****  

| 名前 | 型 | 説明 | 
| --- | --- | --- | 
| PART\$1ID | 整数 | SAP HANA の名前付きパーティション。 | 

## パフォーマンス
<a name="connectors-sap-hana-performance"></a>

SAP HANA はネイティブパーティションをサポートしています。Athena SAP HANA コネクタは、これらのパーティションからデータを並列に取得できます。均一なパーティション分散の非常に大きなデータセットをクエリする場合は、ネイティブパーティションを強くお勧めします。列のサブセットを選択すると、クエリランタイムが大幅に短縮され、スキャンされるデータが減ります。コネクタでは、同時実行が原因で大幅なスロットリングが発生し、場合によってはクエリに失敗することもあります。

Athena SAP HANA コネクタは述語のプッシュダウンを実行して、クエリによってスキャンされるデータを減少させます。スキャンされるデータ量を削減し、クエリ実行のランタイムを短縮するために、`LIMIT` 句、単純な述語、および複雑な式はコネクタにプッシュダウンされます。

### LIMIT 句
<a name="connectors-saphana-performance-limit-clauses"></a>

`LIMIT N` ステートメントにより、クエリによってスキャンされるデータが削減されます。`LIMIT N` プッシュダウンを使用すると、コネクタは `N` 行のみを Athena に返します。

### 述語
<a name="connectors-saphana-performance-predicates"></a>

述語は、ブール値に照らして評価し、複数の条件に基づいて行をフィルタリングする 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

### 組み合わせたプッシュダウンの例
<a name="connectors-saphana-performance-pushdown-example"></a>

クエリ機能を強化するには、次の例のようにプッシュダウンタイプを組み合わせます。

```
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;
```

## パススルークエリ
<a name="connectors-saphana-passthrough-queries"></a>

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'
        ))
```

## ライセンス情報
<a name="connectors-saphana-license-information"></a>

このコネクタを使用することにより、[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) ファイルに記載されている、個別のサードパーティライセンスの使用条件に同意したとみなされます。

## その他のリソース
<a name="connectors-saphana-additional-resources"></a>

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