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 SQL localmente usando o terminal.

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

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

Antes de começar

Antes de instalar a CLI do Dataform, instale o NPM.

Instalar a CLI do Dataform

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

    npm i -g @dataform/cli@^3.0.0-beta

Inicializar um projeto do Dataform

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Substitua:

    • PROJECT_NAME: o nome do projeto.
    • DEFAULT_LOCATION: a região em que você quer que o Dataform grave dados do BigQuery. Para mais informações sobre as regiões do BigQuery, consulte Locais do BigQuery.

Atualizar o núcleo do Dataform

  • Para atualizar o framework principal do Dataform, atualize o dataformCoreVersion no arquivo workflow_settings.yaml e execute novamente o NPM install:

    npm i

Atualizar a CLI do Dataform

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

    npm i -g @dataform/cli@^3.0.0-beta.2

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.

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 vazio do Dataform no núcleo do Dataform 3.0.0-beta.0 ou mais recente tem a seguinte estrutura:

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

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

    dataform init PROJECT_NAME --default-project YOUR_GOOGLE_CLOUD_PROJECT_ID

    Substitua:

    • PROJECT_NAME: o nome do projeto.
    • YOUR_GOOGLE_CLOUD_PROJECT_ID: o ID do Google Cloud projeto.

Clonar um projeto

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

  • Depois que o repositório for clonado, execute o comando abaixo no diretório do repositório clonado:

    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 abaixo 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 de operação SQL personalizado.

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 de operação SQL personalizado.

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.

Executar código

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

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

    dataform run

  • Para executar o código do seu 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 seu projeto do Dataform no BigQuery e recriar todas as tabelas do zero, execute o seguinte comando:

    dataform run --full-refresh

Sem --full-refresh, o Dataform atualiza tabelas incrementais sem reconstruí-las do zero.

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

    dataform run --dry-run

Receba 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