# フェデレーテッドパススルークエリを使用する
<a name="federated-query-passthrough"></a>

Athena では、データソース自体のクエリ言語を使用してフェデレーテッドデータソースに対するクエリを実行したり、実行のためにクエリ全体をデータソースにプッシュダウンしたりすることができます。これらのクエリはパススルークエリと呼ばれます。パススルークエリを実行するには、Athena クエリでテーブル関数を使用します。データソースで実行するパススルークエリは、テーブル関数に対する引数の 1 つに含めます。パススルークエリは、Athena SQL を使用して分析できるテーブルを返します。

## サポートされるコネクタ
<a name="federated-query-passthrough-supported-connectors"></a>

以下の Athena データソースコネクタがパススルークエリをサポートしています。
+ [Azure Data Lake Storage](connectors-adls-gen2.md)
+ [Azure Synapse](connectors-azure-synapse.md)
+ [Cloudera Hive](connectors-cloudera-hive.md)
+ [Cloudera Impala](connectors-cloudera-impala.md)
+ [CloudWatch](connectors-cloudwatch.md)
+ [Db2](connectors-ibm-db2.md)
+ [Db2 iSeries](connectors-ibm-db2-as400.md)
+ [DocumentDB](connectors-docdb.md) 
+ [DynamoDB](connectors-dynamodb.md) 
+ [HBase](connectors-hbase.md)
+ [Google BigQuery](connectors-bigquery.md)
+ [Hortonworks](connectors-hortonworks.md)
+ [MySQL](connectors-mysql.md)
+ [Neptune](connectors-neptune.md)
+ [OpenSearch](connectors-opensearch.md) 
+ [Oracle](connectors-oracle.md)
+ [PostgreSQL](connectors-postgresql.md)
+ [Redshift](connectors-redshift.md)
+ [SAP HANA](connectors-sap-hana.md)
+ [Snowflake](connectors-snowflake.md)
+ [SQL Server](connectors-microsoft-sql-server.md)
+ [Teradata](connectors-teradata.md)
+ [Timestream](connectors-timestream.md)
+ [Vertica](connectors-vertica.md)

## 考慮事項と制限事項
<a name="federated-query-passthrough-considerations-and-limitations"></a>

Athena でパススルークエリを使用するときは、以下の点を考慮してください。
+ クエリパススルーがサポートされるのは、Athena `SELECT` ステートメントまたは読み取り操作のみです。
+ クエリのパフォーマンスは、データソースの設定に応じて異なる場合があります。
+ クエリパススルーは、Lake Formation のきめ細かなアクセスコントロールをサポートしていません。
+ パススルークエリは、[Glue データカタログとして登録](register-connection-as-gdc.md)されているデータソースではサポートされていません。

## 構文
<a name="federated-query-passthrough-syntax"></a>

以下は、一般的な Athena クエリパススルー構文です。

```
SELECT * FROM TABLE(catalog.system.{{function_name}}({{arg1}} => '{{arg1Value}}'[, {{arg2}} => '{{arg2Value}}', ...]))
```

次の点に注意してください。
+ **catalog** – ターゲット Athena フェデレーションコネクタ名またはデータカタログ名。
+ **system** – 関数を含む名前空間。すべての Athena コネクタ実装で、この名前空間が使用されます。
+ **function\_name** – パススルークエリをデータソースにプッシュダウンする関数の名前。これはよく `query` と呼ばれます。組み合わせ `catalog.system.function_name` は、関数の完全解決パスです。
+ **arg1、arg2 など** – 関数の引数。ユーザーはこれらの引数を関数に渡す必要があります。ほとんどの場合、これはデータソースに渡されるクエリ文字列です。

ほとんどのデータソースでは、`query` が最初で唯一の引数であり、その後にアロー演算子 `=>` とクエリ文字列が続きます。

```
SELECT * FROM TABLE(catalog.system.query(query => 'query string'))
```

オプションの名前付き引数 `query` とアロー演算子 `=>` は、簡素化のために省略することが可能です。

```
SELECT * FROM TABLE(catalog.system.query('query string'))
```

