Opção Palavras-chave

A caixa das palavras-chave reescreve as palavras-chave do SQL em maiúsculas (o padrão) ou em minúsculas. Esta página lista exatamente o que tem a caixa alterada e o que fica como você digitou, incluindo algumas palavras que se comportam de um jeito diferente do que você talvez espere.

O que a opção faz

O formatador reconhece as palavras-chave do SQL e escreve cada uma delas na caixa escolhida, não importa como foram digitadas. Select, select e SELECT viram SELECT com a configuração padrão e select com minúsculas. Tudo o que não é palavra-chave mantém a grafia original, então a opção nunca altera os nomes das suas tabelas, colunas ou aliases, a menos que eles próprios sejam palavras-chave não qualificadas, um caso tratado numa seção própria mais abaixo.

Valores possíveis e padrão

A entrada abaixo mistura maiúsculas e minúsculas de propósito. Compare as duas saídas:

-- Active customers: keep this comment as written
Select id, Coalesce(nickname, first_name) as display_name, count(*) as logins, upper(email) as email_upper, Round(avg(session_minutes), 1) as avg_minutes
From customer_logins
Where is_active = TRUE and deleted_at Is Null and plan_code <> 'select from where'
Group By id, nickname, first_name, email

-- Active customers: keep this comment as written
SELECT id,
    COALESCE(
        nickname,
        first_name
    ) AS display_name,
    COUNT(*) AS logins,
    upper(email) AS email_upper,
    Round(
        AVG(session_minutes),
        1
    ) AS avg_minutes
FROM customer_logins
WHERE is_active = true
AND deleted_at IS NULL
AND plan_code <> 'select from where'
GROUP BY id,
    nickname,
    first_name,
    email

-- Active customers: keep this comment as written
select id,
    coalesce(
        nickname,
        first_name
    ) as display_name,
    count(*) as logins,
    upper(email) as email_upper,
    Round(
        avg(session_minutes),
        1
    ) as avg_minutes
from customer_logins
where is_active = true
and deleted_at is null
and plan_code <> 'select from where'
group by id,
    nickname,
    first_name,
    email

O que tem a caixa alterada

• Palavras-chave de cláusula e de operador: SELECT, FROM, WHERE, GROUP BY, AS, AND, IS, IN, JOIN, ON, NOT, EXISTS, LIKE, ILIKE e assim por diante.
• Palavras de DDL e de upsert: PRIMARY KEY, FOREIGN KEY, REFERENCES, CONSTRAINT, UNIQUE, CHECK, DEFAULT, INDEX, CASCADE, RESTRICT, TRUNCATE, TRIGGER, SEQUENCE, SCHEMA e as palavras de ON CONFLICT … DO NOTHING.
• Limitação de linhas e frames de janela: FETCH FIRST/FETCH NEXT, ROWS ONLY, WITH TIES, RECURSIVE, ROWS, UNBOUNDED, PRECEDING, FOLLOWING e CURRENT ROW.
• NULL, que segue a configuração como qualquer outra palavra-chave: IS NULL ou is null.
• Nomes de tipos de dados como INTEGER, TEXT ou DATE, inclusive depois de um cast :: do PostgreSQL.
• Alguns nomes de função: as agregações COUNT, SUM, AVG, MIN e MAX, além de COALESCE, EXTRACT e CAST, são tratadas como palavras-chave e seguem a configuração.
• Palavras-chave dentro de corpos com dollar quoting do PostgreSQL. Funções e blocos DO escritos entre marcadores $$ são formatados como PL/pgSQL, e as suas palavras-chave BEGIN, IF, END IF e similares também têm a caixa alterada. Veja o guia de formatação para PostgreSQL.

O que fica como foi escrito

