Instalar um pacote no Dataform

Este documento mostra como instalar um pacote JavaScript em um repositório do Dataform e importá-lo para um arquivo JavaScript e um arquivo SQLX para usar o pacote a fim de desenvolver fluxos de trabalho SQL no Dataform.

Para usar um pacote no Dataform, você precisa instalá-lo no seu repositório.

É possível instalar os seguintes tipos de pacotes no Dataform:

Em seguida, para usar o pacote em um arquivo JavaScript ou SQLX, é necessário importar o conteúdo selecionado do pacote para o arquivo. Você também pode importar um pacote inteiro para um arquivo JavaScript ou SQLX em vez do conteúdo selecionado.

Antes de começar

  1. No Console do Google Cloud, acesse a página do Dataform.

    Acessar a página do Dataform

  2. Selecione ou crie um repositório.

  3. Selecione ou crie um espaço de trabalho de desenvolvimento.

  4. [Opcional] Para instalar um pacote particular, autentique o pacote particular.

Funções exigidas

Para conseguir as permissões necessárias para importar um pacote, peça ao administrador que conceda a você o papel de editor do Dataform (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Instalar um pacote em um repositório do Dataform

Para instalar um pacote dentro de um repositório do Dataform, é necessário adicioná-lo como uma dependência no arquivo package.json. O formato da definição de dependência no arquivo package.json depende do tipo do pacote.

Para instalar um pacote em um repositório do Dataform, siga estas etapas:

  1. No espaço de trabalho, no painel Files, selecione package.json.

  2. Adicione o pacote ao bloco dependencies:

    1. Adicione um pacote NPM publicado no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Substitua:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-VERSION pela versão mais recente do pacote público do NPM publicado.

    2. Adicione um pacote NPM público não publicado no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-URL"

      Substitua:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-URL pelo URL tar.gz do repositório de pacotes de terceiros, por exemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Adicione um pacote NPM autenticado particular no seguinte formato:

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

      Substitua:

      • REGISTRY-SCOPE pelo nome do pacote. REGISTRY-SCOPE precisa corresponder ao escopo do registro definido no arquivo .nmprc no seu repositório.
      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-URL pelo URL tar.gz do repositório de pacotes, por exemplo, https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Clique em Instalar pacotes.

  4. Confirme e envie as alterações.

A exemplo de código a seguir mostra o pacote de pacote de dimensões com código aberto que foi alterado lentamente adicionado ao arquivo .package.json:

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

Importar uma função de pacote ou constante para um arquivo JavaScript no Dataform

Para usar uma função ou uma constante de um pacote dentro de um arquivo JavaScript no Dataform, primeiro é necessário importá-lo para o arquivo.

Para importar uma função ou uma constante de um pacote para um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho, no painel Arquivos, selecione um arquivo .js em que você quer usar o pacote.

  2. No arquivo, importe uma função ou uma constante no seguinte formato:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. Substitua EXPORT-NAME pelo nome da função ou constante que você quer usar, declarada em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie as alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice importado e usado em um arquivo JavaScript:

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

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

Importar um pacote inteiro para um arquivo JavaScript no Dataform

Para importar todo o pacote para um arquivo JavaScript, em vez de importar funções ou constantes selecionadas para um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho, no painel Arquivos, selecione um arquivo .js em que você quer usar o pacote.

  2. No arquivo, importe o pacote no seguinte formato:

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. Substitua CONSTANT-NAME por um nome para a constante.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie as alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice importado usado em um arquivo JavaScript:

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

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

Importar uma função de pacote ou constante para um arquivo SQLX no Dataform

Para usar uma função ou uma constante de um pacote dentro de um arquivo SQLX, primeiro é necessário importá-lo para o arquivo.

Para importar uma função ou uma constante de um pacote para um arquivo SQLX, siga estas etapas:

  1. No espaço de trabalho, no painel Arquivos, selecione um arquivo .sqlx em que você quer usar o pacote.

  2. No arquivo, digite o seguinte bloco js:

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. Substitua EXPORT-NAME pelo nome da função ou constante que você quer usar, declarada em module.exports no arquivo index.js do pacote.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie as alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice importado em um bloco js e usada em uma instrução SELECT em um arquivo SQLX:

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

config {
    type: "table",
}

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

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

Importar um pacote inteiro para um arquivo SQLX no Dataform

Para importar todo o pacote para um arquivo SQLX em vez de importar funções ou constantes selecionadas para um arquivo JavaScript, siga estas etapas:

  1. No espaço de trabalho, no painel Arquivos, selecione um arquivo .sqlx em que você quer usar o pacote.

  2. No arquivo, importe o pacote no seguinte formato:

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. Substitua CONSTANT-NAME por um nome para a constante.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e envie as alterações.

O exemplo de código a seguir mostra o pacote postoffice importado em um bloco js e a função getDomain usada em uma instrução SELECT em um arquivo SQLX:

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

config {
    type: "table",
}

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

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

A seguir