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 é compatível com 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 ao ADC.

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 (opcional): o local em que você quer que o Dataform grave dados do BigQuery. Se não estiver definido, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

      • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
      • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
      • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

Atualizar o Dataform Core

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

    npm i

Atualizar a CLI do Dataform

  • Para atualizar a ferramenta de linha de comando 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 Dataform Core 3.0.0-beta.0 ou em uma versão 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-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION

    Substitua:

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

    • DEFAULT_LOCATION (opcional): o local em que você quer que o Dataform grave os dados do BigQuery. Se não estiver definido, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

      • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
      • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
      • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

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 seguinte comando 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 a seguir define uma visualização no arquivo example SQLX.

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

Definir uma asserçã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.

Ver saída da compilação

O Dataform compila seu código em tempo real.

  • Para ver 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 sua variável de compilação personalizada.

Gerar código

Para executar seu 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 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 sua variável de compilação personalizada.

  • Para executar o código do 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 as tabelas incrementais sem recriá-las do zero.

  • Para fazer uma simulação do seu código contra o BigQuery, execute o seguinte comando:

    dataform run --dry-run

Precisa de ajuda?

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

    dataform help

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

    dataform help COMMAND

    Substitua COMMAND pelo comando que você quer conhecer.

A seguir