• Literais de string. No exemplo, 'select from where' não é alterado em nenhuma das saídas. Texto entre aspas é dado, e alterá-lo mudaria o resultado da consulta.
• Comentários. Tanto os comentários -- quanto os /* */ são copiados como estão, mesmo quando contêm palavras-chave.
• A maioria dos nomes de função. Funções que não estão na lista acima, como UPPER, ROUND, NOW, NULLIF e as suas próprias funções, mantêm a caixa que você digitou. No exemplo, upper(email) continua em minúsculas na saída em maiúsculas, e Round(...) mantém o R maiúsculo nas duas. Se você quer nomes de função consistentes, digite-os de forma consistente.
• Identificadores entre aspas. Nomes entre aspas duplas, entre crases do MySQL ou entre colchetes do SQL Server, como "Order Id", "select", `order` ou [dbo].[orders], são copiados exatamente, mesmo quando a palavra dentro deles é uma palavra-chave. Na maioria dos bancos de dados, um nome entre aspas diferencia maiúsculas de minúsculas, então alterar a sua caixa faria a consulta apontar para outro objeto.
• Nomes qualificados. Cada parte de um nome com ponto mantém a caixa digitada: t.month continua t.month e Sales.Orders continua Sales.Orders.
• Nomes de tabelas, colunas e aliases que não são palavras-chave.

Identificadores que são palavras-chave

Para um nome isolado, o formatador decide pela palavra, não pelo papel dela na instrução. Um nome sem aspas e não qualificado que também é palavra-chave tem a caixa alterada como uma palavra-chave, seja ele um alias ou uma coluna escrita sem qualificador de tabela. A mesma palavra depois de um qualificador, como em p.month, ou entre aspas, como em "month", fica intacta. Palavras como month, value, date e plan estão nessa lista, embora muitos bancos de dados as aceitem como nomes comuns:

select p.id, extract(month from p.paid_at) as month, p.amount as value, p.paid_at::date as date, p.status from payments p

SELECT p.id,
    EXTRACT(MONTH FROM p.paid_at) AS MONTH,
    p.amount AS VALUE,
    p.paid_at::DATE AS DATE,
    p.status
FROM payments p

select p.id,
    extract(month from p.paid_at) as month,
    p.amount as value,
    p.paid_at::date as date,
    p.status
from payments p

Com palavras-chave em minúsculas, nada de visível acontece. Com maiúsculas, os aliases viram MONTH, VALUE e DATE. No PostgreSQL, no MySQL e no Oracle, nomes de coluna e aliases sem aspas não diferenciam maiúsculas de minúsculas, então a consulta roda da mesma forma. O SQL Server segue a collation do banco: com uma collation case-sensitive, um nome de coluna com a caixa alterada deixa de corresponder à coluna; por isso, qualifique essa coluna (p.date) ou coloque-a entre aspas, e ela mantém a caixa digitada. O rótulo da coluna no resultado também pode mudar: o MySQL e o SQL Server devolvem o alias exatamente como foi escrito, então um cliente que procura as colunas pelo nome diferenciando maiúsculas de minúsculas veria MONTH em vez de month. O PostgreSQL converte nomes sem aspas para minúsculas e o Oracle para maiúsculas, então, para eles, o rótulo é o mesmo nos dois casos.

A forma mais simples de evitar a questão é dar aos aliases nomes descritivos que não sejam palavras-chave: paid_month, amount_paid, paid_on. Isso já é uma boa prática de qualquer forma, porque nomes que são palavras-chave confundem tanto as pessoas quanto as ferramentas.

Maiúsculas ou minúsculas

Palavras-chave em maiúsculas são a convenção de longa data. A maior parte da documentação dos bancos de dados as usa, e muitos guias de estilo de times as recomendam porque elas separam a linguagem dos nomes à primeira vista, mesmo em texto puro sem destaque de sintaxe: num e-mail, num arquivo de log ou num terminal.

As minúsculas ganharam espaço, principalmente em times de analytics e de engenharia de dados. Os argumentos são que todo editor moderno já destaca as palavras-chave, que minúsculas são mais fáceis de digitar e que uma consulta toda em maiúsculas parece gritar mais do que o necessário. Se a maior parte do seu SQL vive dentro do código da aplicação, ao lado de identificadores em minúsculas, as minúsculas também podem parecer mais naturais ali.

Nenhuma das escolhas afeta a execução da consulta. O que importa é usar a mesma caixa em todo lugar, para que um diff nunca mostre uma linha alterada só porque alguém digitou select em vez de SELECT. Escolha uma no seu guia de estilo e deixe o formatador garantir que ela seja seguida. A configuração combina livremente com as outras opções: espaços de indentação, quantidade máxima de colunas, posição das vírgulas e parênteses em nova linha.