Use a CLI Dataform de código aberto

Este documento mostra-lhe como usar a interface de linhas de comando (CLI) de código aberto do Dataform para desenvolver fluxos de trabalho localmente através do terminal.

Com a CLI do Dataform de código aberto, pode inicializar, compilar, testar e executar o Dataform core localmente, fora do Google Cloud.

A CLI Dataform suporta Credenciais padrão da aplicação (ADC). Com o ADC, pode disponibilizar credenciais à sua aplicação numa variedade de ambientes, como desenvolvimento local ou produção, sem ter de modificar o código da aplicação. Para usar o ADC, primeiro tem de fornecer as suas credenciais ao ADC.

Antes de começar

Antes de instalar a CLI Dataform, instale o NPM.

Instale a CLI Dataform

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

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

Inicialize 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 o seguinte:

    • PROJECT_NAME: o nome do seu projeto.

    • DEFAULT_LOCATION (opcional): a localização onde quer que o Dataform escreva dados do BigQuery. Se não estiver definido, o Dataform determina a localização com base nos conjuntos de dados aos quais a sua consulta SQL faz referência. Funciona da seguinte forma:

      • Se a sua consulta fizer referência a conjuntos de dados da mesma localização, o Dataform usa essa localização.
      • Se a sua consulta fizer referência a conjuntos de dados de duas ou mais localizações diferentes, ocorre um erro. Para ver detalhes acerca desta limitação, consulte o artigo Replicação de conjuntos de dados entre regiões.
      • Se a sua consulta não fizer referência a nenhum conjunto de dados, a localização predefinida do Dataform é a multirregião US. Para escolher uma localização diferente, defina a localização predefinida. Em alternativa, use a @@location variável do sistema na sua consulta. Para mais informações, consulte o artigo Especifique localizações.

Atualize o Dataform Core

  • Para atualizar a framework principal do Dataform, atualize o ficheiro dataformCoreVersion in workflow_settings.yaml e, em seguida, volte a executar a instalação do NPM:

    npm i

Atualize 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

Crie um ficheiro de credenciais

O Dataform requer um ficheiro de credenciais para estabelecer ligação a serviços remotos e criar o ficheiro .df-credentials.json no seu disco.

Para criar o ficheiro de credenciais, siga estes passos:

  1. Execute o seguinte comando:

    dataform init-creds

  2. Siga o init-credsassistente que explica a criação do ficheiro de credenciais.

Criar um projeto

Um projeto do Dataform vazio no Dataform core 3.0.0-beta.0 ou posterior tem a seguinte estrutura:

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

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

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

    Substitua o seguinte:

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

    • DEFAULT_LOCATION (opcional): a localização onde quer que o Dataform escreva dados do BigQuery. Se não estiver definido, o Dataform determina a localização com base nos conjuntos de dados aos quais a sua consulta SQL faz referência. Funciona da seguinte forma:

      • Se a sua consulta fizer referência a conjuntos de dados da mesma localização, o Dataform usa essa localização.
      • Se a sua consulta fizer referência a conjuntos de dados de duas ou mais localizações diferentes, ocorre um erro. Para ver detalhes acerca desta limitação, consulte o artigo Replicação de conjuntos de dados entre regiões.
      • Se a sua consulta não fizer referência a nenhum conjunto de dados, a localização predefinida do Dataform é a multirregião US. Para escolher uma localização diferente, defina a localização predefinida. Em alternativa, use a @@location variável do sistema na sua consulta. Para mais informações, consulte o artigo Especifique localizações.

Clone um projeto

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

  • Depois de clonar o repositório, execute o seguinte comando no diretório do repositório clonado:

    dataform install

Defina uma tabela

Armazenar definições na pasta definitions/.

  • Para definir uma tabela, execute o seguinte comando:

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

    Substitua o seguinte:

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

O seguinte exemplo de código define uma vista no ficheiro example SQLX.

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

Defina uma declaração manual

Armazenar definições na pasta definitions/.

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

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

    Substitua o seguinte:

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

Defina uma operação de SQL personalizada

Armazenar 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 o seguinte:

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

Veja a saída da compilação

O Dataform compila o seu código em tempo real.

  • Para ver o resultado do processo de compilação no terminal, execute o seguinte comando:

    dataform compile

  • Para ver o resultado do processo de compilação como um objeto JSON, execute o seguinte comando:

    dataform compile --json

  • Para ver o resultado da compilação com variáveis de compilação personalizadas, execute o seguinte comando:

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

    Substitua o seguinte:

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

Executar código

Para executar o código, o Dataform acede ao BigQuery para determinar o respetivo estado atual e adaptar o SQL resultante em conformidade.

  • 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 o seguinte:

    • SAMPLE_VAR: a 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 seu projeto do Dataform no BigQuery e reconstruir todas as tabelas de raiz, execute o seguinte comando:

    dataform run --full-refresh

Sem o --full-refresh, o Dataform atualiza as tabelas incrementais sem as reconstruir de raiz.

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

    dataform run --dry-run

Obtenha ajuda

  • Para apresentar uma lista de todos os comandos e opções disponíveis, execute o seguinte comando:

    dataform help

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

    dataform help COMMAND

    Substitua COMMAND pelo comando sobre o qual quer saber mais.

O que se segue?