排查 BigQuery 连接器错误和限制

将数据洞察连接到 BigQuery 时，您可能会遇到超时、SQL 语法限制、配额限制或 VPC Service Controls 错误。本指南介绍了 BigQuery 连接器的常见问题。展开解决步骤 部分，以调查并解决您的问题。

查询和 SQL 语法错误

数据洞察中的自定义 SQL 查询有特定的限制。如果您的查询违反了这些限制，则可能会发生错误。

Field is ambiguous 连接错误

如果您的自定义查询包含重复的列名称，图表会显示以下错误：

User Configuration Error: Field is ambiguous

错误消息文本：用户配置错误

原因： 连接的表 (JOIN) 不能共享重复的列名称。例如，如果您在 Criteria_ID 字段上连接两个具有相同架构的表，生成的虚拟表将包含重复的列（Criteria_ID、Parent_ID、Name），这会触发歧义错误。

解决步骤

使用 AS 关键字或 EXCEPT 子句使所有列名称都是唯一的：

选项 1：使用别名显式重命名重复的字段

SELECT *
FROM (
  SELECT
    Criteria_ID AS Criteria_ID_1,
    Parent_ID AS Parent_ID_1,
    Name AS NAME_1
  FROM
    `project.dataset.table_1` ) AS table_1
LEFT JOIN (
  SELECT
    Criteria_ID AS Criteria_ID_2,
    Parent_ID AS Parent_ID_2,
    Name AS NAME_2
  FROM
    `project.dataset.table_2` ) AS table_2
ON
  table_1.Criteria_ID_1 = table_2.Criteria_ID_2;

选项 2：使用 EXCEPT 排除和重命名特定字段

如果您只需要重命名少量字段，同时保留其余字段，请使用 EXCEPT：

SELECT * EXCEPT (city), city AS city_1 FROM `project.dataset.table_1`

自定义 SQL 查询语法错误（多条语句）

如果您的自定义 SQL 查询包含变量或多条语句（DECLARE、SET），则该查询会失败。

原因： 数据洞察会在外部 SELECT 查询 (SELECT * FROM (<your_custom_sql>)) 中运行您的 SQL。因此，您的查询必须是单个 SELECT 语句。

例如，以下查询会失败，因为它在选择之前声明了一个变量：

DECLARE cost_per_tb_in_dollar FLOAT64 DEFAULT 4.2;
SELECT total_bytes_billed / (1024 * 1024) * cost_per_tb_in_dollar / (1024 * 1024) FROM `billing_table`;

解决步骤

使用通用表表达式（CTE 或 WITH 子句）将计算合并为一条 SELECT 语句：

WITH constants AS (
  SELECT 4.2 AS cost_per_tb_in_dollar
)
SELECT
  total_bytes_billed / (1024 * 1024) * c.cost_per_tb_in_dollar / (1024 * 1024) AS cost
FROM `billing_table`, constants AS c;

性能和查询超时

如果查询运行时间超过 3 到 5 分钟，数据洞察会在收到结果之前超时，并返回：HTTP 504 Gateway timeout。

HTTP 504 Gateway timeout 或长时间运行的查询错误

数据洞察中的自定义查询或复杂的图表聚合可能会在 3 到 5 分钟后超时，并返回 HTTP 504 Gateway timeout 错误。

解决步骤

如果您的查询始终超时，请使用以下优化措施：

  • 启用 BigQuery Storage Read API： 启用 BigQuery Storage Read API 以提高数据吞吐量。
  • 简化查询： 移除不必要的 `JOIN` 命令，按更长的时间段对数据进行分组，并仅选择所需的列。
  • 使用 BigQuery BI Engine： 使用 BigQuery BI Engine 预留容量，以实现亚秒级性能。
  • 使用数据库视图： 将自定义 SQL 保存为 BigQuery 视图 或 物化视图，并将数据洞察直接连接到该视图。
  • 预先聚合到报告表中： 在 BigQuery 中使用定期查询将汇总记录写入单独的表，并查询汇总表。

配额和表限制

当您的数据集包含数千个表或返回数百万条记录时，可能会发生限制错误：

数据集包含 5,000 多个表时，界面响应速度变慢

当您尝试使用数据洞察中的表选择列表连接到 BigQuery 数据集时，界面会冻结或无响应。

原因： 连接器最多支持每个数据集 5,000 个表 。如果数据集超过 5,000 个表或视图，表选择列表会超时并冻结。

解决步骤

使用以下任一替代方案进行连接，而无需加载表列表：

  • 使用自定义查询进行连接： 选择自定义查询 ，然后编写一个不太复杂的 `SELECT` 语句： 
    SELECT * FROM `your_project.your_dataset.your_table`
  • 直接从 BigQuery 进行连接： 在 BigQuery 控制台中，找到您的表，点击导出 或探索数据，然后选择在 Looker Studio 中打开。
  • 拆分或重新整理数据集： 将报告表移到较小的专用报告数据集中，这些数据集包含的表少于 5,000 个。

最多返回 200 万行记录的限制

当您直观呈现大型数据集时，图表可能会显示数据截断警告，或者省略超过 200 万条记录的行。

原因： 连接器每个图表查询最多返回 200 万行记录 。如果查询超过 200 万条记录，图表会截断数据并显示警告。

解决步骤

