Crea flujos de trabajo de SQL de Dataform con JavaScript

En este documento, se muestra cómo usar JavaScript para crear elementos de flujo de trabajo de SQL en Dataform. Te recomendamos que uses JavaScript en lugar del núcleo de Dataform para crear elementos similares de forma repetida en tu flujo de trabajo.

Información acerca del desarrollo de flujos de trabajo en Dataform con JavaScript

Dataform Core te permite crear acciones de flujos de trabajo de SQL con SQLX y JavaScript. Con JavaScript, puedes crear acciones similares de manera repetida en tu flujo de trabajo. Por ejemplo, puedes crear una vista de cada tabla en tu flujo de trabajo sin ciertos IDs de usuario.

La siguiente muestra de código JavaScript te permite crear una vista de cada tabla en la que el valor del campo user_id no corresponde a uno de los valores de la lista blocked_user_ids:

  const tableNames = ["user_events", "user_settings", "user_logs"];

  tableNames.forEach(tableName => {
    publish(tableName + "_blocked_removed").query(
      ctx => `
        SELECT * FROM ${ctx.ref(tableName)}
        WHERE user_id NOT IN (
          SELECT user_id
          FROM ${ctx.ref("blocked_user_ids")}
        )`
    );
  });

En esta muestra de código, se crean tres vistas llamadas user_events_blocked_removed, user_settings_blocked_removed y user_logs_blocked_removed que no contienen ninguno de los IDs de usuario bloqueados.

Puedes crear varias acciones en un archivo JavaScript con los métodos globales de Dataform y el código JavaScript ES5 arbitrario, como bucles y constantes.

Puedes definir las siguientes acciones con JavaScript en Dataform:

Antes de comenzar

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

    Ir a Dataform

  2. Selecciona o crea un repositorio.

  3. Selecciona o crea un lugar de trabajo de desarrollo.

Funciones obligatorias

Si quieres obtener los permisos necesarios para desarrollar un flujo de trabajo de SQL con JavaScript, pídele a tu administrador que te otorgue el rol de IAM de Editor de Dataform (roles/dataform.editor) en los lugares de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Es posible que también puedas obtener los permisos necesarios a través de los roles personalizados o de otros roles predefinidos.

Crea un archivo JavaScript en Dataform

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

  1. En el panel Files, junto a definitions/, haz clic en el menú More de .

  2. Haz clic en Crear archivo.

  3. En el panel Create new file, haz lo siguiente:

    1. En el campo Agregar una ruta del archivo, después de definitions/, ingresa el nombre del archivo seguido de .js. Por ejemplo, definitions/definitions.js

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

    2. Haz clic en Crear archivo.

Configura propiedades del objeto de flujo de trabajo de SQL de Dataform con JavaScript

Puedes usar los siguientes métodos globales de Dataform para crear objetos de flujo de trabajo de SQL con Dataform:

  • declare: Se usa para declarar una fuente de datos.
  • publish: Se usa para definir una tabla.
  • assert: Se usa para crear una aserción.
  • operate: Se usa para definir una operación de SQL personalizada.

Cada uno de los métodos globales contiene propiedades que puedes usar para configurar el objeto creado. Para obtener más información sobre los métodos globales y sus propiedades, consulta la referencia principal de Dataform.

En el método publish() que crea una tabla, puedes establecer las propiedades de la tabla si las pasas como el segundo argumento del método.

Para pasar las propiedades de la tabla como el segundo argumento de publish(), sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.

  2. Selecciona un archivo JavaScript.

  3. En el archivo, agrega las propiedades de la tabla al método publish() en el siguiente formato:

     method("first_method_argument", {
   property1: "property1_value",
   property2: "property2_value",
   property3: "property3_value",
 });

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se indica cómo establecer propiedades en el método publish() pasando las propiedades como un segundo argumento del método:

  publish("table1", {
    type: "table",
    dependencies: ["other_table"],
    description: {
      "Value is 1"
    }
  }).query(ctx => "SELECT 1 AS test");

Incluye referencias en un archivo JavaScript

Puedes hacer referencia a cualquier función de inclusión, macro o constante dentro de un archivo JavaScript. Para obtener más información sobre las inclusiones en Dataform, consulta Reutiliza variables y funciones con inclusiones de JavaScript.

La sintaxis para hacer referencia a inclusiones dentro de un archivo JavaScript depende de la ubicación del archivo de inclusión. Dataform almacena estos archivos en el directorio include.

Las referencias de nivel superior incluyen lo siguiente:

  • Para hacer referencia a un archivo de inclusión de nivel superior, haz referencia al nombre del archivo cuando declares las variables.

En la siguiente muestra de código, se hace referencia a las variables serviceName y serviceId del archivo includes/service.js:

  const {serviceName, serviceId} = service;

Inclusiones anidadas de referencia

Para hacer referencia a un archivo de inclusión anidado, ingresa el nombre del archivo en la función obligatorio de JavaScript.

En la siguiente muestra de código, se hace referencia a las variables serviceName y serviceId del archivo includes/allServices/service.js:

  const {serviceName, serviceId} = require("includes/allServices/service.js");

Usa funciones de consulta de Dataform en métodos de JavaScript

