如何使用 SQL Formatter 设置缩进并大写 SQL 关键字

用 SQL Formatter 整理查询文本

SQL Formatter 用于整理 SQL 文本的排版：在解析和格式化成功时，它会重新缩进内容，并将 SQL 关键字改为大写。适合在提交代码、撰写文档或检查查询结构前，先把一段难以阅读的 SQL 整理成更清晰的形式。它只处理输入文本的格式，不执行 SQL，也不连接数据库。

操作步骤与参数设置

1. 在 SQL 输入区域粘贴 SQL 文本。输入必须是字符串；如果不填写，输入默认为空值。仅包含空白字符的输入也可以提交，并会得到空的格式化结果。

2. 设置缩进参数。默认值为 2。对于非空白 SQL，系统会先把该值转换为整数；转换失败，或转换后的数值小于 0、大于 8 时，会改用 2，其他转换后的数值会被采用。空白输入会在这项转换之前直接返回。

3. 如有方言选项，可填写一个通用方言值，但不要把它当作方言解析器选择。当前格式化路径接受该输入，却不应用方言特定的解析或排版规则。

4. 执行格式化并查看输出。输入超过 1,000,000 个 UTF-8 字节，或输入不是字符串时，会在格式化前被拒绝。非空输入还可能因为无法找到 SQL 语句、解析组件不可用，或解析排版过程中发生异常而失败。

5. 如果使用旧版参数名提供 SQL，只有在主要 SQL 输入为空时，该值才会被采用。格式化多条已解析语句时，输出会用分号和换行连接，并在末尾增加一个分号。

如何理解格式化结果

成功结果表示输入文本已经按照当前路径重新排版，并使用了大写 SQL 关键字。多条语句的结果应呈现为分号加换行的连接形式，末尾还有一个分号。不要据此判断查询能否执行、结果是否正确，或某种 SQL 方言是否被验证。

如果结果为空，先确认输入是否只有空白字符；这种输入本来就会产生空的格式化结果。若非空内容失败，检查输入类型、大小和语句是否能被解析，再尝试降低内容复杂度。格式化可能改变原始排版，因此应在提交或保存前复核语句结构。

使用示例

你准备把一条多行 SELECT 查询放入代码审查说明中，希望先统一缩进并突出 SQL 关键字。

将一条包含小写关键字和嵌套条件的 SELECT 查询粘贴到输入区域，设置缩进为 4，然后执行格式化。

输出中的 SQL 关键字为大写，查询层级按所用缩进重新排列；若包含多条语句，它们之间以分号和换行分隔，末尾带一个分号。

使用限制

• 方言输入不会启用方言特定规则；非空内容可能因解析或格式化问题失败。格式化结果不能证明 SQL 可执行，也不代表查询结果已经验证。

常见错误

• 把方言选项当成方言专用格式化开关，可能导致对输出能力的预期过高。请将其视为可接受的输入，并在格式化失败或输出不符合预期时检查 SQL 是否能被当前解析路径处理。

常见问题

缩进值可以设置为多少？

当输入不是空白内容时，缩进值会先转换为整数；转换失败或结果低于 0、超过 8 时使用 2，其他转换后的数值会被采用。空白输入会直接返回，不经过这项转换。

填写 SQL 方言后会使用对应的格式化规则吗？

可以填写方言值，但当前格式化路径不会据此应用方言特定的解析或排版规则，因此不能把该选项当作方言验证或专用格式化开关。

不输入 SQL 或输入过大的内容会怎样？

如果 SQL 输入只含空白字符，工具会接受它并返回空的格式化结果；如果输入非空但不是字符串，或超过 1,000,000 个 UTF-8 字节，则会被拒绝。