如需避免数据截断，请执行以下操作：

  • 应用报告级日期过滤条件，以缩小查询量。
  • 查询需要分区过滤条件的日期分区表（`DATE`、`DATETIME`、`TIMESTAMP`）（了解详情）。
  • 在 BigQuery 中对基数较高的维度进行分组，然后再在数据洞察中直观呈现。

MEDIAN 和 PERCENTILE 方差

当您在连接到 BigQuery 的图表中计算确切的中位数 (MEDIAN) 或百分位数 (PERCENTILE) 时，输出结果可能与在其他 SQL 数据库或 CSV 导出中执行的相同计算略有不同。

原因： 在 BigQuery 查询中，MEDIAN 和 PERCENTILE 使用 APPROX_QUANTILES 近似聚合函数。这可以快速处理 PB 级数据集，但近似结果可能与对 CSV 导出或其他 SQL 数据库执行的精确计算略有不同。

数据类型和加密错误

了解如何处理不受支持的列类型和组织强制执行的密钥加密政策。

CONDITION_NOT_MET 加密错误 (CMEK)

当您查询数据集时，图表会失败并返回以下错误：

User Configuration Error: CONDITION_NOT_MET

原因： 连接器不支持客户管理的加密密钥 (CMEK) 。如果组织政策要求对查询或临时存储（组织政策服务）使用 CMEK 加密，图表会显示 User Configuration Error: CONDITION_NOT_MET。

解决步骤

与组织管理员协作，将报告项目从 CMEK 政策中排除，或将报告数据导出到受标准管理的数据集中 Google-owned and Google-managed encryption keys。

不支持 TIME 数据类型

当您连接到包含 TIME 数据类型列（例如 23:59:59）的 BigQuery 表时，数据洞察会将该字段转换为 TEXT，这会阻止基于时间的排序或聚合。

原因： 数据洞察原生不支持 BigQuery 的 TIME 数据类型（例如 23:59:59）。连接器会在提取时将 TIME 列转换为 TEXT 字符串，从而阻止基于时间的排序。

解决步骤

使用以下任一变通方案将 `TIME` 列转换为 DATETIME 对象：

变通方案 1：使用自定义 SQL 查询

直接在 SQL 中将 `TIME` 字段与基本日期 (`1970-01-01`) 组合在一起：

SELECT
  *,
  -- Combine a dummy date (1970-01-01) with your TIME field
  DATETIME(DATE "1970-01-01", your_time_field) AS time_as_datetime
FROM
  `your_project.your_dataset.your_table`
  • 结果： 数据洞察会将 `time_as_datetime` 作为 **日期和时间** 字段提取。
  • 格式设置： 在报告图表属性中，将字段的 **显示格式** 更改为 **小时** 、**分钟** 或自定义时间格式 (`h:mm:ss`)，以便仅显示时间部分（了解详情）。

变通方案 2：在数据洞察中创建计算字段

如果您不修改 SQL 查询，请在数据源中创建计算字段：

PARSE_DATETIME("%H:%M:%S", CAST(your_time_field AS TEXT))
  • 结果： `PARSE_DATETIME` 函数会将文本字符串解析为 **日期和时间** 对象，并将日历日期默认设置为 1970 年 1 月 1 日（了解详情）。

VPC Service Controls 错误

在服务边界内工作时，排查访问遭拒错误和后台进程限制。

在 VPN 关闭的情况下查看报告时出现 Service Control Failure

当您在组织 VPN 或公司网络之外查看报告时，部分或所有图表都会失败，并显示以下错误：

Service Control Failure

原因： 连接器会将报告查看者的 IP 地址传递给 BigQuery，以验证 VPC Service Controls 基于 IP 的访问权限级别。当您复制报告时，副本中的旧版或“幽灵”自定义 SQL 数据源可能会引用受服务边界保护的结算项目，即使您的主要数据集位于边界之外也是如此。

解决步骤

在报告中找出并移除或重新分配任何隐藏的边界绑定结算项目：

  1. 制作受影响报告的副本，以便安全地进行问题排查。
  2. 在副本的报告编辑器中，依次前往资源 > 管理添加的数据源 。
  3. 查看附加到报告的每个嵌入式 **BigQuery** 或 **自定义 SQL** 数据源。
  4. 修改每个自定义 SQL 连接，以验证其配置的 **结算项目** 。如果任何数据源指向受 VPC Service Controls 边界保护的结算项目，请将其更新为使用未受保护的结算项目，或者删除不再使用的数据源。

VPC Service Controls 后面的定时发送的邮件传送或图表提醒失败

当自动化后台功能（例如定时发送的邮件传送或图表提醒）在连接到受 VPC Service Controls 保护的 BigQuery 数据集的图表上执行时，系统会传送定时发送的邮件，但其中不包含报告内容或附件，或者提醒无法触发（VPC Service Controls unexpected field in error map）。

原因： 由于自动化后台功能（例如定时发送的邮件传送或图表提醒）作为后台任务运行，没有最终用户的 IP 地址，因此 VPC Service Controls (VPC-SC) 在评估基于 IP 的访问权限级别时会阻止这些功能 (VPC Service Controls unexpected field in error map)。

解决步骤

如需在 VPC Service Controls 边界后面使用自动化后台功能，请将数据源配置为使用服务账号凭据 ，或创建基于身份的访问权限级别：