Looky
Back to site

Docs / Build Workflow

Publish

El ciclo de vida de publish

Publicar un workspace es un ritmo de cuatro pasos — leer el estado local, ver qué difiere, validar, push. Corre todos estos desde el root del workspace (o cualquier subdirectorio adentro):

looky status     # confirm root, instance, billing, workspace, sync state
looky diff       # show local-vs-server file differences
looky validate   # run the validation gate
looky push       # publish content (only after validate is clean)

push corre el mismo gate de validación que validate y se rehúsa a publicar si algo falla — validate es la forma de correr ese gate sin publicar.

Dos scopes de push — content vs settings

looky push apunta a una de dos superficies distintas, nunca a las dos a la vez:

  • Default (content push) — publica content/** + workspace.yml. Gateado fuerte por la validación. Falla si tu configuración de runtime todavía no se deployó.
  • --settings (config push) — publica runtime/** + secrets/**. Valida las declaraciones de source y después escribe. Usalo en setup inicial, después de rotar credentials, o cada vez que cambies declaraciones de source.

Orden típico de primera vez:

looky push --settings   # deploy runtime/sources.runtime.yml + secrets/ first
looky push              # then the content

Qué chequea la validación

Cuando corres looky validate o looky push:

  • Pasada local. El YAML parsea, los archivos referenciados existen, los IDs son únicos, query usa el separador ::, los dashboards referencian visualizations reales, los exports referencian dashboards reales, las expresiones cron son válidas, el bloque chart de cada visualization pasa su schema tipado.
  • Pasada server. Los aliases de source son alcanzables, cada model Malloy compila, cada visualization publicada hace dry-run limpio contra las data sources configuradas.

Si algún check falla, el comando sale no-cero e imprime el código de error, el path del archivo, y un mensaje legible. Los warnings no bloquean — aparecen en el output y dejan que el push proceda.

Flags de validación

  • --strict — suma validación live-source por visualization. En Postgres y MySQL, corre EXPLAIN contra la base live (un round-trip por viz, con un timeout de statement). En BigQuery, corre un estimado de costo de query (gratis, sin bytes escaneados). Atrapa errores de dialecto y permisos faltantes que la pasada rápida default no puede. Usalo antes de un release; salteatelo para iteración rápida.
looky validate --strict   # the strict gate without publishing
looky push --strict       # publish behind the strict gate

El push refleja tu estado de content local. El cliente es la fuente de verdad de su scope de content — los archivos presentes en el server pero ausentes localmente se borran como parte del push. Corre looky diff primero y asegúrate de que cada borrado listado sea uno que intencionas.

Familias de error code

Los errores y warnings de validación se taggean con un prefix de código estable. El prefix te dice qué gate se disparó y a qué familia de archivos concierne.

  • WS*** — issues de workspace.yml (campos faltantes, shape inválido de identifier, billing account desconocido).
  • RT*** — declaraciones de runtime / source (tipo de source faltante o no soportado, credentials_file faltante, dsn faltante para postgres, archivo de credenciales no encontrado en secrets/). Mayoritariamente warnings.
  • MD*** — issues de archivo de model (referencia a alias de source faltante, archivo fuera de content/, archivo no legible).
  • VZ*** — estructura YAML de visualization (id/title/type/query faltantes, referencia de query malformada, id duplicado).
  • VZ020, VZ021 — violaciones de schema tipado de visualization: una propiedad chart.* que no está en el schema, un tipo equivocado, un valor fuera de rango.
  • DB*** — issues de YAML de dashboard (campos faltantes, layout_mode no en fluid_grid / document, referencias a visualizations desconocidas).
  • EX*** — issues de YAML de export (formato cron, referencia a dashboard desconocido).
  • MR*** — errores de runtime reportados por el server. MR000 falla de carga, MR001 error de compile / parse de Malloy, MR002 field no definido, MR003 alias de source desconocido, MR004 introspección de schema fallida, MR005 query engine inalcanzable, MR006 query engine timeouteó, MR008 archivo de model faltante, MR009 catch-all de precheck, MR010 source inalcanzable desde la probe.

Qué sube el push

Un content push exitoso publica el set de archivos validado y reporta counts de archivos created / updated / unchanged / deleted. El disaster recovery es tu responsabilidad — mantén el workspace en git, o apóyate en el snapshot local .bk/<timestamp>/ que looky pull escribe cuando sobrescribe archivos locales.

Un settings push exitoso publica runtime/sources.runtime.yml y los archivos de secrets/ referenciados por él. La validación corre primero; si falla, el push imprime los issues y no se escribe nada.

Verificación post-publish

  1. Corre looky list visualizations y looky list dashboards — confirma qué hay publicado realmente en el server.
  2. Abre https://my.looky.studio y confirma que los dashboards renderizan.
  3. Abre al menos una página de detalle de visualization y confirma que aparece data. La validación no chequea que los nombres de campo en mapping matcheen el resultado de la query; eso recién aparece cuando el chart efectivamente renderiza.
  4. Si un dashboard renderiza en blanco o un chart muestra "no rows", chequea la query de model subyacente en la página de detalle de la visualization — esa es la traza más directa.

Un push exitoso solo significa que tus archivos fueron aceptados y publicados. No significa que cada chart renderice bien. Siempre confirma visualmente después de cada push.

Playbook de recovery de fallas

  • La validación falló localmente (WS / RT / MD / VZ / DB / EX). Lee el código de error y el path del archivo; arregla el YAML; re-corre looky validate.
  • La validación falló en la pasada server (MR* o VZ020). El error menciona el model o visualization que lo disparó. Abre ese archivo, arregla el Malloy o spec de chart, re-corre looky validate. Si el error es MR010 (source inalcanzable), confirma que looky push --settings haya corrido exitosamente recientemente con las credentials actuales. Cuando el server reporta cualquier error, nada en el workspace se modifica.
  • El push pasó pero el dashboard está mal en el sitio live. Los archivos se publicaron bien pero un chart está fallando al renderizar. Chequea nombres de campo en mapping, format keys, y el output real de la query en el viz detail.
  • Necesitas deshacer un push. Restaura el contenido previo desde git o desde el directorio local .bk/<timestamp>/ que looky pull escribió, y vuelve a pushear con looky push.