fn_registry/python/functions/metabase/metabase_smartscalar_kpi_payload.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_payload	function	py	infra	1.0.0	pure	def metabase_smartscalar_kpi_payload(*, name: str, database_id: int, sql: str, template_tags: dict | None = None, description: str = '', collection_id: int = 0, currency: bool = False, currency_code: str = 'EUR', decimals: int = 0, comparison_label: str = 'vs n-1', extra_visualization_settings: dict | None = None) -> dict	Construye el payload completo para POST /api/card de un KPI smartscalar con formato y comparacion previousValue. Combina SQL nativo (idealmente generado por metabase_smartscalar_kpi_sql) con template-tags y visualization_settings predefinidos. Listo para metabase_create_card_raw.	metabase smartscalar kpi card payload pure builder pendiente-usar				false			name desc name Nombre de la card mostrado en el dashboard name desc database_id ID de la database de Metabase contra la que se ejecuta el SQL name desc sql Query nativa que devuelve columnas periodo (DATE) y valor (numero) con 2 filas (n-1, actual). Generable con metabase_smartscalar_kpi_sql name desc template_tags Dict {tag_name: tag_dict} para field-filters; None para card sin filtros. Construir con metabase_smartscalar_dimension_tag name desc description Descripcion mostrada en la card; vacio = autorrellenada name desc collection_id ID de la coleccion destino; 0 = Our analytics (root) name desc currency Si True formatea valor como moneda con simbolo currency_code name desc currency_code Codigo ISO de moneda. Default EUR. Solo aplica si currency=True name desc decimals Decimales mostrados en valor name desc comparison_label Etiqueta del bloque de comparacion bajo el numero principal. Default 'vs n-1' name desc extra_visualization_settings Settings adicionales fusionados (top-level override) en visualization_settings; util para anadir scalar.title, card.title.alignment, etc.	dict con payload completo (name, description, type=question, display=smartscalar, dataset_query nativo, visualization_settings con scalar.field/scalar.comparisons/column_settings, [collection_id]) directamente posteable a /api/card	false			python/functions/metabase/smartscalar.py

Por que existe

Encapsular la combinacion exacta de campos que Metabase v0.59 necesita para un KPI smartscalar con comparacion previousValue: scalar.field, scalar.comparisons con id, type y label, y column_settings con la clave de columna serializada como JSON '["name","valor"]'.

Cualquier desviacion (clave de column_settings sin escapar, ausencia de scalar.field, type distinto de previousValue/anotherColumn/staticNumber) hace que el frontend muestre el numero pero descarta silenciosamente la comparacion o pide breakout.

Ejemplo

sql = metabase_smartscalar_kpi_sql(
    act_expr="ROUND(SUM(v.venta_n), 2)",
    n1_expr="ROUND(SUM(v.venta_n1), 2)",
    body_sql=ventas_cte_sql,
    date_expr="MIN(v.fecha)",
)
tags = {
    "fecha": metabase_smartscalar_dimension_tag(
        name="fecha", field_id=322392,
        base_type="type/Date", widget_type="date/all-options",
    ),
}
payload = metabase_smartscalar_kpi_payload(
    name="Venta total",
    database_id=6,
    sql=sql,
    template_tags=tags,
    currency=True, decimals=0,
    description="Venta del periodo seleccionado vs ano anterior.",
    collection_id=583,
)
card = metabase_create_card_raw(client, payload)
print(card["id"])

Notas

• visualization_settings.column_settings usa la clave con formato JSON exacto '["name","valor"]' (sin espacios entre comillas y coma) — Metabase no normaliza variaciones.
• Si necesitas la card como model o metric en lugar de question, override via extra_visualization_settings no aplica — clona el resultado y modifica payload["type"] antes de enviar.
• Para reemplazar una card existente usa metabase_update_card con los mismos campos del payload (display, dataset_query, visualization_settings).