Usar a CLI do Dataform de código aberto

Neste documento, mostramos como usar a interface de linha de comando (CLI) do Dataform de código aberto para desenvolver fluxos de trabalho localmente usando o terminal.

Com a CLI do Dataform de código aberto, é possível inicializar, compilar, testar, e executar o Dataform Core localmente, fora do Google Cloud.

A CLI do Dataform oferece suporte ao Application Default Credentials (ADC). Com o ADC, é possível disponibilizar credenciais para seu aplicativo em uma variedade de ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo. Para usar o ADC, primeiro é necessário fornecer suas credenciais a ele.

Observação: a partir do Dataform core 3.0.0., o Dataform não distribui uma imagem Docker. É possível criar sua própria imagem Docker do Dataform, que pode ser usada para executar o equivalente aos comandos da CLI do Dataform. Para criar sua própria imagem do Docker, consulte Containerizar um aplicativo na documentação do Docker.

Antes de começar

Antes de instalar a CLI do Dataform, instale NPM.

Instalar a CLI do Dataform

• Para instalar a CLI do Dataform, execute o seguinte comando:

  npm i -g @dataform/cli
  

Observação: A versão 3.0.0-beta não é compatível. Se npm audit informar uma vulnerabilidade de alta gravidade relacionada ao pacote vm2, observe que, embora o Dataform use vm2, ele não usa vm2 para o ambiente de simulação, que é a origem das vulnerabilidades informadas. As versões mais recentes da CLI do Dataform não dependem de versões vulneráveis do vm2.

Inicializar um projeto do Dataform

• Para inicializar um novo projeto do Dataform, execute o seguinte comando no diretório do projeto:

  dataform init . YOUR_GOOGLE_CLOUD_PROJECT_ID DEFAULT_LOCATION
  

  Substitua:

  • YOUR_GOOGLE_CLOUD_PROJECT_ID: o Google Cloud ID do projeto.
  • DEFAULT_LOCATION: o local do BigQuery em que você quer que o Dataform processe e armazene dados.

Atualizar o Dataform Core

• Para atualizar o framework do Dataform Core, atualize dataformCoreVersion no arquivo workflow_settings.yaml. Quando dataformCoreVersion é definido em workflow_settings.yaml, o Dataform instala @dataform/core automaticamente no ambiente de execução. Se o projeto gerenciar @dataform/core em um arquivo package.json sem dataformCoreVersion em workflow_settings.yaml, atualize a versão em package.json e execute:

  dataform install
  

Atualizar a CLI do Dataform

• Para atualizar a ferramenta da CLI do Dataform, execute o seguinte comando:

  npm i -g @dataform/cli@^3.0.50
  

Criar um arquivo de credenciais

O Dataform exige um arquivo de credenciais para se conectar a serviços remotos e criar o arquivo .df-credentials.json no disco.

Aviso:Se você usar um sistema de controle de origem, não confirme o arquivo .df-credentials.json no repositório para proteger essas credenciais de acesso. Recomendamos adicionar o arquivo .df-credentials.json ao .gitignore.

Para criar o arquivo de credenciais, siga estas etapas:

1. Execute este comando:

   dataform init-creds
   

2. Siga o assistente init-creds que orienta você na criação do arquivo de credenciais.

Criar um projeto

Um projeto do Dataform vazio no Dataform Core 3.0.0 ou mais recente tem a seguinte estrutura:

   project-dir
   ├── definitions
   ├── includes
   └── workflow_settings.yaml

• Para criar um projeto do Dataform para implantar recursos no BigQuery, execute o seguinte comando:

  dataform init PROJECT_NAME --default-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
  

  Substitua:

  • PROJECT_NAME: o nome do diretório do projeto.
  • YOUR_GOOGLE_CLOUD_PROJECT_ID: o Google Cloud ID do projeto.
  • DEFAULT_LOCATION: o local do BigQuery em que você quer que o Dataform processe e armazene dados.

Clonar um projeto

Para clonar um projeto do Dataform de um repositório Git de terceiros, siga as instruções do provedor Git.

• Se o projeto clonado declarar dependências externas em um arquivo package.json (sem dataformCoreVersion em workflow_settings.yaml), execute o seguinte comando no diretório do repositório clonado:

  dataform install
  