クエリがターゲットカタログのコンテキスト内で実行されている場合、`catalog` 名を削除することでクエリをさらに簡素化できます。

```
SELECT * FROM TABLE(system.query('query string'))
```

データソースがクエリ文字列以上のものを必要とする場合は、データソースが期待する順序で名前付き引数を使用してください。たとえば、`{{arg1}} => '{{arg1Value}}'` 式には最初の引数とその値が含まれます。{{arg1}} という名前はデータソースに固有のもので、コネクタによって異なる場合があります。

```
SELECT * FROM TABLE(
        system.query(
            {{arg1}} => '{{arg1Value}}',
            {{arg2}} => '{{arg2Value}}',
            {{arg3}} => '{{arg3Value}}'
        ));
```

引数名を省略することで、上記を簡素化することもできます。ただし、メソッドの署名の順序に従う必要があります。関数の署名の詳細については、各コネクタのドキュメントを参照してください。

```
SELECT * FROM TABLE(catalog.system.query('arg1Value', 'arg2Value', 'arg3Value'))
```

次の例のように、完全な関数解決パスを利用することで、異なる Athena コネクタ間で複数のパススルークエリを実行できます。

```
SELECT c_customer_sk 
    FROM TABLE (postgresql.system.query('select * from customer limit 10'))
UNION
SELECT c_customer_sk 
    FROM TABLE(dynamodb.system.query('select * from customer')) LIMIT 10
```

パススルークエリは、フェデレーションビューの一部として使用できます。同じ制限が適用されます。詳細については、「[フェデレーテッドビューをクエリする](https://docs.aws.amazon.com/athena/latest/ug/running-federated-queries.html#running-federated-queries-federated-views)」を参照してください。

```
CREATE VIEW catalog.database.ViewName AS
    SELECT * FROM TABLE (
        catalog.system.query('query')
    )
```

特定のコネクタで使用する正確な構文については、個々のコネクタのドキュメントを参照してください。

### 引用符の使用
<a name="federated-query-passthrough-syntax-quotation-marks"></a>

引数値 (渡すクエリ文字列を含む) は、以下の例にあるように、一重引用符で囲む必要があります。

```
SELECT * FROM TABLE(system.query(query => 'SELECT * FROM testdb.persons LIMIT 10'))
```

クエリ文字列が二重引用符で囲まれていると、クエリは失敗します。以下のクエリは、COLUMN\_NOT\_FOUND: line 1:43: Column 'select \* from testdb.persons limit 10' cannot be resolved というエラーメッセージで失敗します。

```
SELECT * FROM TABLE(system.query(query => "SELECT * FROM testdb.persons LIMIT 10"))
```

一重引用符をエスケープするには、元の引用符に一重引用符を追加します (`terry's_group` を `terry''s_group` にするなど)。

## 例
<a name="federated-query-passthrough-sql-based-connectors-examples"></a>

以下のクエリ例は、データソースにクエリをプッシュダウンします。クエリは `customer` テーブル内のすべての列を選択し、結果を 10 個に制限します。

```
SELECT * FROM TABLE(
        catalog.system.query(
            query => 'SELECT * FROM customer LIMIT 10;'
        ))
```

以下のステートメントは同じクエリを実行しますが、オプションの名前付き引数 `query` とアロー演算子 `=>` を削除します。

```
SELECT * FROM TABLE(
        catalog.system.query(
            'SELECT * FROM customer LIMIT 10;'
        ))
```

これは、再利用しやすいようにフェデレーションビュー内にカプセル化することもできます。ビューで使用する場合は、完全な関数解決パスを使用する必要があります。

```
CREATE VIEW AwsDataCatalog.default.example_view AS
    SELECT * FROM TABLE (
        catalog.system.query('SELECT * FROM customer LIMIT 10;')
    )
```

## クエリパススルーのオプトアウト
<a name="federated-query-passthrough-sql-based-connectors-opting-out"></a>

パススルークエリを無効にするには、`enable_query_passthrough` という名前の Lambda 環境変数を追加し、`false` に設定します。