Cómo estructurar tus queries para que sean legibles

El código se lee más de lo que se escribe

Una consulta SQL que funciona pero es ilegible es un problema a futuro. Cuando se necesita modificarla semanas después, o cuando otra persona del equipo necesita entenderla, el formato importa tanto como la lógica. Invertir unos minutos en estructurar la query correctamente ahorra horas de frustración después.

Las convenciones que se describen a continuación no son reglas del lenguaje SQL (que es flexible con el formato), sino prácticas de la industria que facilitan la lectura y el mantenimiento.

Convención 1: una cláusula por línea

Cada cláusula principal va en su propia línea, alineada a la izquierda:

-- MAL: todo en una línea
SELECT url, SUM(clicks) AS clics FROM gsc WHERE data_date > '2026-04-01' GROUP BY url ORDER BY clics DESC LIMIT 50

-- BIEN: una cláusula por línea
SELECT
  url,
  SUM(clicks) AS clics
FROM
  `your-project.searchconsole.searchdata_url_impression`
WHERE
  data_date > '2026-04-01'
GROUP BY
  url
ORDER BY
  clics DESC
LIMIT 50

Convención 2: indentación consistente

Usar 2 espacios de indentación para las columnas y condiciones dentro de cada cláusula. No mezclar tabs y espacios. Las columnas del SELECT van indentadas debajo de él:

SELECT
  event_date,
  event_name,
  traffic_source.medium AS medio,
  COUNT(*) AS total
FROM
  `proyecto.dataset.tabla`
WHERE
  _TABLE_SUFFIX BETWEEN '20260401' AND '20260430'
  AND traffic_source.medium = 'organic'
GROUP BY
  event_date, event_name, medio

Las condiciones del WHERE con AND/OR van alineadas con indentación, cada una en su propia línea. Esto facilita identificar rápidamente qué filtros se aplican.

Convención 3: CTEs con nombres descriptivos

Los CTEs deben tener nombres que describan qué contienen, no abreviaturas genéricas:

-- MAL: nombres genéricos
WITH t1 AS (...), t2 AS (...)

-- BIEN: nombres descriptivos
WITH gsc_keywords AS (...),
ga4_conversiones AS (...),
cruce_final AS (...)

Al leer la consulta, los nombres de los CTEs funcionan como títulos de secciones. Un buen nombre permite entender la lógica sin leer el contenido del CTE.

Convención 4: comentarios estratégicos

Los comentarios deben explicar el «por qué», no el «qué». El código ya dice qué hace; el comentario explica la razón detrás de una decisión no obvia:

-- MAL: repite lo que el código ya dice
-- Filtrar por orgánico
WHERE traffic_source.medium = 'organic'

-- BIEN: explica el por qué de una decisión no obvia
-- traffic_source.medium es first-touch attribution;
-- para session-level usar collected_traffic_source
WHERE traffic_source.medium = 'organic'

-- BIEN: explica la fórmula del cálculo
-- Posición media: 0-indexed en el export, se suma impressions para convertir a 1-indexed
ROUND(SUM(sum_top_position + impressions) / SUM(impressions), 2) AS posicion_media

Convención 5: alias consistentes

Usar alias claros y consistentes a lo largo de la query:

• Alias de columna: nombres en español o en inglés, pero siempre en el mismo idioma. clics, sesiones, posicion_media o clicks, sessions, avg_position.
• Alias de tabla: abreviaturas de 2-3 letras que se puedan asociar fácilmente. g para GSC, a para GA4, o mejor aún gsc y ga4.

Convención 6: usar mayúsculas para palabras clave SQL

La convención más extendida es escribir las palabras clave de SQL en mayúsculas (SELECT, FROM, WHERE) y los nombres de columnas y tablas en minúsculas. Esto facilita distinguir la estructura de la query de los datos:

SELECT
  url,
  SUM(clicks) AS clics
FROM
  gsc_data
WHERE
  data_date >= '2026-04-01'
GROUP BY
  url

BigQuery no distingue mayúsculas de minúsculas en las palabras clave, así que select, SELECT y Select funcionan igual. Pero la convención de mayúsculas mejora la legibilidad.

Convención 7: agrupar las condiciones lógicamente

WHERE
  -- Filtros de fecha
  _TABLE_SUFFIX BETWEEN
    FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))
    AND FORMAT_DATE('%Y%m%d', CURRENT_DATE())
  -- Filtros de tráfico
  AND traffic_source.medium = 'organic'
  AND event_name = 'session_start'
  -- Filtros de geografía
  AND geo.country IN ('Spain', 'Mexico')

Agrupar las condiciones por tema y separarlas con comentarios de una línea facilita identificar qué filtros se aplican en cada dimensión.

Plantilla de referencia

Una estructura de query bien formateada que se puede usar como punto de partida:

-- Descripción breve de qué hace la query
-- Fuente: GA4 + GSC | Periodo: últimos 28 días
WITH fuente_a AS (
  -- Datos de la primera fuente
  SELECT
    columna1,
    columna2,
    SUM(metrica) AS metrica_agregada
  FROM
    `proyecto.dataset.tabla`
  WHERE
    filtro_fecha
    AND filtro_adicional
  GROUP BY
    columna1, columna2
),
fuente_b AS (
  -- Datos de la segunda fuente
  SELECT
    campo_comun,
    SUM(otra_metrica) AS otra_metrica_agregada
  FROM
    `proyecto.otro_dataset.otra_tabla`
  WHERE
    filtro_fecha
  GROUP BY
    campo_comun
)
-- Consulta final: cruzar fuentes
SELECT
  a.columna1,
  a.metrica_agregada,
  b.otra_metrica_agregada
FROM
  fuente_a a
  LEFT JOIN fuente_b b ON a.columna1 = b.campo_comun
ORDER BY
  a.metrica_agregada DESC
LIMIT 50

Todas las queries del catálogo de Queryteca siguen estas convenciones. Pueden servir como referencia de formato además de como soluciones técnicas.

Aplicar estas convenciones de forma consistente tiene un beneficio adicional: facilita la revisión colaborativa. Cuando varias personas del equipo trabajan con las mismas queries, un formato uniforme reduce el tiempo necesario para entender el código ajeno y minimiza la probabilidad de introducir errores al modificarlo.

Siguiente paso

Una query bien estructurada es más fácil de guardar, versionar y reutilizar. El siguiente artículo cubre cómo organizar una biblioteca personal de queries para no perder el trabajo.