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 externas a Dataform te permite tratar esas fuentes de datos como objetos de Dataform.

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

  • Haz referencia a las fuentes declaradas o resuélvelas de la misma manera que cualquier otra tabla en Dataform.
  • Visualiza las fuentes declaradas en el gráfico de Dataform.
  • Usa Dataform para administrar las descripciones a nivel de la tabla y la columna de las tablas creadas de forma externa.
  • Activa invocaciones de flujos de trabajo que incluyen todos los elementos dependientes 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 requeridos

Para obtener los permisos que necesitas para declarar una fuente de datos, pídele a tu administrador que te otorgue el rol de IAM de Editor de Dataform (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 a través de 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.

    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 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.

Cómo agregar una declaración a un archivo JavaScript

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

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, haz clic en tu archivo JavaScript para las declaraciones de la fuente 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: Es 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, podrás 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.

    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 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.

Declara una fuente de datos

Puedes declarar una fuente de datos por archivo de declaración de 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 Archivos, 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: Es 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, podrás usar ese nombre para hacer referencia a la fuente de datos en Dataform.

  3. Opcional: Haz clic en Formato.

En el siguiente muestra 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",
    }

¿Qué sigue?