问题排查简介

本文档简要介绍了可帮助您排查 BigQuery 中的问题的诊断工具、遥测接口和文档资源。

当您遇到查询失败、性能瓶颈、权限错误、配额限制或数据注入问题时，BigQuery 提供了内置工具来帮助您快速找出根本原因并解决问题。

排查工作流问题

如需有效排查 BigQuery 中的问题，请考虑以下诊断标准：

  1. 确定症状和故障模式。查看任务的结果，确定问题是硬故障（例如错误代码或作业失败）、性能下降（例如查询缓慢或槽位不足）、权限拒绝还是意外的费用差异。
  2. 检查作业执行详情。使用 Google Cloud 控制台作业浏览器、查询执行图或命令行工具检查阶段级时间、槽分配和错误详细信息。您还可以让 Gemini Cloud Assist 调查您的问题。
  3. 分析遥测数据和元数据。查询信息架构视图或检查 Cloud Audit Logs，将作业行为与资源争用、预留限制或管理更改相关联。
  4. 应用有针对性的缓解措施。使用特定于类别的问题排查指南或防御性 SQL 函数来解决根本原因。

区分问题排查与优化

使用 BigQuery 时，请务必区分问题排查、性能优化和最佳实践：

  • 问题排查。重点关注诊断和解决意外故障、运行时错误、流水线损坏、配额耗尽或导致作业无法成功完成的意外行为。
  • 性能优化。专注于提高已成功运行的查询和工作负载的执行速度、延迟时间或资源效率。如需了解详情，请参阅优化查询性能。
  • 最佳实践。重点介绍数据建模、存储、安全和费用管理的架构和设计模式。如需了解详情，请参阅最佳实践简介。

诊断工具

以下部分介绍了多个 BigQuery 界面和自动化工具，可帮助您诊断工作负载中的问题。

可视化和控制台工具

以下工具可帮助您从Google Cloud 控制台排查 BigQuery 问题。

  • 作业探索器。无需编写 SQL 查询，即可在项目或组织中搜索、过滤和检查过去和正在运行的作业。您可以查看出错提示、槽用量、执行时间轴和作业元数据。如需了解详情，请参阅在 Jobs Explorer 中监控作业。
  • 查询执行图。检查查询的分阶段可视化执行计划。执行图可帮助您识别瓶颈，例如 shuffle 溢出到磁盘、计算受限阶段、数据倾斜或输入/输出延迟。如需了解详情，请参阅获取查询性能数据分析。
  • Query Insights 和资源图表。查看槽利用率、作业并发和预留分配的实时和历史图表，以诊断容量限制。如需了解详情，请参阅使用管理资源图表。
  • Gemini Cloud Assist in BigQuery。获取 AI 辅助的上下文分析，了解失败的查询和性能瓶颈。Gemini Cloud Assist 会直接在Google Cloud 控制台中解释错误代码、突出显示有问题的 SQL 语法，并建议修复步骤。如需了解详情，请参阅使用 Gemini Cloud Assist 排查查询问题。

命令行和自动化诊断工具

以下工具可帮助您通过命令行界面诊断 BigQuery 问题。

  • bq 命令行工具。使用 bq show -j <var>JOB_ID</var> 命令或向查询命令添加 --format=prettyjson 标志，检查详细的错误结构、请求 ID 和作业元数据。如需了解详情，请参阅排查 CLI 命令问题。
  • gcpdiag 工具。从命令行运行自动化诊断，以检测常见的 Google Cloud 配置问题，包括 IAM 权限缺口、网络限制和服务账号错误。如需了解详情，请参阅使用 gcpdiag 排查查询失败问题。

元数据和遥测视图

借助信息架构视图，您可以使用标准 SQL 查询有关作业、容量、流式注入和数据集的实时和历史元数据。这些视图包括：

如需了解详情，请参阅 BigQuery INFORMATION_SCHEMA 简介。

