Opción Palabras clave

La opción Palabras clave reescribe las palabras clave de SQL en mayúsculas (el valor predeterminado) o en minúsculas. Esta página detalla exactamente qué se cambia y qué se deja tal como lo escribiste, incluidas algunas palabras que no se comportan como podrías esperar.

Qué hace la opción

El formateador reconoce las palabras clave de SQL y escribe cada una de ellas en la forma elegida, sin importar cómo se hayan escrito. Select, select y SELECT se convierten todas en SELECT con la configuración predeterminada y en select con minúsculas. Todo lo que no es palabra clave conserva su escritura original, así que la opción nunca cambia los nombres de tus tablas, columnas o alias, salvo que ellos mismos sean palabras clave sin calificar, un caso que se trata en su propia sección más abajo.

Valores posibles y valor predeterminado

La entrada de abajo mezcla mayúsculas y minúsculas a propósito. Compara las dos salidas:

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

Qué se cambia

• Palabras clave de cláusulas y operadores: SELECT, FROM, WHERE, GROUP BY, AS, AND, IS, IN, JOIN, ON, NOT, EXISTS, LIKE, ILIKE, etcétera.
• Palabras de DDL y de upsert: PRIMARY KEY, FOREIGN KEY, REFERENCES, CONSTRAINT, UNIQUE, CHECK, DEFAULT, INDEX, CASCADE, RESTRICT, TRUNCATE, TRIGGER, SEQUENCE, SCHEMA y las palabras de ON CONFLICT … DO NOTHING.
• Limitación de filas y marcos de ventana: FETCH FIRST/FETCH NEXT, ROWS ONLY, WITH TIES, RECURSIVE, ROWS, UNBOUNDED, PRECEDING, FOLLOWING y CURRENT ROW.
• NULL, que sigue la configuración como cualquier otra palabra clave: IS NULL o is null.
• Nombres de tipos de datos como INTEGER, TEXT o DATE, incluso después de un cast :: de PostgreSQL.
• Algunos nombres de funciones: las funciones de agregación COUNT, SUM, AVG, MIN y MAX, además de COALESCE, EXTRACT y CAST, se tratan como palabras clave y siguen la configuración.
• Palabras clave dentro de cuerpos de PostgreSQL entre dólares. Las funciones y los bloques DO escritos entre marcadores $$ se formatean como PL/pgSQL, y sus palabras clave BEGIN, IF, END IF y similares también se cambian. Consulta la guía de formateo de PostgreSQL.

Qué se deja como está escrito

• Literales de cadena. En el ejemplo, 'select from where' queda intacto en las dos salidas. El texto entre comillas es dato, y cambiarlo cambiaría el resultado de la consulta.
• Comentarios. Tanto los comentarios -- como los /* */ se copian tal cual, aunque contengan palabras clave.
• La mayoría de los nombres de funciones. Las funciones que no están en la lista anterior, como UPPER, ROUND, NOW, NULLIF y tus propias funciones, conservan las mayúsculas y minúsculas con que las escribiste. En el ejemplo, upper(email) sigue en minúsculas en la salida en mayúsculas y Round(...) conserva su R mayúscula en ambas. Si quieres que los nombres de funciones sean consistentes, escríbelos de forma consistente.
• Identificadores entre comillas. Los nombres entre comillas dobles, entre comillas invertidas de MySQL o entre corchetes de SQL Server, como "Order Id", "select", `order` o [dbo].[orders], se copian exactamente, aunque la palabra de adentro sea una palabra clave. En la mayoría de las bases de datos un nombre entre comillas distingue mayúsculas de minúsculas, así que cambiarlo haría que la consulta apuntara a otro objeto.
• Nombres calificados. Cada parte de un nombre con puntos conserva las mayúsculas y minúsculas con que se escribió: t.month sigue siendo t.month y Sales.Orders sigue siendo Sales.Orders.
• Nombres de tablas, columnas y alias que no son palabras clave.

Identificadores que son palabras clave

Para un nombre simple, el formateador decide por la palabra, no por su función en la sentencia. Un nombre sin comillas y sin calificar que también es palabra clave se cambia como una palabra clave, ya sea un alias o una columna escrita sin calificador de tabla. La misma palabra después de un calificador, como en p.month, o entre comillas, como en "month", no se toca. Palabras como month, value, date y plan están en esa lista, aunque muchas bases de datos las acepten como nombres comunes:

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

Con palabras clave en minúsculas no pasa nada visible. Con mayúsculas, los alias se convierten en MONTH, VALUE y DATE. En PostgreSQL, MySQL y Oracle, los nombres de columna y los alias sin comillas no distinguen mayúsculas de minúsculas, así que la consulta se ejecuta igual. SQL Server depende de la intercalación (collation) de la base de datos: con una intercalación que distingue mayúsculas de minúsculas, un nombre de columna cambiado ya no coincide con la columna, así que califica esa columna (p.date) o ponla entre comillas y conservará las mayúsculas y minúsculas con que la escribiste. También puede cambiar la etiqueta de la columna del resultado: MySQL y SQL Server devuelven el alias exactamente como está escrito, así que un cliente que busque columnas por nombre distinguiendo mayúsculas de minúsculas vería MONTH en lugar de month. PostgreSQL convierte los nombres sin comillas a minúsculas y Oracle a mayúsculas, así que en ellos la etiqueta es la misma en ambos casos.

La forma más sencilla de evitar la cuestión es dar a los alias nombres descriptivos que no sean palabras clave: paid_month, amount_paid, paid_on. De todos modos es una buena práctica, porque los nombres que son palabras clave confunden tanto a las personas como a las herramientas.

Mayúsculas o minúsculas

Las palabras clave en mayúsculas son la convención de toda la vida. La mayor parte de la documentación de bases de datos las usa, y muchas guías de estilo de equipos las recomiendan porque separan el lenguaje de los nombres de un vistazo, incluso en texto plano sin resaltado de sintaxis: en un correo, un archivo de log o una terminal.

Las minúsculas han ganado terreno, sobre todo en los equipos de analítica e ingeniería de datos. Los argumentos son que cualquier editor moderno resalta las palabras clave de todos modos, que las minúsculas son más fáciles de escribir y que una consulta toda en mayúsculas parece gritar más de lo necesario. Si la mayor parte de tu SQL vive dentro del código de la aplicación junto a identificadores en minúsculas, las minúsculas también pueden verse más naturales.

Ninguna de las dos opciones afecta cómo se ejecuta la consulta. Lo que importa es usar una sola forma en todas partes, para que un diff nunca muestre una línea modificada solo porque alguien escribió select en lugar de SELECT. Elige una en tu guía de estilo y deja que el formateador la aplique. La configuración se combina libremente con las demás opciones: Espacios de sangría, Cantidad máxima de columnas, Comas y Paréntesis en nueva línea.