Cómo declarar una fuente de datos

En este documento, se muestra 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. Declarar fuentes de datos de BigQuery que son externas a Dataform te permite tratarlas como objetos de Dataform.

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

  • Haz referencia a las fuentes declaradas o resuélvelas de la misma manera que cualquier otra tabla en Dataform.
  • Consulta las fuentes declaradas en el gráfico de Dataform visualizado.
  • Usa Dataform para administrar las descripciones a nivel de la tabla y de la columna de las tablas creadas de forma externa.
  • Activa invocaciones de flujos de trabajo que incluyan todas las dependencias de una fuente de datos externa.

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

Antes de comenzar

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, pídele a tu administrador que te otorgue el rol de IAM Editor de formularios de datos (roles/dataform.editor) en los espacios de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea un archivo JavaScript para varias declaraciones de fuentes de datos

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

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

    Ve a la página Dataform

  2. Selecciona un repositorio.

  3. Selecciona un lugar 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 un archivo nuevo, haz lo siguiente:

    1. En el campo Agregar una ruta de archivo, después de definitions/, ingresa 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.

Agrega una declaración a un archivo JavaScript

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

  1. En tu lugar de trabajo de desarrollo, en el panel Files, haz clic en tu archivo JavaScript para ver las declaraciones de fuentes de datos.

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

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

    Reemplaza lo siguiente:

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

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

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

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

    Ve a la página Dataform

  2. Selecciona un repositorio.

  3. Selecciona un lugar 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 un archivo nuevo, haz lo siguiente:

    1. En el campo Agregar una ruta de archivo, después de definitions/, ingresa 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.

Cómo 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 tu espacio de trabajo de desarrollo, en el panel Files, haz clic en tu archivo SQLX para la declaración de la fuente de datos.

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

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

    Reemplaza lo siguiente:

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

  3. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra una declaración de muestra 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",
    }

¿Qué sigue?