---
name: metabase_update_dashboard_safe
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def metabase_update_dashboard_safe(client: MetabaseClient, dashboard_id: int, *, dashcards_update: list[dict] | None = None, dashcards_add: list[dict] | None = None, dashcards_remove: list[int] | None = None, extra_fields: dict | None = None) -> dict"
description: "Wrapper sobre PUT /api/dashboard/:id que maneja los tres gotchas documentados: strip del campo '.card' denormalizado (evita 413), inclusion obligatoria de 'tabs' (evita 500 FK violation) y asignacion de IDs negativos a dashcards nuevos. Soporta reemplazo completo (dashcards_update), operaciones incrementales (add/remove) y actualizacion de campos extra del dashboard."
tags: [metabase, dashboard, dashcard, api, wrapper, safe, put]
uses_functions:
  - metabase_get_dashboard_py_infra
uses_types: []
params:
  - name: client
    desc: "MetabaseClient autenticado con sesion activa."
  - name: dashboard_id
    desc: "ID entero del dashboard a actualizar."
  - name: dashcards_update
    desc: "Lista completa de dashcards que reemplaza el estado actual (full replace). Si se da, dashcards_add y dashcards_remove se ignoran. Cada dict puede incluir o no el campo 'card' — se strippea automaticamente."
  - name: dashcards_add
    desc: "Dashcards a añadir sobre los existentes. No deben incluir 'id' — la funcion asigna IDs negativos (-1, -2, ...). Se ignora si dashcards_update esta presente."
  - name: dashcards_remove
    desc: "Lista de IDs de dashcards existentes a eliminar del dashboard. Se aplica sobre existentes antes de añadir dashcards_add."
  - name: extra_fields
    desc: "Campos adicionales del dashboard a actualizar junto con las cards: name, description, parameters, archived, collection_id, etc."
output: "Dict con resumen: {'added': [negative_ids_assigned], 'updated': count_existentes_conservados, 'removed': count_eliminados, 'response': dict_respuesta_PUT}"
returns: []
returns_optional: false
error_type: "error_go_core"
imports:
  - httpx
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/metabase/metabase_update_dashboard_safe.py"
---

## Gotchas que maneja

### 1. 413 Payload Too Large — campo `.card` denormalizado
GET /api/dashboard/:id devuelve cada dashcard con un campo `card` que contiene el objeto completo de la question (dataset_query, visualization_settings, result_metadata, etc.). Ese campo puede pesar varios KB por dashcard. PUT /api/dashboard/:id lo rechaza con 413 si se incluye.

Esta funcion hace strip automatico, conservando solo los campos aceptados por la API:
`id`, `card_id`, `dashboard_tab_id`, `col`, `row`, `size_x`, `size_y`, `parameter_mappings`, `visualization_settings`, `series`, `action_id`, `inline_parameters`.

### 2. 500 FK violation — tabs ausentes
Si el body del PUT no incluye `tabs`, Metabase interpreta que se deben borrar todas las tabs. Los dashcards que referencian esas tabs via `dashboard_tab_id` quedan con FK dangling y se produce 500 Internal Server Error.

Esta funcion siempre hace GET del estado actual y re-incluye `current_tabs` en el body.

### 3. IDs negativos para dashcards nuevos
Los dashcards nuevos deben tener `id` negativo temporal (-1, -2, ...) en el payload del PUT. Sin el campo `id`, Metabase los ignora. Esta funcion asigna IDs negativos automaticamente a cualquier dashcard sin `id` en `dashcards_add` o en `dashcards_update`.

## Ejemplo

```python
from metabase import MetabaseClient, metabase_update_dashboard_safe

client = MetabaseClient('https://metabase.example.com', 'token...')

# Añadir una card al dashboard
result = metabase_update_dashboard_safe(
    client,
    dashboard_id=42,
    dashcards_add=[{
        "card_id": 100,
        "col": 0,
        "row": 0,
        "size_x": 6,
        "size_y": 4,
        "parameter_mappings": [],
        "visualization_settings": {},
    }],
)
print(result["added"])   # [-1]
print(result["updated"]) # N dashcards existentes conservados

# Reemplazar todos los dashcards y cambiar nombre
dash = client.request("GET", "/api/dashboard/42")
cards = dash["dashcards"]
cards.append({"card_id": 200, "col": 6, "row": 0, "size_x": 6, "size_y": 4})
result = metabase_update_dashboard_safe(
    client,
    dashboard_id=42,
    dashcards_update=cards,
    extra_fields={"name": "Dashboard actualizado"},
)
```

## Notas

Realiza siempre 2 requests (GET + PUT). Para operaciones de solo metadata sin tocar cards (ej. cambiar nombre), usar `metabase_update_dashboard` directamente que solo hace PUT.

En caso de 413 o 500, el mensaje de error incluye diagnostico del gotcha mas probable para facilitar debugging.