---
name: metabase_add_dashboard_filter
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def metabase_add_dashboard_filter(client: MetabaseClient, dashboard_id: int, name: str, slug: str, filter_type: str, card_mappings: list[dict], *, default: str | None = None) -> dict"
description: "Añade un filtro a un dashboard de Metabase y lo conecta a las cards indicadas. Crea el parameter a nivel de dashboard y actualiza los parameter_mappings de cada dashcard."
tags: [metabase, dashboard, filter, parameter, create, api, python, pendiente-usar]
uses_functions:
  - metabase_update_dashboard_safe_py_infra
  - metabase_get_dashboard_py_infra
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [uuid]
params:
  - name: client
    desc: "instancia autenticada de MetabaseClient"
  - name: dashboard_id
    desc: "ID del dashboard al que se añade el filtro"
  - name: name
    desc: "nombre visible del filtro en la UI de Metabase (ej: 'Fecha desde')"
  - name: slug
    desc: "slug URL-friendly del filtro, unico dentro del dashboard (ej: 'fecha_desde')"
  - name: filter_type
    desc: "tipo del filtro: 'string/=', 'number/=', 'date/single', 'date/range', 'date/relative', 'category'"
  - name: card_mappings
    desc: "lista de dicts [{card_id: int, template_tag: str}] conectando el filtro a template-tags SQL de las cards"
  - name: default
    desc: "valor por defecto del filtro; None = sin default"
output: "dict con resultado de metabase_update_dashboard_safe: {added, updated, removed, response}"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/metabase/dashboard_filters.py"
---

## Ejemplo

```python
result = metabase_add_dashboard_filter(
    client,
    dashboard_id=887,
    name="Fecha desde",
    slug="fecha_desde",
    filter_type="string/=",
    card_mappings=[
        {"card_id": 7711, "template_tag": "fecha_desde"},
        {"card_id": 7719, "template_tag": "fecha_desde"},
    ],
)

# Con valor por defecto
result = metabase_add_dashboard_filter(
    client,
    dashboard_id=887,
    name="Estado",
    slug="estado",
    filter_type="category",
    card_mappings=[{"card_id": 7711, "template_tag": "estado"}],
    default="activo",
)
```

## Notas

Realiza 2 requests internamente via metabase_update_dashboard_safe (GET + PUT).

El `param_id` se genera como UUID hex de 8 caracteres — formato que usa la UI de Metabase.

`card_mappings` solo conecta cards que ya existen como dashcards en el dashboard. Cards no presentes en el dashboard se ignoran silenciosamente.

Para filtros de tipo date, los valores en `default` deben seguir el formato de Metabase: "2024-01-01" para `date/single`, "2024-01-01~2024-12-31" para `date/range`.
