Declarar una fuente de datos

En este documento se explica cómo declarar fuentes de datos de BigQuery con Dataform Core.

Puedes declarar cualquier tipo de tabla de BigQuery como fuente de datos en Dataform. Al declarar fuentes de datos de BigQuery externas a Dataform, puedes tratar esas fuentes de datos como objetos de Dataform.

Declarar fuentes de datos es opcional, pero puede ser útil si quiere hacer lo siguiente:

  • Hacer referencia a fuentes declaradas o resolverlas de la misma forma que cualquier otra tabla de Dataform.
  • Ver las fuentes declaradas en el gráfico de Dataform visualizado.
  • Usa Dataform para gestionar las descripciones a nivel de tabla y de columna de las tablas creadas externamente.
  • Activa invocaciones de flujo de trabajo que incluyan todas las dependencias de una fuente de datos externa.

Puedes declarar fuentes de datos mediante archivos JavaScript o SQLX. En un archivo JavaScript, puede declarar varias fuentes de datos por archivo. En un archivo SQLX, puedes declarar una fuente de datos por archivo.

Antes de empezar

Antes de declarar una fuente de datos, crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.

Roles obligatorios

Para obtener los permisos que necesitas para declarar una fuente de datos, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Dataform (roles/dataform.editor) en los espacios de trabajo. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear un archivo JavaScript para varias declaraciones de fuentes de datos

Almacena los archivos JavaScript de las declaraciones de fuentes de datos en el directorio definitions/. Para crear un archivo JavaScript en el directorio definitions/, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. En el panel Archivos, junto a definitions/, haz clic en el menú Más.

  5. Haz clic en Crear archivo.

  6. En el panel Crear archivo, haz lo siguiente:

    1. En el campo Añadir una ruta de archivo, después de definitions/, introduce el nombre del archivo seguido de .js. Por ejemplo, definitions/declarations.js.

      Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

    2. Haz clic en Crear archivo.

Añadir una declaración a un archivo JavaScript

Puedes declarar varias fuentes de datos por archivo JavaScript. Para añadir una nueva declaración, sigue estos pasos:

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, haz clic en el archivo JavaScript de las declaraciones de la fuente de datos.

  2. En el archivo, añade el siguiente fragmento de código para cada fuente de datos:

      declare({
    database: "DATABASE_PROJECT_ID",
    schema: "BIGQUERY_SCHEMA",
    name: "RELATION_NAME",
  });

    Haz los cambios siguientes:

    • DATABASE_PROJECT_ID: ID del proyecto que contiene la fuente de datos.
    • BIGQUERY_SCHEMA: el conjunto de datos de BigQuery en el que se encuentra la fuente de datos.
    • RELATION_NAME: el nombre de la tabla o la vista que quieras usar como fuente de datos. Más adelante, puede usar ese nombre para hacer referencia a la fuente de datos en Dataform.

Crear un archivo SQLX para la declaración de la fuente de datos

Almacena los archivos SQLX de las declaraciones de fuentes de datos en el directorio definitions/. Para crear un archivo SQLX en el directorio definitions/, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Dataform.

    Ir a la página de Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

  4. En el panel Archivos, junto a definitions/, haz clic en el menú Más.

  5. Haz clic en Crear archivo.

  6. En el panel Crear archivo, haz lo siguiente:

    1. En el campo Añadir una ruta de archivo, después de definitions/, introduce el nombre del archivo seguido de .sqlx. Por ejemplo, definitions/dataset-declaration.sqlx.

      Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.

    2. Haz clic en Crear archivo.

Declarar una fuente de datos

Puedes declarar una fuente de datos por archivo de declaración SQLX. Para declarar una fuente de datos en el bloque de configuración de un archivo SQLX, sigue estos pasos:

  1. En el espacio de trabajo de desarrollo, en el panel Archivos, haz clic en el archivo SQLX para declarar la fuente de datos.

  2. En el archivo, introduce el siguiente fragmento de código:

    config {
  type: "declaration",
  database: "DATABASE",
  schema: "SCHEMA",
  name: "NAME",
}

    Haz los cambios siguientes:

    • DATABASE: ID del proyecto que contiene la fuente de datos.
    • SCHEMA: el conjunto de datos de BigQuery en el que se encuentra la fuente de datos.
    • NAME: el nombre de la tabla o la vista que quieras usar como fuente de datos. Más adelante, puede usar ese nombre para hacer referencia a la fuente de datos en Dataform.

  3. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestra una declaración de ejemplo de la tabla shakespeare en el conjunto de datos samples del proyecto bigquery-public-data como fuente de datos:

    config {
      type: "declaration",
      database: "bigquery-public-data",
      schema: "samples",
      name: "shakespeare",
    }

Siguientes pasos