Opção Parênteses em nova linha

Parênteses em nova linha controla onde fica o parêntese de abertura quando ele inicia um bloco indentado: no fim da linha que o introduz (o padrão) ou numa linha só dele. Esta página mostra exatamente quais parênteses mudam de lugar, com a saída real das duas configurações.

O que a opção faz

Quando o formatador abre um bloco entre parênteses, como uma subconsulta depois de IN, ele indenta o conteúdo em um nível e coloca o parêntese de fechamento numa linha própria. A única questão que resta é onde fica o parêntese de abertura:

• Desligada (padrão): ele fica no fim da linha que o introduz, como em WHERE id IN (.
• Ligada: a linha que o introduz termina com a palavra-chave (WHERE id IN), e o parêntese ganha uma linha própria, na mesma indentação da linha à qual pertence.

O conteúdo e o parêntese de fechamento são montados da mesma forma nos dois modos. Só um caractere muda de lugar.

Valores possíveis e padrão

Subconsulta depois de IN

É o caso mais comum. Compare a linha depois de WHERE id IN nas duas saídas:

select name, email from customers where id in (select customer_id from orders where total > 500 and status = 'PAID')

SELECT name,
    email
FROM customers
WHERE id IN (
    SELECT customer_id
    FROM orders
    WHERE total > 500
    AND status = 'PAID'
)

SELECT name,
    email
FROM customers
WHERE id IN
(
    SELECT customer_id
    FROM orders
    WHERE total > 500
    AND status = 'PAID'
)

Com a opção ligada, os parênteses de abertura e de fechamento ficam na mesma coluna, um em cima do outro, com a subconsulta entre eles.

CTEs e tabelas derivadas

O corpo de uma common table expression e uma tabela derivada no FROM se comportam da mesma forma. A linha WITH recent AS e a linha do FROM perdem o parêntese, que vai para a linha seguinte:

with recent as (select customer_id, sum(total) as total from orders where created_at >= current_date - 90 group by customer_id) select x.region, sum(x.total) as region_total from (select t.region, r.total from recent r join territories t on t.customer_id = r.customer_id) x group by x.region

WITH recent AS (
    SELECT customer_id,
        SUM(total) AS total
    FROM orders
    WHERE created_at >= CURRENT_DATE - 90
    GROUP BY customer_id
)
SELECT x.region,
    SUM(x.total) AS region_total
FROM (
    SELECT t.region,
        r.total
    FROM recent r
        JOIN territories t
            ON  t.customer_id = r.customer_id
) x
GROUP BY x.region

WITH recent AS
(
    SELECT customer_id,
        SUM(total) AS total
    FROM orders
    WHERE created_at >= CURRENT_DATE - 90
    GROUP BY customer_id
)
SELECT x.region,
    SUM(x.total) AS region_total
FROM
(
    SELECT t.region,
        r.total
    FROM recent r
        JOIN territories t
            ON  t.customer_id = r.customer_id
) x
GROUP BY x.region

O mesmo acontece com a lista de colunas e a lista de VALUES de um INSERT e com as definições de colunas de um CREATE TABLE, que o formatador também monta como blocos indentados. Uma lista de uma coluna só, como INSERT INTO t (id), fica na mesma linha e não muda de lugar.

Chamadas de função e listas de valores

A opção olha para o layout, não para o tipo de parêntese. Qualquer parêntese que abre um bloco indentado muda de lugar, e qualquer parêntese que fica na mesma linha permanece onde está. A única exceção é a especificação de uma janela: OVER ( fica sempre na linha da sua função, nos dois modos.

select id, count(*) as items, coalesce(discount_code, 'NONE') as discount, (select max(shipped_at) from shipments s where s.order_id = o.id) as last_shipment from orders o where status in ('PAID', 'SHIPPED') group by id, discount_code

SELECT id,
    COUNT(*) AS items,
    COALESCE(
        discount_code,
        'NONE'
    ) AS discount,
    (
        SELECT
            MAX(shipped_at)
        FROM shipments s
        WHERE s.order_id = o.id
    ) AS last_shipment
FROM orders o
WHERE status IN (
    'PAID',
    'SHIPPED'
)
GROUP BY id,
    discount_code

SELECT id,
    COUNT(*) AS items,
    COALESCE
    (
        discount_code,
        'NONE'
    ) AS discount,
    (
        SELECT
            MAX(shipped_at)
        FROM shipments s
        WHERE s.order_id = o.id
    ) AS last_shipment
FROM orders o
WHERE status IN
(
    'PAID',
    'SHIPPED'
)
GROUP BY id,
    discount_code

Neste exemplo:

• COUNT(*) e MAX(shipped_at) ficam numa linha só, então os seus parênteses não são alterados.
• COALESCE é quebrada com um argumento por linha, então, com a opção ligada, o seu parêntese vai para a linha seguinte, com a mesma indentação do nome da função.
• A lista de valores IN ('PAID', 'SHIPPED') também é quebrada com um valor por linha, e o seu parêntese muda de lugar exatamente como o de uma subconsulta.
• A subconsulta escalar na lista do select já começa com o parêntese numa linha própria, então as duas saídas são idênticas nesse ponto.

Quando ligar a opção

As duas configurações são o equivalente, em SQL, ao debate sobre a posição das chaves nas linguagens derivadas do C.

Mantenha a opção desligada para ter uma saída compacta, parecida com a maior parte do SQL que aparece na documentação e nos guias de estilo publicados, em que WITH name AS ( e IN ( são a forma usual de escrever. Cada bloco ocupa uma linha a menos, e a palavra-chave que abre o bloco continua visualmente ligada a ele. O parêntese de fechamento fica alinhado com o início da linha que abriu o bloco, o que basta para encontrar o par na maioria das consultas.

Ligue a opção quando trabalhar com consultas longas e muito aninhadas e quiser casar os parênteses visualmente. Como os parênteses de abertura e de fechamento compartilham a mesma coluna, as guias de indentação do editor ou uma passada rápida de olho na vertical mostram onde cada bloco começa e termina. Alguns times também acham que uma palavra-chave sozinha no fim da linha (IN, AS, FROM) sinaliza claramente que um bloco vem a seguir.

Os custos são uma linha extra por bloco, o que pesa em consultas com muitas CTEs, e chamadas de função que ficam com uma leitura um pouco incomum, com COALESCE numa linha e o seu parêntese na seguinte. Se a maioria dos seus blocos longos for de CTEs e subconsultas, a troca pode valer a pena; se a maioria for de chamadas de função quebradas, o padrão costuma ficar mais legível.

Opções relacionadas

A indentação dentro de cada bloco vem dos espaços de indentação e não muda com esta opção. Mudar o parêntese de lugar não deixa nenhuma linha mais longa, então nunca gera quebras adicionais pela quantidade máxima de colunas. A posição das vírgulas e a caixa das palavras-chave se aplicam normalmente ao conteúdo do bloco. Para orientações mais amplas sobre como estruturar consultas aninhadas, CTEs e subconsultas antes de formatá-las, veja formatação de consultas complexas, e experimente as duas configurações no seu próprio SQL no formatador: a troca é feita com um clique.