调试 SQL 语法错误

当查询返回错误消息时该怎么做。

使用 Metabase 学习 SQL

免费下载 Metabase，或注册 Metabase Cloud 免费试用版

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

调试 SQL 查询

如果您的 SQL 查询包含看起来像 {{ variable }} 的 SQL 变量，请先前往《SQL 变量故障排除》。

1. 转到 SQL 查询中失败的那一行。
   • 我不知道我的 SQL 查询在哪里失败了.
2. 检查 SQL 查询中失败那一行的SQL 语法。
3. 如果查询使用连接、子查询或 CTE，请检查您的查询逻辑。
4. 如果您收到一个与您的 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 管理员，请在数据模型页面检查原始架构。

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

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

解释

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

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

进一步阅读

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

SQL 函数不存在

如果您的 SQL 查询包含看起来像 {{ variable }} 的 SQL 变量，请先前往《SQL 变量故障排除》。

步骤

1. 检查您希望函数应用于的列的数据类型。

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

2. 检查您的 SQL 方言参考指南中的“函数”部分。

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

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

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

解释

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

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

进一步阅读

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

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

如果您的 SQL 查询包含看起来像 {{ variable }} 的 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 社区。

下一步：调试 SQL 查询逻辑

当您的查询返回看起来不正确的数据时该怎么做。

下一篇文章