Ir al contenido
ShareOut ShareOut Docs

Procedencia de datos

import { Aside } from ‘@astrojs/starlight/components’;

Los dashboards y reportes corren sobre consultas, conectores, snapshots y entregas programadas. Los visitantes (y quienes reenvían un Slack o email) preguntan constantemente de dónde salen los números y cómo reproducirlos. Respondé en build-time: declará la procedencia en el manifest y ShareOut renderiza la UI por vos.

La regla única

Sección titulada «La regla única»

Por cada dataset que lee un artifact, declará en el manifest: qué es, la query o script que lo produjo, las tablas que toca, cuándo se refresca y cómo reconstruirlo. Después vinculá cada gráfico o tabla a su fuente.

1. Declarar procedencia en las fuentes

Sección titulada «1. Declarar procedencia en las fuentes»

Cada entrada de sources.{connections,json,tables} acepta campos opcionales de procedencia:

<script type="shareout/manifest">
{
  "version": "2.0",
  "sources": {
    "connections": {
      "warehouse": {
        "label": "Actividad de clientes (90d)",
        "description": "Eventos de creación/interacción por empresa, últimos 90 días.",
        "query": "SELECT company_id, SUM(recipes_created + vendors_created) AS act\nFROM CUSTOMER_METRICS.FCT_CUSTOMER_ACTIVITY\nWHERE event_date >= DATEADD(day,-90,CURRENT_DATE)\nGROUP BY 1",
        "tables": ["CUSTOMER_METRICS.FCT_CUSTOMER_ACTIVITY"],
        "refresh": "daily 12:00 UTC",
        "as_of": "2026-06-22",
        "replication": {
          "build": "python build_scorecard.py",
          "publish": "node publish_scorecard.mjs",
          "credentials": "Key-pair Snowflake en la conexión del workspace"
        },
        "default": [{ "company_id": "c1", "act": 42 }]
      }
    }
  }
}
</script>
CampoPropósito
labelNombre legible del dataset
descriptionUna línea: qué es
querySQL, llamada API o paso de build exacto que produjo los datos
tablesTablas subyacentes del warehouse o fuente
refreshCadencia en palabras (daily 12:00 UTC, manual, live)
as_ofFecha u hora del snapshot
replication{ build, publish, credentials, notes } — cómo reconstruir desde cero

Todos los campos son opcionales y retrocompatibles. Mantené default también — alimenta el preview del editor. Ver Manifest → Procedencia.

2. Vincular cada gráfico o tabla a su fuente

Sección titulada «2. Vincular cada gráfico o tabla a su fuente»

Dos formas; usá una o ambas.

Atributo por elemento (lo más simple):

<div id="rev-chart" data-shareout-source="connection:warehouse"></div>
<table data-shareout-source="json:revenue">…</table>

feeds en el manifest (cuando no podés editar el elemento, o querés una nota):

"feeds": [
  { "element": "#rev-chart", "source": "connection:warehouse", "note": "Rollup 90 días" }
]

source es una ref kind:key — connection:warehouse, json:revenue, table:rooms.

3. Mostrar el drawer a los visitantes

Sección titulada «3. Mostrar el drawer a los visitantes»

Una línea de JavaScript:

const sdk = await ShareOut.create();
sdk.sources.mount(); // botón flotante "Data sources" + drawer + badges por elemento

O cero líneas — agregá el atributo y el SDK monta al cargar el DOM:

<body data-shareout-sources>

Lo que ven los visitantes:

  • Un drawer Data sources: una tarjeta por dataset con descripción, tablas, refresh, as-of, View query colapsable y bloque Replicate (build/publish/credentials).
  • Un badge ⓘ source en cada elemento que etiquetaste (o mapeaste vía feeds); al hacer clic abre el drawer en ese dataset.

Ver SDK Sources para la API completa.

4. Atribuir entregas de crew

Sección titulada «4. Atribuir entregas de crew»

Cuando un crew o job entrega números derivados de datos a Slack, Telegram o email, pasá source a notify_send para que los destinatarios puedan rastrear las cifras:

{
  "destination": "slack",
  "message": "Adopción semanal: 62% de cuentas activas (+4pts).",
  "config": { "connection": "team_slack", "channelId": "C0…" },
  "source": {
    "connection": "galley_snowflake",
    "query": "SELECT … FROM CUSTOMER_METRICS.FCT_CUSTOMER_ACTIVITY …",
    "asOf": "2026-06-22"
  }
}

Se agrega un footer compacto: _Source: galley_snowflake · as of 2026-06-22_ más la query en una línea. Ver Crew tools → notify_send.

Checklist

Sección titulada «Checklist»
  • Cada conexión o dataset declara description + query (+ tables)
  • refresh + as_of definidos para que los visitantes sepan qué tan frescos están los datos
  • replication.{build,publish,credentials} completos — la respuesta “cómo reconstruir”
  • Cada gráfico o tabla con data-shareout-source o mapeado en feeds
  • sdk.sources.mount() (o <body data-shareout-sources>) para que los visitantes lo vean
  • Entregas de crew o jobs pasan source a notify_send
  • El perfil de readiness al publicar no muestra advertencias de provenance

Relacionado

Sección titulada «Relacionado»