“缩进空格”选项

Indent spaces sets how many spaces the formatter adds for each level of nesting. This page shows what changes between 2, 4 and 0, how tab characters in your input are handled, and how to pick a value your team will not have to argue about again.

What the option does

The formatter builds the layout of every statement from scratch, so the indentation you typed is not kept. What you control is the width of one indentation step. That step is applied wherever the layout nests something:

• select items after the first one, and the continuation items of GROUP BY, ORDER BY, SET and RETURNING;
• joins under FROM, with the ON condition one step further in;
• the body of a subquery or CTE inside its parentheses, and the window specification after OVER (;
• function arguments when a call is split over several lines.

Clause keywords such as SELECT, FROM and WHERE start at the indentation of the block they belong to, and AND/OR lines line up with their WHERE. That does not change with this option; only the size of each step does.

Possible values and default

The same query with the default of 4 and with 2. Only the leading whitespace differs; line breaks are identical.

select c.name, sum(o.total) as revenue from customers c join orders o on o.customer_id = c.id where o.status = 'PAID' and c.id in (select customer_id from loyalty_members where tier = 'GOLD') group by c.name order by revenue desc

SELECT c.name,
    SUM(o.total) AS revenue
FROM customers c
    JOIN orders o
        ON  o.customer_id = c.id
WHERE o.status = 'PAID'
AND c.id IN (
    SELECT customer_id
    FROM loyalty_members
    WHERE tier = 'GOLD'
)
GROUP BY c.name
ORDER BY revenue DESC

SELECT c.name,
  SUM(o.total) AS revenue
FROM customers c
  JOIN orders o
    ON  o.customer_id = c.id
WHERE o.status = 'PAID'
AND c.id IN (
  SELECT customer_id
  FROM loyalty_members
  WHERE tier = 'GOLD'
)
GROUP BY c.name
ORDER BY revenue DESC

Two spaces or four

Both are common, and most published SQL style guides pick one of the two and indent with spaces rather than tabs. The practical differences are small but real:

• Four spaces make each level obvious at a glance. In the example above, the ON line sits eight columns in, clearly subordinate to its join, and the subquery body stands apart from the outer WHERE. Developers coming from Java, C# or Python already read code at this width.
• Two spaces keep deeply nested queries readable on narrow screens and in side-by-side diffs. A subquery three levels down starts at column 6 instead of 12, which leaves more room before the maximum columns limit wraps a long expression. Teams that embed SQL in YAML, dbt models or application strings often prefer it because the host file is already indented.

The choice matters far less than keeping it. Changing the indent width of an existing file rewrites the leading whitespace of almost every line, which buries real changes in a code review. If you need to switch, do it in a commit that contains nothing else, as described in formatting for code review and version control.

What happens to tab characters

Every tab character in the input, outside string literals and quoted identifiers, is replaced by the configured number of spaces before the query is laid out. For the SQL itself this is invisible, because the layout is rebuilt anyway. Where you notice it is inside multi-line comments: a comment line indented with one tab ends up indented by exactly one indentation step, so the comment keeps its shape and matches the code around it.

/*
	Customers created in the last 30 days
		owner: data team
*/
select id,
	email,
	created_at
from customers
where	created_at >= current_date - 30

/*
    Customers created in the last 30 days
        owner: data team
*/
SELECT id,
    email,
    created_at
FROM customers
WHERE created_at >= CURRENT_DATE - 30

/*
  Customers created in the last 30 days
    owner: data team
*/
SELECT id,
  email,
  created_at
FROM customers
WHERE created_at >= CURRENT_DATE - 30

Indent 0

With 0, the formatter still puts each clause, select item, join and condition on its own line and still applies keyword case and comma placement. It just stops indenting:

SELECT c.name,
SUM(o.total) AS revenue
FROM customers c
JOIN orders o
ON  o.customer_id = c.id
WHERE o.status = 'PAID'
AND c.id IN (
SELECT customer_id
FROM loyalty_members
WHERE tier = 'GOLD'
)
GROUP BY c.name
ORDER BY revenue DESC

The result is easy to process line by line, but the structure is gone: the only thing that tells you where the subquery starts and ends is its pair of parentheses. Use 0 when another tool re-indents the output afterwards, or when you only want one-item-per-line output for a quick text comparison. For SQL that people will read, 2 or 4 is the better choice.

How it interacts with other options

• Maximum columns. Indentation counts toward the line width. With a larger indent, nested lines reach the limit sooner and wrap earlier. Wrapped continuation lines always get 2 extra spaces, whatever indent you choose.
• Comma placement. With leading commas, each comma sits at the indentation column with the item right after it, so the indent width decides how far the column of commas is from the left margin.
• Parentheses on new line. When the opening parenthesis gets its own line, the block inside is still indented by one step.

Choosing a value

Keep the default of 4 unless you have a reason not to: it is the easiest to read and needs no explanation in a style guide. Pick 2 if your queries nest deeply, if SQL lives inside already-indented files, or if your team reviews diffs side by side on laptops. Whatever you choose, write it down next to the other rules in your SQL style guide and use the same value every time you run the formatter, so that formatting never shows up as a change on its own.