---
name: metabase_viz_column_format
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: pure
signature: "def metabase_viz_column_format(column: str, *, number_style: str = '', decimals: int = -1, currency: str = '', currency_in_header: bool | None = None, suffix: str = '', prefix: str = '') -> dict"
description: "Construye la entrada column_settings para una columna en visualization_settings de Metabase. Genera la clave con el formato JSON exacto que Metabase requiere ('['name','<columna>']') y el dict de formato con solo los campos explicitamente especificados. El resultado se fusiona en visualization_settings['column_settings']."
tags: [metabase, visualization, column-settings, format, number-style, currency, percent, pure, builder]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: column
    desc: "Nombre exacto de la columna tal como aparece en el resultado del query (sensible a mayusculas)"
  - name: number_style
    desc: "Estilo de formato numerico: '' (default), 'currency', 'percent', 'decimal', 'scientific'"
  - name: decimals
    desc: "Numero de decimales a mostrar. -1 = omitir (usa default de Metabase)"
  - name: currency
    desc: "Codigo ISO de moneda ('EUR', 'USD', ...). Solo relevante con number_style='currency'. Vacio = omitir"
  - name: currency_in_header
    desc: "Si True muestra el simbolo de moneda en la cabecera en lugar de junto al valor. None = omitir"
  - name: suffix
    desc: "Sufijo textual mostrado tras el valor. Vacio = omitir"
  - name: prefix
    desc: "Prefijo textual mostrado antes del valor. Vacio = omitir"
output: "Dict con una sola clave (string JSON '[\"name\",\"<column>\"]') y como valor un dict con los campos de formato explicitamente especificados. Listo para fusionar en visualization_settings['column_settings']."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/metabase/metabase_viz_column_format.py"
---

## Por que existe

Metabase espera la clave de ``column_settings`` como un string JSON serializado sin
espacios: ``'["name","Margen"]'``. Construir este string manualmente es propenso
a errores (espacios extra, comillas mal escapadas). Esta funcion estandariza la
construccion y solo incluye los campos que se especificaron — Metabase ignora
campos ausentes con su comportamiento default.

## Ejemplo

```python
from metabase import metabase_viz_column_format

# Formato porcentaje con 2 decimales
entry = metabase_viz_column_format("Margen", number_style="percent", decimals=2)
# {'["name","Margen"]': {"number_style": "percent", "decimals": 2}}

# Formato moneda sin decimales, simbolo en cabecera
entry = metabase_viz_column_format(
    "MasadeMargen",
    number_style="currency",
    currency="EUR",
    decimals=0,
    currency_in_header=False,
)
# {'["name","MasadeMargen"]': {"number_style": "currency", "currency": "EUR", "decimals": 0, "currency_in_header": False}}

# Usar en visualization_settings
viz = {"column_settings": {}}
viz["column_settings"].update(metabase_viz_column_format("Venta", number_style="currency", currency="EUR", decimals=0))
viz["column_settings"].update(metabase_viz_column_format("Margen", number_style="percent", decimals=2))
```

## Notas

- La clave se genera con ``json.dumps(["name", column], separators=(",", ":"))``
  que produce ``'["name","Margen"]'`` sin espacios — el formato exacto que Metabase
  espera. Cualquier variacion (espacios, comillas simples) causa que Metabase
  ignore silenciosamente el setting.
- Solo se incluyen en el dict de valor los campos explicitamente especificados.
  Metabase aplica sus defaults para los ausentes.
- El centinela ``decimals=-1`` (valor por defecto) indica "omitir"; cualquier valor
  >= 0 se incluye en el resultado incluyendo ``decimals=0``.
- Compatible con cualquier tipo de card (smartscalar, table, bar, line).
