调试 SQL 语法错误

当查询返回错误消息时应如何处理。

阅读错误消息不应该像解谜一样。本调试指南将解释如何处理那些顽固不运行的查询。

调试 SQL 查询

如果您的 SQL 查询包含形如 {{ variable }} 的 SQL 变量，请首先参阅SQL 变量故障排除。

1. 转到 SQL 查询中失败的行。
   • 我不知道我的 SQL 查询在哪里失败。.
2. 检查 SQL 查询中失败行的SQL 语法。
3. 如果查询使用了连接、子查询或 CTE，请检查您的查询逻辑。
4. 如果您收到并非特定于 SQL 查询的错误消息，请转到错误消息故障排除。

在深入学习高级 SQL 之前需要快速复习吗？请查看我们的SQL 速查表，了解核心命令和语法。它也非常适合与开始进行数据分析的同事分享。

SQL 调试如何工作？

• SQL 错误消息会显示查询中每个失败的行。您需要按照上述步骤处理每个失败的行。
• 如果您对某行进行了任何更改，请运行您的查询，在继续下一步之前检查问题是否已修复。您可以在查询末尾添加 LIMIT 子句以加快处理速度。
• 请注意，SQL 查询并非自上而下运行，因此您不会按照它们编写的顺序调试查询行。遵循错误消息以帮助您找到需要注意的行。

调试 SQL 语法

