fn_registry/python/functions/metabase/metabase_update_dashboard_safe.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, params, output, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	params	output	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
metabase_update_dashboard_safe	function	py	infra	1.0.0	impure	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	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.	metabase dashboard dashcard api wrapper safe put	metabase_get_dashboard_py_infra		name desc client MetabaseClient autenticado con sesion activa. name desc dashboard_id ID entero del dashboard a actualizar. name desc dashcards_update 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 desc dashcards_add 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 desc dashcards_remove Lista de IDs de dashcards existentes a eliminar del dashboard. Se aplica sobre existentes antes de añadir dashcards_add. name desc extra_fields Campos adicionales del dashboard a actualizar junto con las cards: name, description, parameters, archived, collection_id, etc.	Dict con resumen: {'added': [negative_ids_assigned], 'updated': count_existentes_conservados, 'removed': count_eliminados, 'response': dict_respuesta_PUT}		false	error_go_core	httpx	false			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

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.