---
name: metabase_smartscalar_kpi_payload
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: pure
signature: "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"
description: "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."
tags: [metabase, smartscalar, kpi, card, payload, pure, builder]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: name
    desc: "Nombre de la card mostrado en el dashboard"
  - name: database_id
    desc: "ID de la database de Metabase contra la que se ejecuta el SQL"
  - name: sql
    desc: "Query nativa que devuelve columnas periodo (DATE) y valor (numero) con 2 filas (n-1, actual). Generable con metabase_smartscalar_kpi_sql"
  - name: template_tags
    desc: "Dict {tag_name: tag_dict} para field-filters; None para card sin filtros. Construir con metabase_smartscalar_dimension_tag"
  - name: description
    desc: "Descripcion mostrada en la card; vacio = autorrellenada"
  - name: collection_id
    desc: "ID de la coleccion destino; 0 = Our analytics (root)"
  - name: currency
    desc: "Si True formatea valor como moneda con simbolo currency_code"
  - name: currency_code
    desc: "Codigo ISO de moneda. Default EUR. Solo aplica si currency=True"
  - name: decimals
    desc: "Decimales mostrados en valor"
  - name: comparison_label
    desc: "Etiqueta del bloque de comparacion bajo el numero principal. Default 'vs n-1'"
  - name: extra_visualization_settings
    desc: "Settings adicionales fusionados (top-level override) en visualization_settings; util para anadir scalar.title, card.title.alignment, etc."
output: "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"
tested: false
tests: []
test_file_path: ""
file_path: "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

```python
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).