Looky
Back to site

Docs / Getting Started

Acceso al Dataset de BigQuery

Qué necesitás antes de escribir un solo model

Looky corre queries Malloy contra BigQuery a tu nombre. Para que eso funcione, tu workspace necesita un service account de GCP con suficientes permisos para leer datos y correr jobs. Esta página te lleva por crear uno, descargar el archivo de credentials y ponerlo donde el runtime lo espera.

Vas a necesitar dos cosas de GCP:

  • Un billing project: el proyecto de GCP que paga el costo de las queries. Este es tu propio proyecto.
  • Una dataset location: el proyecto y dataset donde los datos realmente viven. Puede ser un proyecto distinto — incluyendo datasets públicos como bigquery-public-data.

Estas dos cosas se confunden seguido. Tu service account vive en el billing project, pero se le puede dar read access a datasets en cualquier otro proyecto.

Paso 1: Crear un service account en GCP

  1. Abrí la consola de Service Accounts de GCP y seleccioná tu billing project.
  2. Clickeá Create service account.
  3. Dale un nombre claro, por ejemplo: looky-workspace-reader.
  4. Clickeá Create and continue.

Paso 2: Dar los roles mínimos requeridos

En el paso "Grant this service account access to project", agregá estos dos roles:

  • BigQuery Data Viewer — permite leer data de tablas y schemas.
  • BigQuery Job User — permite correr query jobs (requerido incluso para queries read-only).

Eso es el mínimo. No agregues Owner, Editor ni ningún rol más amplio. Clickeá Done.

Si los datos que necesitás consultar viven en otro proyecto de GCP (por ejemplo un data warehouse compartido), también tenés que agregar BigQuery Data Viewer en ese proyecto para este mismo service account. Eso se hace desde la página de IAM del proyecto de datos, no del billing project.

Paso 3: Descargar el JSON key

  1. En la lista de service accounts, clickeá el account que recién creaste.
  2. Abrí la pestaña Keys.
  3. Clickeá Add key → Create new key.
  4. Seleccioná JSON y clickeá Create. El archivo se descarga al toque.

Renombrá el archivo a algo legible, por ejemplo: my-workspace-bq.json.

Paso 4: Poner el key en tu workspace

Copiá el JSON key en la carpeta secrets/ de tu workspace:

<local_root>/
  <billing_account_id>/
    <workspace_slug>/
      secrets/
        my-workspace-bq.json   ← acá va

Asegurate de que .gitignore excluya secrets/ antes de commitear nada:

cat .gitignore

Tenés que ver secrets/ o secrets/* listado. Si no está, agregalo antes de pushear a cualquier remote — Looky no lo enforcea; es tu responsabilidad.

Nunca commitees el JSON key a git. Cualquiera con el archivo puede correr queries facturadas a tu proyecto de GCP. La exclusión de secrets/ existe exactamente por esta razón.

Paso 5: Referenciar el key en sources.runtime.yml

Abrí runtime/sources.runtime.yml y poné credentials_file con el nombre del JSON que dejaste en secrets/. Es un filename plano — sin paths, sin slashes; la plataforma lo resuelve contra la carpeta secrets/ del workspace.

sources:
  ecommerce:
    name: The Look Ecommerce
    type: bigquery
    project_id: my-gcp-billing-project
    credentials_file: my-workspace-bq.json
    datasets:
      - bigquery-public-data.thelook_ecommerce
  • project_id: el proyecto de GCP que paga el costo de las queries — tu billing project.
  • credentials_file: filename del JSON de service-account dentro de secrets/. Pattern ^[A-Za-z0-9_-][A-Za-z0-9._-]*$ — sin separadores de path, sin punto inicial.
  • datasets: una o más referencias a datasets que el runtime tiene permitido consultar. Pueden estar en un proyecto de GCP distinto a project_id.

Paso 6: Validar la conexión

Desde el root del workspace, corré:

looky sources list
looky validate

Si sources list devuelve tu alias sin errores y validate no muestra issues bloqueantes, la declaración del source es estructuralmente válida y el runtime puede llegar a BigQuery con las credentials que pasaste. La validación default no verifica que el service account tenga read access a cada dataset que referenciás — esos errores aparecen cuando una query real toca el dataset. Usá looky validate --strict para upgradear la validación a checks live-source por visualization (el estimateQueryCost de BigQuery es gratis y atrapa issues de permisos antes del push).

Si la validación falla, las causas más comunes son:

  • El nombre de archivo en credentials_file no coincide con el archivo en secrets/, o trae separadores de path (debe ser filename plano).
  • Al service account le falta BigQuery Job User — las queries quedan bloqueadas incluso si los datos son legibles.
  • La referencia al dataset usa el proyecto o nombre de dataset equivocado — verificá los nombres exactos en la consola de BigQuery.