Instalar um pacote no Dataform

Neste documento, mostramos como instalar um pacote JavaScript em um repositório do Dataform e importá-lo para um arquivo JavaScript e um arquivo SQLX. Assim, você poderá usar o pacote para desenvolver fluxos de trabalho SQL no Dataform.

Para usar um pacote no Dataform, é necessário 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, importe 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] Autentique o pacote particular para instalá-lo.

Funções exigidas

Para receber as permissões necessárias para importar um pacote, peça ao administrador para conceder a você o papel do IAM 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 de outros papéis predefinidos.

Instalar um pacote em um repositório do Dataform

Para instalar um pacote dentro de um repositório do Dataform, é preciso 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. Se você não tiver um arquivo package.json porque o workflow_settings.yaml especifica seu dataformCoreVersion, remova o dataformCoreVersion de workflow_settings.yaml, crie um arquivo package.json e adicione @dataform/core como uma dependência.

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

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

  2. Adicione o pacote ao bloco dependencies:

    1. Adicione um pacote NPM público publicado no seguinte formato:

      "PACKAGE-NAME": "PACKAGE-VERSION"

      Substitua:

      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-VERSION pela versão mais recente do pacote NPM público 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, como https://github.com/user/sample-package-repository/archive/master.tar.gz.

    3. Adicione um pacote NPM particular autenticado 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 do repositório.
      • PACKAGE-NAME pelo nome do pacote.
      • PACKAGE-URL pelo URL tar.gz do repositório do pacote, como https://github.com/user/sample-package-repository/archive/master.tar.gz.

  3. Clique em Install packages.

  4. Confirme e push as alterações.

O exemplo de código a seguir mostra o pacote público de dimensões que mudam lentamente e foi 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 ou constante de pacote 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 você precisa importá-la 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 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 de pacote index.js.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e push 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 painel Files do espaço de trabalho, selecione um arquivo .js em que você quer usar o pacote.

  2. No arquivo, importe o pacote neste 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 push 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, você precisa primeiro importá-la para o arquivo.

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

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

  2. No arquivo, insira 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 do pacote index.js.
    2. Substitua PACKAGE-NAME pelo nome do pacote que você quer usar.

  3. Confirme e push as alterações.

O exemplo de código a seguir mostra a função getDomain do pacote postoffice, importada 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 Files, selecione um arquivo .sqlx em que você quer usar o pacote.

  2. No arquivo, importe o pacote neste 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 push 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