5.2 Actualizando dashboards con API

Puedes automatizar la actualización de dashboards completos sin tocar la UI. El flujo normal es generar un CSV nuevo, enviar solo las filas a agregar con `mode: append` y dejar que Luminon recalcule automáticamente los KPI cards y las charts conectadas al dataset. En este flujo no hace falta token porque usamos la API local del renderer.

Para `Retail Analytics Overview` (`db_gxclrszt`), la idea es simple: el archivo update-retail-analytics.csv solo contiene las filas nuevas de `March 2026`. Ese archivo puede venir de un volcado automatizado desde PostgreSQL, MySQL o incluso desde un archivo plano generado por otro proceso.

#!/usr/bin/env bash
set -euo pipefail

CSV_FILE="${1:-update-retail-analytics.csv}"
DATASET_ID="${DATASET_ID:-ds_sgo6cmlj}"
DASHBOARD_ID="${DASHBOARD_ID:-db_gxclrszt}"
API_URL="${API_URL:-http://localhost:5173/api/datasets/${DATASET_ID}}"

jq -Rs --arg mode "append" --argjson allowSchemaChange false '{csv: ., mode: $mode, allowSchemaChange: $allowSchemaChange}' < "$CSV_FILE" \
  | curl -sS -X PATCH "$API_URL" \
      -H "Content-Type: application/json" \
      --data-binary @- \
  | jq -r '.dataset.id + " updated at " + (.dataset.updatedAt // "unknown")'

echo "Dashboard ${DASHBOARD_ID} will refresh automatically when the dataset update is broadcast."

Ejemplo de ejecución y salida:

sh update_db_gxclrszt.sh

ds_sgo6cmlj updated at 2026-06-06T19:28:56.019Z
Dashboard db_gxclrszt will refresh automatically when the dataset update is broadcast.

No hay una mutación separada para el dashboard: cuando el dataset cambia, Luminon emite la actualización y el dashboard se vuelve a calcular con los mismos filtros, layouts y charts ya definidos. Si el navegador no está abierto en ese momento, basta con refrescar la página del dashboard.

Si quieres ejecutar esto cada mes, agrega una entrada de `cron` para el día 1. Por ejemplo:

0 2 1 * * /bin/bash <your-script-path>/update_db_gxclrszt.sh >> /path/to/log/luminon-retail-analytics.log 2>&1

La misma estrategia funciona si el CSV sale de una base de datos PostgreSQL, MySQL o de cualquier origen plano. Lo importante es que el archivo final solo incluya filas nuevas para `append` y que el esquema siga siendo el mismo.

El patrón `${1:-update-retail-analytics.csv}` significa: usa el primer argumento si lo pasas; si no, usa el nombre de archivo por defecto. Por eso el script asume que lo ejecutas desde `public/tutorials/build-first-dashboard` o desde un directorio donde ese CSV ya esté disponible.

También puedes hacer lo mismo desde Python si prefieres un script más fácil de integrar con otros procesos.

#!/usr/bin/env python3
import pathlib
import sys
import requests

csv_path = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "update-retail-analytics.csv")
dataset_id = "ds_sgo6cmlj"
api_url = f"http://localhost:5173/api/datasets/{dataset_id}"

payload = {
    "csv": csv_path.read_text(encoding="utf-8"),
    "mode": "append",
    "allowSchemaChange": False,
}

response = requests.patch(api_url, json=payload, timeout=30)
response.raise_for_status()
dataset = response.json()["dataset"]
print(f"{dataset['id']} updated at {dataset.get('updatedAt', 'unknown')}")

Importante: si tu archivo solo contiene una actualización usa `append` en `mode`, no uses `replace`. Luminon guarda un snapshot previo y puedes restaurarlo con `restore_dataset_snapshot` desde el MCP. Si lo que quieres es reemplazar todo el dataset, entonces sí usa `replace`, pero el archivo debe contener el dataset completo.