Cloud Monitoring 和 Cloud Audit Logs

  • Cloud Audit Logs。查看管理员活动和数据访问审核日志，以跟踪谁发起了特定操作、检查调用方身份并诊断 PERMISSION_DENIED 错误。如需了解详情，请参阅 BigQuery 审核日志记录参考文档。
  • Cloud Monitoring。跟踪槽用量、查询执行时长和上传的字节数等指标，并配置提醒政策，以便在超出阈值或配额时通知您的团队。如需了解详情，请参阅使用 Cloud Monitoring 监控 BigQuery。

防御性 SQL 函数和调试语句

为防止查询因运行时数据错误而意外失败，请使用以下方法：

  • 安全表达式。使用 SAFE_CAST()、SAFE_DIVIDE()、SAFE_OFFSET() 和 SAFE_ORDINAL() 可在数据类型或数组边界不匹配时返回 NULL，而不是生成运行时错误。大多数标量函数都支持 SAFE. 前缀。如需了解详情，请参阅调试函数和 SAFE. 前缀。
  • SQL 断言。在多语句事务或脚本中使用 ASSERT 语句，以强制执行数据验证条件，并在下游操作执行之前失败并显示自定义错误消息。如需了解详情，请参阅调试语句。

按问题类别排查问题

从以下部分中选择一个类别，查看详细的错误代码、根本原因和分步解决指南。

查询性能和执行

诊断无法运行、超时、遇到资源限制或出现意外延迟的查询。

Identity and Access Management (IAM) 和安全性

诊断访问权限控制失败、角色分配缺失和数据治理政策屏蔽问题。

配额、速率限制和预留

解决工作负载超出 BigQuery 服务限制或容量分配的问题。

数据注入、流式传输和传输

诊断加载数据、流式传输记录或同步外部来源时发生的故障。

  • 排查数据传输问题。 诊断 BigQuery Data Transfer Service 问题、专用转移作业的网络连接问题以及 CSV 数据加载错误。
  • 排查转移作业配置问题。解决 Amazon Simple Storage Service (Amazon S3)、Salesforce、Google Ads 和 Cloud Storage 等来源的 BigQuery Data Transfer Service 服务配置错误。
  • 排查 BigQuery Storage API 问题。 调试 BigQuery Storage Read API、BigQuery Storage Write API (gRPC) 和 BigQuery Storage Write API (REST) 流式注入失败、行级插入错误和吞吐量配额。
  • 排查架构错误。 解决加载、查询、复制和架构更新操作中的架构不匹配错误（例如缺少、重复或不兼容的列更改），以及 15 级架构、文件和例程嵌套深度限制。

数据仓库迁移

诊断在评估、转换外部数据仓库或将其迁移到 BigQuery 时遇到的问题。

  • 排查迁移问题。 解决迁移评估错误、交互式和批量 SQL 转换问题以及元数据提取失败问题。

外部数据源和联合查询

诊断在 BigQuery 外部查询数据时出现的连接、身份验证和执行错误。

账单和费用差异

调查计算和存储方面的意外费用和账单差异。

数据丢失缓解

如需恢复已更改或已删除的历史数据，或在区域服务中断期间维持业务连续性，请使用以下灾难恢复和数据保留工具：

  • 恢复数据。查询或恢复在时间旅行窗口内更改或删除的表数据。如需了解详情，请参阅恢复数据。
  • 时间旅行。在配置的保留期限内保留数据集中更新或删除的数据，以帮助防止意外修改。如需了解详情，请参阅时间旅行。
  • 区域故障切换。在使用 BigQuery 托管式灾难恢复时，在区域性服务中断期间将次要副本提升为主副本。如需了解详情，请参阅区域级故障切换。

使用 API

以编程方式与 BigQuery 交互时，请使用以下资源来优化请求延迟时间并管理上传工作流：

  • API 性能提示。遵循进行 API 调用的最佳实践，例如管理连接池、使用批量操作和处理重试。如需了解详情，请参阅 API 性能提示。
  • API 上传。使用 REST API 可续传和分段上传请求排查和管理数据注入问题。如需了解详情，请参阅 API 上传。

身份验证和 ADC

如需排查使用应用默认凭据 (ADC) 时可能遇到的常见问题，请参阅排查 ADC 设置问题。

后续步骤