1. 检查 SQL 查询中失败行的拼写。
2. 检查 SQL 查询中失败行是否缺少括号或逗号。
3. 删除注释行（以 -- 或 /* 开头的行）。
4. 检查特定于您的 SQL 方言的常见语法错误。

解释

您的数据库必须能够“读取”您的查询才能执行它。

• 正确的拼写告诉您的数据库准确地要查找什么。
• 标点符号告诉您的数据库如何（例如，使用什么顺序）查找数据。
• 注释并非用于读取或执行，但有时尾随的空格或符号可能会意外地干扰相邻行的读取和执行。

常见 SQL 参考指南

开始之前，请打开您正在使用的 SQL 方言的 SQL 参考指南。我们在此处链接了一些最常见的指南：

• MySQL
• PostgreSQL
• Microsoft SQL Server
• Amazon Redshift
• Google BigQuery
• Snowflake
• 我不知道要使用哪种 SQL 方言.

常见 SQL 语法错误

您的错误消息说什么？

• 我的列名或表名“未找到”或“无法识别”.
• 我的 SQL“函数不存在”.

列名或表名“未找到”或“无法识别”

如果您的 SQL 查询包含形如 {{ variable }} 的 SQL 变量，请首先参阅SQL 变量故障排除。

步骤

1. 查看您使用的 SQL 方言的参考指南的结构部分。

   • 您是否使用了正确的引号？例如：

     • SELECT 'column_name'
     • SELECT "column_name"
     • SELECT `column_name`

   • 您是否使用了正确的列和表路径？例如：

     • FROM table_name
     • FROM schema_name.table_name
     • FROM database_name.schema_name.table_name

   • 您的列名是否为保留字？例如：

     在 PostgresSQL 中，'users' 是保留关键字.

     • SELECT users 将会抛出错误。
     • SELECT "users" 将会正确运行。

   • 提示：使用 Metabase 检查列名和表名语法

     1. 在查询构建器中创建一个问题，使用与您的 SQL 问题相同的列和表。
     2. 将问题转换为 SQL.
     3. 查看 Metabase 生成的 SQL 查询如何引用列名和表名。

2. 查看查询中列名和表名的数据参考。

   • 如果列名或表名不存在于数据参考中

     • 运行 SELECT * FROM your_table_name LIMIT 10; 以查找要在查询中使用的列名或表名。
     • 如果您是 Metabase 管理员，请检查数据模型页面以获取原始 schema。

   • 如果列名存在，但您无法从 SQL 编辑器查询该列

     • 询问您的 Metabase 管理员，该列是否在数据库端被重命名或移除。
     • 如果您是 Metabase 管理员，您可能需要运行同步以刷新数据。

解释

您需要确保使用与数据库所用 SQL 方言相符的正确语法。

您的查询还需要使用与数据库中原始名称匹配的列名和表名。Metabase 使用可由 Metabase 管理员更新的显示名称，因此数据参考可能与您的数据库架构不匹配。也可能列或表已在数据库端重命名，但 Metabase 尚未运行同步以获取更新。

延伸阅读

• Metabase 如何执行 SQL 查询
• Metabase 如何与您的数据库同步
• SQL 最佳实践

SQL 函数不存在

如果您的 SQL 查询包含形如 {{ variable }} 的 SQL 变量，请首先参阅SQL 变量故障排除。

步骤

1. 查看您要应用函数的列的数据类型。

   • 您可以使用 Metabase 数据参考来查看列的字段类型（作为数据类型的代理）。
   • 如果您有权访问，也可以直接查询数据库中的信息架构。

2. 查看您的 SQL 方言的参考指南的函数部分。

   • 确认该函数存在于您的 SQL 方言中。
   • 查看您的函数接受的数据类型。

3. 如果您的列的字段类型与函数的预期数据类型不匹配

   • 在您的 SQL 查询中将列转换为正确的数据类型。
   • 如果您是 Metabase 管理员，您也可以从表元数据页面转换数据类型。

解释

SQL 函数旨在处理数据库中的特定数据类型。例如，PostgresSQL 中的 DATE_TRUNC 函数处理 Postgres 数据库中具有 date、timestamp 和 time 类型数据的列。如果您尝试在数据库中对具有 string 数据类型的列使用 DATE_TRUNC 函数，它将不起作用。

请注意，Metabase 字段类型与数据库中的数据类型并非一一对应。在这种情况下，字段类型为您提供了足够的列数据类型信息来排除错误。

延伸阅读

• Metabase 如何执行 SQL 查询
• 字段类型文档
• SQL 最佳实践

如何查找 SQL 查询中失败的行

如果您的 SQL 查询包含形如 {{ variable }} 的 SQL 变量，请首先参阅SQL 变量故障排除。

找到 SQL 查询中失败的行后，请转到调试 SQL 查询下的步骤。

阅读您的 SQL 错误消息

您的错误消息是否

• 告诉您行或字符位置？
• 包含表名或列名？如果表名或列名在查询中出现多次，请减小 SQL 查询的大小。
• 提及 SQL 子句？

减小 SQL 查询的大小

如果您的查询使用

• 子查询（嵌套查询），请单独运行每个子查询。从内部子查询开始，然后向外逐层运行。
• CTE，请单独运行每个 CTE。从您的基本 CTE 开始，然后沿着查询向下运行。
• 指向 Metabase 模型的 SQL 变量，请单独运行每个模型。通过打开变量面板或在 Metabase 搜索栏中输入变量中的模型 ID 号码来访问模型。
• 请记住在尝试隔离问题时阅读 SQL 错误消息。有关更多信息，请转到SQL 调试如何工作？。

SQL 编辑器使用技巧

突出显示 SQL 查询行以

• 使用 Cmd + Return 或 Ctrl + Enter 运行行。
• 使用 Cmd + / 或 Ctrl + / 注释/取消注释行。

如何查找要使用的 SQL 方言

SQL 方言基于存储您要查询的表的数据库。一旦您找出要使用的 SQL 方言，就可以按照调试 SQL 查询下的步骤进行操作。

要找出您正在查询的数据库是哪个

• 如果您是 Metabase 管理员，请前往管理设置 > 数据库，然后查看引擎列。
• 否则，请询问设置您的 Metabase 的人。

您有其他问题吗？

• 我的查询结果不正确.
  • 我的查询结果有重复行.
  • 我的查询结果有缺失行.
  • 我的聚合（计数、求和等）不正确.
• 我的日期和时间不正确.
• 我的数据不是最新的.
• 我有一个不特定于我的SQL查询或语法的错误消息.

您还卡住了吗？

搜索或询问Metabase 社区。