Dataform proporciona una serie de funciones integradas que puedes usar dentro de las consultas, como ref y self. Para obtener más información sobre las funciones integradas de Dataform, consulta la referencia de la API de Dataform.

Para usar una función de consulta integrada en un método de JavaScript, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.

  2. Selecciona un archivo JavaScript.

  3. En el archivo, ingresa un método global de Dataform JavaScript.

  4. En el método, ingresa un argumento ctx contextual.

  5. Opcional: Si usas strings de plantillas de JavaScript, encierra el argumento contextual entre acentos graves ``.

  6. En el argumento contextual, ingresa la función de consulta con su parámetro como un objeto de contexto.

  7. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observa la función de consulta ref unida a un argumento contextual del método de publicación:

  publish("example").query(ctx => `SELECT * FROM ${ctx.ref("other_table")}`);

Declara una fuente de datos de flujo de trabajo de SQL con JavaScript

Puedes declarar varias fuentes de datos en un archivo de declaración de JavaScript con el método de declaración de JavaScript de Dataform. Para obtener más información sobre el método de declaración, consulta la referencia principal de Dataform. Para obtener más información sobre las fuentes de datos en Dataform, consulta la sección sobre cómo declarar una fuente de datos.

Para declarar una fuente de datos en un archivo JavaScript, sigue estos pasos:

  1. En tu lugar de trabajo de desarrollo, en el panel Files, expande definiciones/.

  2. Selecciona un archivo JavaScript.

  3. En el archivo, ingresa 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 relación externa.
    • RELATION_NAME: Es el nombre de la relación que más adelante puedes usar para hacer referencia a la fuente de datos en Dataform.

  4. Para declarar otra fuente de datos en el mismo archivo, agrega un bloque declare adicional al archivo.

  5. Opcional: Haz clic en Formato.

Cómo definir una tabla con JavaScript

Puedes crear una tabla con el método publish de JavaScript de Dataform. Si quieres obtener más información sobre el método de publicación, consulta la referencia principal de Dataform.

Puedes definir los siguientes tipos de tablas: tabla, tabla incremental y vista. Si quieres obtener más información para definir tablas en Dataform, consulta Crea una tabla.

Para definir una tabla en un archivo JavaScript, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.

  2. Selecciona un archivo JavaScript.

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

     publish("TABLE_NAME").query(ctx => "SELECT_QUERY");

    1. Reemplaza TABLE_NAME por el nombre de la tabla.

    2. Reemplaza SELECT_QUERY por una instrucción SELECT de SQL que define la tabla.

  4. Para establecer el tipo de tabla, agrega sus dependencias y agrega una descripción de la tabla, establece las propiedades del objeto del método publish.

  5. Para definir otra tabla en el mismo archivo, repite los pasos 3 y 4.

  6. Opcional: Haz clic en Formato.

Define aserciones manuales de Dataform con JavaScript

Puedes crear aserciones de SQL manuales en un archivo JavaScript con el método de JavaScript de aserción de Dataform. Para obtener más información sobre el método de aserción, consulta la referencia principal de Dataform.

Una consulta en SQL de aserción manual no debe mostrar ninguna fila. Si la consulta muestra filas cuando se ejecuta, la aserción falla. Puedes crear varias aserciones en un archivo JavaScript.

Para obtener más información sobre las aserciones en Dataform, consulta Cómo probar tablas con aserciones.

Para crear una aserción manual en un archivo JavaScript, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.

  2. Selecciona un archivo JavaScript.

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

     assert("<var>ASSERTION_NAME</var>").query(ctx => "<var>CUSTOM_ASSERTION_QUERY</var>");

    1. Reemplaza ASSERTION_NAME por el nombre de tu aserción personalizada.

    2. Reemplaza CUSTOM_ASSERTION_QUERY por tu consulta de aserción de SQL.

  4. Para crear otra aserción en el mismo archivo, repite el paso 3.

  5. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se incluye una aserción de JavaScript que afirma que ningún valor en source_table es NULL:

  assert("assertion1").query(ctx => "SELECT * FROM source_table WHERE value IS NULL");

Define operaciones de SQL personalizadas con JavaScript

Puedes definir operaciones personalizadas de SQL en un archivo JavaScript con el método de JavaScript que opera Dataform. Para obtener más información sobre las operaciones de SQL personalizadas en Dataform, consulta Agrega operaciones de SQL personalizadas.

Para definir una operación de SQL personalizada con JavaScript, sigue estos pasos:

  1. En el lugar de trabajo de desarrollo, en el panel Files, expande definitions/.

  2. Selecciona un archivo JavaScript.

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

     operate("OPERATION_NAME").queries(ctx => "CUSTOM_SQL_QUERY");

    1. Reemplaza OPERATION_NAME por el nombre de la operación personalizada.

    2. Reemplaza CUSTOM_SQL_QUERY por tu consulta en SQL personalizada.

  4. Para definir otra operación de SQL personalizada en el mismo archivo, repite el paso 3.

  5. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se observa una operación de SQL personalizada en un archivo JavaScript que inserta una única fila nueva en some_table y establece el test_column de la fila nueva en 2:

  operate("operation1").queries("INSERT INTO some_table (test_column) VALUES (2)");

¿Qué sigue?