# 페더레이션 패스스루 쿼리 사용
<a name="federated-query-passthrough"></a>

Athena에서는 데이터 소스 자체의 쿼리 언어를 사용하여 페더레이션 데이터 소스에서 쿼리를 실행하고 실행을 위해 전체 쿼리를 데이터 소스로 푸시다운할 수 있습니다. 이러한 쿼리를 패스스루 쿼리라고 합니다. 패스스루 쿼리를 실행하려면 Athena 쿼리에서 테이블 함수를 사용합니다. 데이터 소스에서 실행할 패스스루 쿼리를 테이블 함수의 인수 중 하나에 포함시킵니다. 패스스루 쿼리는 Athena SQL을 사용하여 분석할 수 있는 테이블을 반환합니다.

## 지원되는 커넥터
<a name="federated-query-passthrough-supported-connectors"></a>

다음 Athena 데이터 소스 커넥터는 패스스루 쿼리를 지원합니다.
+ [Azure 데이터 레이크 스토리지](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`로 설정합니다.