Usa paquetes de JavaScript

Este documento te muestra cómo hacer lo siguiente:

Antes de comenzar

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

    Ir a Dataform

  2. Realiza una o ambas de las siguientes acciones:

    1. Para instalar un paquete en un repositorio o autenticar un paquete privado de NPM para habilitar su instalación, sigue estos pasos:
      1. Selecciona o crea un repositorio.
      2. Selecciona o crea un espacio de trabajo de desarrollo.
      3. Opcional: Para instalar un paquete privado, autentica el paquete privado.
      4. Si tu repositorio no contiene un archivo package.json, crea package.json y mueve el paquete principal de Dataform.
    2. Para crear un paquete, sigue estos pasos:
      1. Crea un repositorio de Dataform dedicado a tu paquete. Haz que el nombre del repositorio coincida con el nombre de tu paquete.
      2. Conecta el repositorio a un repositorio de Git de terceros que alojará tu paquete.
      3. Crea e inicializa un espacio de trabajo en el repositorio de Dataform.

  3. Asegúrate de tener los permisos necesarios para completar las tareas de este documento.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM:

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.

Instala un paquete

En esta sección, se muestra cómo instalar un paquete de JavaScript y cómo importarlo a un archivo de JavaScript y a un archivo SQLX para que puedas usar el paquete y desarrollar flujos de trabajo en Dataform.

Para usar un paquete en Dataform, debes instalarlo en tu repositorio.

Puedes instalar los siguientes tipos de paquetes en Dataform:

Luego, para usar el paquete en un archivo JavaScript o SQLX, debes importar el contenido seleccionado del paquete al archivo. También puedes importar un paquete completo a un archivo JavaScript o SQLX en lugar de su contenido seleccionado.

Para evitar problemas con la instalación de paquetes en tu entorno de producción, te recomendamos que hagas lo siguiente:

Cómo agregar un paquete como dependencia

Para instalar un paquete dentro de un repositorio de Dataform, debes agregarlo como una dependencia en el archivo package.json:

  1. En tu espacio de trabajo, en el panel Archivos, selecciona package.json.

  2. Agrega el paquete al bloque dependencies:

    1. Agrega un paquete público de NPM publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Reemplaza lo siguiente:

      • PACKAGE-NAME con el nombre del paquete.
      • PACKAGE-VERSION con la versión más reciente del paquete de NPM público publicado. Para evitar problemas con la instalación del paquete, especifica la versión de forma explícita, por ejemplo, 3.0.0.

    2. Agrega un paquete público de NPM no publicado con el siguiente formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Reemplaza lo siguiente:

      • PACKAGE-NAME con el nombre del paquete.
      • PACKAGE-URL con la URL tar.gz del repositorio de paquetes de terceros, por ejemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Agrega un paquete privado de NPM autenticado con el siguiente formato:

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      Reemplaza lo siguiente:

      • REGISTRY-SCOPE con el nombre del paquete. REGISTRY-SCOPE debe coincidir con el alcance del registro definido en el archivo .npmrc de tu repositorio.
      • PACKAGE-NAME con el nombre del paquete.
      • PACKAGE-URL con la URL tar.gz del repositorio de paquetes, por ejemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Haz clic en Instalar paquetes.

  4. Confirma y envía tus cambios.

En el siguiente muestra de código, se muestra el paquete de dimensiones que cambian lentamente de código abierto público agregado al archivo .package.json:

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

Importa una función o constante de un paquete a un archivo JavaScript en Dataform

Para usar una función o una constante de un paquete dentro de un archivo JavaScript en Dataform, primero debes importarla al archivo.

Para importar una función o una constante de un paquete a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Archivos, selecciona un archivo .js en el que quieras usar el paquete.

  2. En el archivo, importa una función o una constante con el siguiente formato:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Reemplaza EXPORT-NAME por el nombre de la función o la constante que deseas usar, declarada en module.exports en el archivo del paquete index.js.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En el siguiente muestra de código, se muestra la función getDomain del paquete postoffice importada y utilizada en un archivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

Importa un paquete completo a un archivo JavaScript en Dataform

Para importar todo el paquete a un archivo JavaScript en lugar de importar funciones o constantes seleccionadas a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Archivos, selecciona un archivo .js en el que quieras usar el paquete.

  2. En el archivo, importa el paquete con el siguiente formato:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Reemplaza CONSTANT-NAME por un nombre para la constante.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En el siguiente muestra de código, se muestra la función getDomain del paquete postoffice importado que se usa en un archivo JavaScript:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

Importa una función o constante de paquete a un archivo SQLX en Dataform

Para usar una función o una constante de un paquete dentro de un archivo SQLX, primero debes importarla al archivo.

Para importar una función o una constante de un paquete a un archivo SQLX, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Archivos, selecciona un archivo .sqlx en el que quieras usar el paquete.

  2. En el archivo, ingresa el siguiente bloque js:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Reemplaza EXPORT-NAME por el nombre de la función o la constante que deseas usar, declarada en module.exports en el archivo del paquete index.js.
    2. Reemplaza PACKAGE-NAME por el nombre del paquete que deseas usar.

  3. Confirma y envía tus cambios.

En la siguiente muestra de código, se muestra la función getDomain del paquete postoffice importada en un bloque js y utilizada en una instrucción SELECT en un archivo SQLX:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

Importa un paquete completo a un archivo SQLX en Dataform

Para importar todo el paquete a un archivo SQLX en lugar de importar funciones o constantes seleccionadas a un archivo JavaScript, sigue estos pasos:

  1. En tu espacio de trabajo, en el panel Archivos, selecciona un archivo .sqlx en el que quieras usar el paquete.

  2. En el archivo, importa el paquete con el siguiente formato:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Reemplaza CONSTANT-NAME por un nombre para la constante.