Opção Espaços de indentação

Espaços de indentação define quantos espaços o formatador acrescenta a cada nível de aninhamento. Esta página mostra o que muda entre 2, 4 e 0, como os caracteres de tabulação da entrada são tratados e como escolher um valor que o seu time não precise discutir de novo.

O que a opção faz

O formatador monta o layout de cada instrução do zero, então a indentação que você digitou não é mantida. O que você controla é a largura de um nível de indentação. Esse passo é aplicado em todo lugar em que o layout aninha alguma coisa:

• os itens do select depois do primeiro e os itens seguintes de GROUP BY, ORDER BY, SET e RETURNING;
• os joins sob o FROM, com a condição ON um nível mais para dentro;
• o corpo de uma subconsulta ou CTE dentro dos seus parênteses e a especificação da janela depois de OVER (;
• os argumentos de uma função quando a chamada é quebrada em várias linhas.

Palavras-chave de cláusula como SELECT, FROM e WHERE começam na indentação do bloco ao qual pertencem, e as linhas de AND/OR ficam alinhadas com o seu WHERE. Isso não muda com esta opção; só o tamanho de cada passo muda.

Valores possíveis e padrão

A mesma consulta com o padrão de 4 e com 2. Só os espaços no início das linhas mudam; as quebras de linha são idênticas.

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

Dois espaços ou quatro

Os dois são comuns, e a maioria dos guias de estilo de SQL publicados escolhe um deles e indenta com espaços em vez de tabulações. As diferenças práticas são pequenas, mas reais:

• Quatro espaços deixam cada nível evidente à primeira vista. No exemplo acima, a linha do ON fica oito colunas para dentro, claramente subordinada ao seu join, e o corpo da subconsulta se destaca do WHERE externo. Quem vem de Java, C# ou Python já está acostumado a ler código nessa largura.
• Dois espaços mantêm legíveis as consultas muito aninhadas em telas estreitas e em diffs lado a lado. Uma subconsulta três níveis abaixo começa na coluna 6 em vez da 12, o que deixa mais espaço antes que o limite de quantidade máxima de colunas quebre uma expressão longa. Times que embutem SQL em YAML, em modelos do dbt ou em strings da aplicação costumam preferir essa opção, porque o arquivo hospedeiro já é indentado.

A escolha importa muito menos do que mantê-la. Mudar a largura da indentação de um arquivo existente reescreve os espaços iniciais de quase todas as linhas, o que esconde as mudanças reais numa revisão de código. Se precisar trocar, faça isso num commit que não contenha mais nada, como descrito em formatação para revisão de código e controle de versão.

O que acontece com os caracteres de tabulação

Cada caractere de tabulação da entrada, fora de literais de string e de identificadores entre aspas, é substituído pelo número configurado de espaços antes de a consulta ser montada. No SQL em si isso é invisível, porque o layout é reconstruído de qualquer forma. Onde você percebe é dentro de comentários de várias linhas: uma linha de comentário indentada com uma tabulação fica indentada exatamente por um nível de indentação, então o comentário mantém o seu formato e acompanha o código ao redor.

/*
	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

Indentação 0

Com 0, o formatador continua colocando cada cláusula, item do select, join e condição na sua própria linha e continua aplicando a caixa das palavras-chave e a posição das vírgulas. Ele apenas deixa de indentar:

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

O resultado é fácil de processar linha a linha, mas a estrutura se perde: a única coisa que indica onde a subconsulta começa e termina é o seu par de parênteses. Use 0 quando outra ferramenta reindentar a saída depois, ou quando você só quiser uma saída com um item por linha para uma comparação rápida de texto. Para SQL que pessoas vão ler, 2 ou 4 é a melhor escolha.

Como ela interage com as outras opções

• Quantidade máxima de colunas. A indentação conta na largura da linha. Com uma indentação maior, as linhas aninhadas chegam ao limite antes e são quebradas mais cedo. As linhas de continuação geradas pela quebra sempre recebem 2 espaços a mais, qualquer que seja a indentação escolhida.
• Posição das vírgulas. Com vírgulas à esquerda, cada vírgula fica na coluna da indentação, com o item logo depois dela, então a largura da indentação decide a que distância da margem esquerda fica a coluna de vírgulas.
• Parênteses em nova linha. Quando o parêntese de abertura ganha uma linha própria, o bloco interno continua indentado em um nível.

Escolhendo um valor

Mantenha o padrão de 4, a menos que tenha um motivo para não fazê-lo: é o mais fácil de ler e não precisa de explicação num guia de estilo. Escolha 2 se as suas consultas forem muito aninhadas, se o SQL ficar dentro de arquivos que já são indentados ou se o seu time revisar diffs lado a lado em notebooks. Seja qual for a escolha, registre-a junto com as outras regras do seu guia de estilo de SQL e use o mesmo valor sempre que executar o formatador, para que a formatação nunca apareça sozinha como uma mudança.