# Amazon Athena Google BigQuery 连接器
<a name="connectors-bigquery"></a>

适用于 Google [BigQuery](https://cloud.google.com/bigquery/) 的 Amazon Athena 连接器使 Amazon Athena 能够对您的 Google BigQuery 数据运行 SQL 查询。

此连接器可以作为联合目录注册到 Glue Data Catalog。此连接器支持 Lake Formation 中在目录、数据库、行和标签级别定义的数据访问控制。此连接器使用 Glue 连接将配置属性集中保存到 Glue 中。

## 先决条件
<a name="connectors-bigquery-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-bigquery-limitations"></a>
+ Lambda 函数的最大超时值为 15 分钟。每次拆分都会在 BigQuery 上执行一次查询，并且必须有足够的时间来存储结果，以便 Athena 读取。如果 Lambda 函数超时，查询将失败。
+ Google BigQuery 区分大小写。连接器尝试更正数据集名称、表名称和项目 ID。这很有必要，因为 Athena 所有元数据均采用小写形式。这些更正对 Google BigQuery 进行了许多额外的调用。
+ 不支持 Binary 数据类型。
+ 由于 Google BigQuery 的并发和配额限制，连接器可能会遇到 Google 配额限制问题。为了避免这些问题，请尽可能多地向 Google BigQuery 施加限制。有关 BigQuery 配额的信息，请参阅 Google BigQuery 文档中的 [配额和限制](https://cloud.google.com/bigquery/quotas)。

## 参数
<a name="connectors-bigquery-parameters"></a>

使用本节中的参数来配置 Google BigQuery 连接器。

### Glue 连接（推荐）
<a name="bigquery-gc"></a>

我们建议您使用 Glue 连接对象来配置 Google BigQuery 连接器。要执行此操作，请将 Google BigQuery 连接器 Lambda 的 `glue_connection` 环境变量设置为要使用的 Glue 连接的名称。

**Glue 连接属性**

使用以下命令来获取 Glue 连接对象的架构。此架构包含可用于控制连接的所有参数。

```
aws glue describe-connection-type --connection-type BIGQUERY
```

**Lambda 环境属性**

**glue\$1connection** – 指定与联合连接器关联的 Glue 连接的名称。

**注意**  
所有使用 Glue 连接的连接器都必须使用 AWS Secrets Manager 来存储凭证。
使用 Glue 连接创建的 Google BigQuery 连接器不支持使用多路复用处理程序。
使用 Glue 连接创建的 Google BigQuery 连接器仅支持 `ConnectionSchemaVersion` 2。

### 旧连接
<a name="bigquery-legacy"></a>

**注意**  
2024 年 12 月 3 日及之后创建的 Athena 数据来源连接器使用 AWS Glue 连接。

下面列出的参数名称和定义适用于在没有关联 Glue 连接器时创建的 Athena 数据来源连接器。仅在[手动部署](connect-data-source-serverless-app-repo.md)早期版本的 Athena 数据来源连接器或未指定 `glue_connection` 环境属性时才使用以下参数。

**Lambda 环境属性**
+ **spill\$1bucket** - 为超出 Lambda 函数限制的数据指定 Amazon S3 存储桶。
+ **spill\$1prefix** -（可选）默认为指定 `spill_bucket`（称为 `athena-federation-spill`）中的子文件夹。我们建议您在此位置配置 Amazon S3 [存储生命周期](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html)，以删除早于预定天数或小时数的溢出内容。
+ **spill\$1put\$1request\$1headers** —（可选）用于溢出的 Amazon S3 `putObject` 请求的请求标头和值的 JSON 编码映射（例如 `{"x-amz-server-side-encryption" : "AES256"}`)。有关其他可能的标头，请参阅《[Amazon Simple Storage Service API 参考](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)》中的 *PutObject*。
+ **kms\$1key\$1id** -（可选）默认情况下，将使用经过 AES-GCM 身份验证的加密模式和随机生成的密钥对溢出到 Amazon S3 的任何数据进行加密。要让您的 Lambda 函数使用 KMS 生成的更强的加密密钥（如 `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`），您可以指定 KMS 密钥 ID。
+ **disable\$1spill\$1encryption** -（可选）当设置为 `True` 时，将禁用溢出加密。默认值为 `False`，此时将使用 AES-GCM 对溢出到 S3 的数据使用进行加密 - 使用随机生成的密钥，或者使用 KMS 生成密钥。禁用溢出加密可以提高性能，尤其是当您的溢出位置使用[服务器端加密](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html)时。
+ **gcp\$1project\$1id** - 项目 ID（不是项目名称），包含连接器应从中读取的数据集（例如 `semiotic-primer-1234567`)。
+ **secret\$1manager\$1gcp\$1creds\$1name** - AWS Secrets Manager 中的密钥名称，包含 JSON 格式的 BigQuery 凭证（例如 `GoogleCloudPlatformCredentials`)。
+ **big\$1query\$1endpoint** –（可选）BigQuery 私有端点的 URL。如果您想通过私有端点访问 BigQuery，使用此参数。

