fn_registry/python/functions/metabase/metabase_smartscalar_kpi_sql.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
metabase_smartscalar_kpi_sql	function	py	infra	1.0.0	pure	def metabase_smartscalar_kpi_sql(*, act_expr: str, n1_expr: str, body_sql: str, date_expr: str = 'MIN(fecha)') -> str	Envuelve agregaciones actual+n-1 en el patron de 2 filas (periodo, valor) que el display smartscalar de Metabase v0.59 requiere para mostrar comparacion vs ano anterior sin pedir breakout temporal. Genera SQL nativo BigQuery con UNION ALL d_min/d_min-52w.	metabase smartscalar kpi sql bigquery pure builder				false			name desc act_expr Expresion SQL de agregado para el periodo actual, ej. 'ROUND(SUM(v.venta_n), 2)' o 'SAFE_DIVIDE(SUM(a), NULLIF(SUM(b),0))' name desc n1_expr Expresion SQL para el mismo agregado del ano anterior, ej. 'ROUND(SUM(v.venta_n1), 2)' name desc body_sql Cuerpo SQL desde 'FROM' que define las tablas/CTEs y filtros con template-tags Metabase (AND {{tag}}) name desc date_expr Expresion para extraer la fecha minima del periodo; usada como periodo en la fila actual y ancla para DATE_SUB de la fila n-1. Default 'MIN(fecha)'	string con SQL nativo BigQuery que devuelve 2 filas con columnas periodo (DATE) y valor (numero); fila 1 = periodo n-1, fila 2 = periodo actual	false			python/functions/metabase/smartscalar.py

Por que existe

El display smartscalar de Metabase v0.59.4 con previousValue requiere una serie temporal para mostrar comparacion. Si el query devuelve un solo numero el frontend muestra el error "Agrupa solo por un campo de tiempo para ver como ha cambiado con el tiempo".

El truco probado en el dashboard Informe Lean (cards 9340-9373) es producir 2 filas sinteticas: una para el periodo actual (d_min, act) y otra para n-1 (d_min - 52 weeks, n1). Smartscalar lo interpreta como serie de 2 puntos y compara naturalmente.

Esta funcion automatiza ese patron: el caller solo provee el cuerpo SQL con sus filtros y las dos expresiones de agregado.

Ejemplo

body = """
FROM `proj.ds.base_margenes_aa` `proj.ds.base_margenes_aa` v
LEFT JOIN `proj.ds.Objeto_productos` p ON p.nav_id = v.prod_nav_id
WHERE 1=1
  [[AND {{fecha}}]]
  [[AND {{categoria}}]]
  [[AND {{tipo}}]]
"""

sql = metabase_smartscalar_kpi_sql(
    act_expr="ROUND(SUM(v.venta_n), 2)",
    n1_expr="ROUND(SUM(v.venta_n1), 2)",
    body_sql=body,
    date_expr="MIN(v.fecha)",
)
# sql tiene UNION ALL con periodo y valor

Notas

• Por convencion los template-tags estan envueltos en [[ ]] para que sean opcionales: si el dashboard no aplica el filtro la clausula desaparece.
• Para que los field-filters de Metabase resuelvan correctamente las tablas dentro de CTEs, alias cada tabla con la cadena schema.table exacta que Metabase usa al expandir el template-tag (ej. \`proj.ds.tabla\` \`ds.tabla\).
• El SQL generado usa DATE_SUB(d_min, INTERVAL 52 WEEK) (BigQuery dialect). Para Postgres adaptar a d_min - INTERVAL '52 weeks'.