# 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)する場合にのみ、以下のパラメータを使用します。 ### AWS Glue Data Catalog フェデレーションコネクタ Glue 接続オブジェクトを使用して Synapse コネクタを設定することをお勧めします。そのためには、Oracle コネクタ Lambda の `glue_connection` 環境変数を、使用する Glue 接続の名前に設定します。 **Glue 接続プロパティ** 次のコマンドを使用して、Glue 接続オブジェクトのスキーマを取得します。このスキーマには、接続を制御するために使用できるすべてのパラメータが含まれています。 ``` aws glue describe-connection-type --connection-type SYNAPSE ``` **Lambda 環境プロパティ** 次の Lambda 環境プロパティは、お客様のアカウントの Lambda 関数でコネクタを使用する場合にのみ適用されます。 + **glue\_connection** – フェデレーションコネクタに関連付けられた Glue 接続の名前を指定します。 + **casing\_mode** – (オプション) スキーマ名とテーブル名の大文字と小文字の区別を処理する方法を指定します。`casing_mode` パラメータは、次の値を使用して大文字と小文字の区別に関する動作を指定します。 + **none** – 指定されたスキーマ名とテーブル名の大文字と小文字は変更しないでください。これは、グルー接続が関連付けられているコネクタのデフォルトです。 + **upper** – 指定されたすべてのスキーマ名とテーブル名を大文字にします。 + **lower** – 指定されたすべてのスキーマ名とテーブル名を小文字にします。 **注記** AWS Glue Data Catalog フェデレーション接続を使用するすべてのコネクタは、認証情報を保存するために AWS Secrets Manager を使用する必要があります。 AWS Glue Data Catalog フェデレーション接続を使用して作成された Synapse コネクタは、マルチプレックスハンドラーの使用をサポートしていません。 AWS Glue Data Catalog フェデレーション接続を使用して作成された Synapse コネクタは、`ConnectionSchemaVersion` 2 のみをサポートします。 ### Athena データカタログフェデレーションコネクタ #### 接続文字列 次の形式の JDBC 接続文字列を使用して、データベースインスタンスに接続します。 ``` synapse://${{{jdbc_connection_string}}} ``` #### マルチプレックスハンドラーの使用 マルチプレクサーを使用すると、単一の Lambda 関数から複数のデータベースインスタンスに接続できます。各リクエストはカタログ名によりルーティングされます。Lambda では次のクラスを使用します。 **** | Handler | Class | | --- | --- | | 複合ハンドラー | SynapseMuxCompositeHandler | | メタデータハンドラー | SynapseMuxMetadataHandler | | レコードハンドラー | SynapseMuxRecordHandler | ##### マルチプレックスハンドラーのパラメータ **** | パラメータ | 説明 | | --- | --- | | ${{catalog}}\_connection\_string | 必須。データベースインスタンスの接続文字列。環境変数には、Athena で使用されているカタログの名前をプレフィックスします。例えば、Athena に登録されたカタログが mysynapsecatalog の場合、環境変数の名前は mysynapsecatalog\_connection\_string になります。 | | default | 必須。デフォルトの接続文字列。この文字列は、カタログが lambda:${{{AWS\_LAMBDA\_FUNCTION\_NAME}}} の場合に使用されます。 | `synapse1` (デフォルト) と `synapse2` の 2 つのデータベースインスタンスをサポートする Synapse MUX Lambda 関数用のプロパティを次に示します。 **** | プロパティ | 値 | | --- | --- | | default | synapse://jdbc:synapse://synapse1.hostname:port;databaseName={{}};${{{secret1\_name}}} | | synapse\_catalog1\_connection\_string | synapse://jdbc:synapse://synapse1.hostname:port;databaseName={{}};${{{secret1\_name}}} | | synapse\_catalog2\_connection\_string | synapse://jdbc:synapse://synapse2.hostname:port;databaseName={{}};${{{secret2\_name}}} | ##### 認証情報の提供 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} を含んでいます。 ``` 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={{}};${{{secret\_name}}} | #### 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]** を選択します。 ![](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\_bucket | 必須。スピルバケット名。 | | spill\_prefix | 必須。スピルバケットのキープレフィックス | | 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)」を参照してください。 | ## サポートされるデータ型 次の表に、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\_EQUAL、LESS\_THAN、LESS\_THAN\_OR\_EQUAL、GREATER\_THAN、GREATER\_THAN\_OR\_EQUAL、NULL\_IF、IS\_NULL + **Arithmetic: **ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、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%'); ``` ## パススルークエリ 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)を参照してください。