Observação: Os projetos que especificam dataformCoreVersion em workflow_settings.yaml instalam @dataform/core automaticamente no ambiente de execução e não exigem a execução de dataform install.

Definir uma tabela

Armazene as definições na pasta definitions/.

• Para definir uma tabela, execute o seguinte comando:

  echo "config { type: 'TABLE_TYPE' } SELECT_STATEMENT" > definitions/FILE.sqlx
  

  Substitua:

  • TABLE_TYPE: o tipo da tabela: table, incremental ou view.
  • SELECT_STATEMENT: uma instrução SELECT que define a tabela.
  • FILE: o nome do arquivo de definição da tabela.

O exemplo de código a seguir define uma visualização no arquivo SQLX example.

echo "config { type: 'view' } SELECT 1 AS test" > definitions/example.sqlx

Definir uma declaração manual

Armazene as definições na pasta definitions/.

• Para definir uma declaração manual, execute o seguinte comando:

  echo "config { type: 'assertion' } SELECT_STATEMENT" > definitions/FILE.sqlx
  

  Substitua:

  • SELECT_STATEMENT: uma instrução SELECT que define a declaração.
  • FILE: o nome do arquivo de definição da operação SQL personalizada.

Definir uma operação SQL personalizada

Armazene as definições na pasta definitions/.

• Para definir uma operação SQL personalizada, execute o seguinte comando:

  echo "config { type: 'operations' } SQL_QUERY" > definitions/FILE.sqlx
  

  Substitua:

  • SQL_QUERY: sua operação SQL personalizada.
  • FILE: o nome do arquivo de definição da operação SQL personalizada.

Conferir a saída da compilação

O Dataform compila seu código em tempo real.

• Para conferir a saída do processo de compilação no terminal, execute o seguinte comando:

  dataform compile
  

• Para conferir a saída do processo de compilação como um objeto JSON, execute o seguinte comando:

  dataform compile --json
  

• Para conferir a saída da compilação com variáveis de compilação personalizadas, execute o seguinte comando:

  dataform compile --vars=SAMPLE_VAR=SAMPLE_VALUE,foo=bar
  

  Substitua:

  • SAMPLE_VAR: sua variável de compilação personalizada.
  • SAMPLE_VALUE: o valor da variável de compilação personalizada.

Gerar código

Para executar o código, o Dataform acessa o BigQuery para determinar o estado atual e adaptar o SQL resultante de acordo.

• Para executar o código do projeto do Dataform, execute o seguinte comando:

  dataform run
  

• Para executar o código do projeto do Dataform no BigQuery com variáveis de compilação personalizadas, execute o seguinte comando:

  dataform run --vars=SAMPLE_VAR=SAMPLE_VALUE,sampleVar2=sampleValue2
  

  Substitua:

  • SAMPLE_VAR: sua variável de compilação personalizada.
  • SAMPLE_VALUE: o valor da variável de compilação personalizada.

• Para executar o código do projeto do Dataform no BigQuery e recriar tabelas incrementais (a menos que marcadas como protected) do zero, execute o seguinte comando:

  dataform run --full-refresh
  

Sem --full-refresh, o Dataform atualiza tabelas incrementais sem recriá-las do zero (tabelas e visualizações normais são sempre recriadas).

• Para executar uma simulação do código no BigQuery, execute o seguinte comando:

  dataform run --dry-run
  

Observação: No Dataform Core 3.0.2 ou mais recente, o Dataform executa uma simulação de cada ação na saída de compilação no BigQuery e exige permissões do IAM correspondentes. Para verificar a compilação sem uma simulação, confira a saída da compilação.

Precisa de ajuda?

• Para listar todos os comandos e opções disponíveis, execute o seguinte comando:

  dataform help
  

• Para conferir uma descrição de um comando específico, execute o seguinte comando:

  dataform help COMMAND
  

  Substitua COMMAND pelo comando sobre o qual você quer saber mais.

A seguir

• Para saber mais sobre os comandos e flags da CLI do Dataform, consulte a referência da CLI do Dataform e a referência da CLI do Dataform no GitHub.
• Para saber mais sobre o Dataform, consulte a visão geral do Dataform.