## 拆分与视图
<a name="connectors-bigquery-splits-and-views"></a>

由于 BigQuery 连接器使用 BigQuery 存储读取 API 来查询表，而 BigQuery 存储 API 不支持视图，所以该连接器使用具有单个视图拆分功能的 BigQuery 客户端。

## 性能
<a name="connectors-bigquery-performance"></a>

为了查询表，BigQuery 连接器使用了 BigQuery 存储读取 API，该 API 使用基于 RPC 的协议，支持快速访问 BigQuery 托管存储。有关 BigQuery 存储读取 API 的更多信息，请参阅 Google Cloud 文档中的[使用 BigQuery 存储读取 API 读取表格数据](https://cloud.google.com/bigquery/docs/reference/storage)。

选择列的子集可以显著减少查询运行时及扫描的数据。随着并发增加，连接器容易出现查询失败，并且通常是慢速连接器。

Athena Google BigQuery 连接器执行谓词下推，以减少查询扫描的数据。`LIMIT` 子句、`ORDER BY` 子句、简单谓词和复杂表达式将下推到连接器，以减少扫描数据量并缩短查询执行的运行时间。

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

`LIMIT N` 语句用于减少查询扫描的数据量。`LIMIT N` 下推时，连接器仅向 Athena 返回 `N` 行。

### 前 N 个查询
<a name="connectors-bigquery-performance-top-n-queries"></a>

前 `N` 个查询用于指定结果集的顺序以及返回的行数限值。您可以使用此类查询确定数据集的前 `N` 个最大值或前 `N` 个最小值。前 `N` 个查询下推时，连接器仅向 Athena 返回 `N` 个已排序行。

### Predicates
<a name="connectors-bigquery-performance-predicates"></a>

谓词是 SQL 查询的 `WHERE` 子句中的表达式，其评估结果为布尔值并根据多个条件筛选行。Athena Google BigQuery 连接器可以组合这些表达式并将其直接推送到 Google BigQuery，以增强功能并减少扫描数据量。

以下 Athena Google BigQuery 连接器运算符支持谓词下推：
+ **布尔值：**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
+ **算术：**ADD、SUBTRACT、MULTIPLY、DIVIDE、MODULUS、NEGATE
+ **其他：**LIKE\$1PATTERN、IN

### 组合下推示例
<a name="connectors-bigquery-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%') 
ORDER BY col_a DESC 
LIMIT 10;
```

## 传递查询
<a name="connectors-bigquery-passthrough-queries"></a>

Google BigQuery 连接器支持[传递查询](federated-query-passthrough.md)。传递查询使用表函数将完整查询下推到数据来源来执行查询。

要在 Google BigQuery 中执行传递查询，可以使用以下语法：

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

以下示例查询将查询下推到 Google BigQuery 中的数据来源。该查询选择了 `customer` 表中的所有列，将结果限制为 10。

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

## 许可证信息
<a name="connectors-bigquery-license-information"></a>

Amazon Athena Google BigQuery 连接器项目已获得 [Apache-2.0 许可证](https://www.apache.org/licenses/LICENSE-2.0.html)授权。

使用此连接器，即表示您确认包含第三方组件（这些组件的列表可在此连接器的 [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/pom.xml) 文件中找到），并同意 GitHub.com 上的 [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-google-bigquery/LICENSE.txt) 文件中提供的相应第三方许可证中的条款。

## 其他资源
<a name="connectors-bigquery-additional-resources"></a>

有关此连接器的更多信息，请访问 GitHub.com 上的[相应站点](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-google-bigquery)。