---
name: metabase_smartscalar_dimension_tag
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: pure
signature: "def metabase_smartscalar_dimension_tag(*, name: str, field_id: int, base_type: str = 'type/Text', widget_type: str = 'string/=', display_name: str = '') -> dict"
description: "Construye un template-tag de tipo dimension con la firma exacta que Metabase v0.59 espera (incluyendo lib/uuid, base-type, effective-type). Sin estos flags Metabase devuelve PUT 200 pero descarta silenciosamente el dataset_query."
tags: [metabase, smartscalar, template-tag, field-filter, kpi, pure, builder, pendiente-usar]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports:
  - "import uuid"
params:
  - name: name
    desc: "Identificador snake_case del template-tag; tambien se usa en el SQL como [[AND {{name}}]]"
  - name: field_id
    desc: "ID numerico del Field de Metabase al que apunta el filtro; consultable via GET /api/field/<id> o el data model"
  - name: base_type
    desc: "Tipo base del Field. Valores comunes: type/Text, type/Date, type/Integer, type/Decimal, type/DateTime"
  - name: widget_type
    desc: "Widget de filtro en el dashboard. Comunes: string/= (multivalor texto), date/all-options, number/=, string/contains"
  - name: display_name
    desc: "Etiqueta legible mostrada en la UI; vacio = autogenerada title-casing del name"
output: "dict con la estructura {name, id, display-name, type, widget-type, dimension: ['field', {base-type, effective-type, lib/uuid}, field_id]} listo para usar como entrada del map template-tags de un dataset_query nativo"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/metabase/smartscalar.py"
---

## Por que existe

Metabase v0.59 valida silenciosamente la estructura de los ``template-tags``
en cards nativas: si falta ``lib/uuid``, ``base-type`` o ``effective-type``
en el ``dimension`` array, el ``PUT /api/card/:id`` devuelve 200 pero al
releer la card el ``dataset_query`` aparece vacio (``stages: [{}]``) y la
card no se puede ejecutar.

Este helper rellena la firma exacta y ademas genera el ``lib/uuid``
deterministicamente con ``uuid5`` sobre el ``name``, garantizando que la
funcion sea pura: dos llamadas con los mismos argumentos producen el mismo
dict bit a bit.

## Ejemplo

```python
tags = {
    "fecha": metabase_smartscalar_dimension_tag(
        name="fecha", field_id=322392,
        base_type="type/Date", widget_type="date/all-options",
        display_name="Fecha",
    ),
    "categoria": metabase_smartscalar_dimension_tag(
        name="categoria", field_id=270702,
        widget_type="string/=",
    ),
}
# tags["fecha"]["dimension"] == ["field", {"base-type": "type/Date", ...}, 322392]
```

## Notas

- El ``id`` interno se rellena con ``f"{name}_tag"`` por consistencia con las
  cards de la suite Lean.
- Para campos calculados (expresiones MBQL) o template-tags de tipo ``text``,
  ``snippet`` o ``card``, NO usar este helper — fueron disenados solo para
  dimension/field-filters.
- Si la card se va a guardar una vez y editar a mano luego, los UUIDs
  deterministicos no causan colisiones porque solo importan dentro de la card.
