Use a CLI de código aberto do Dataform

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

Com a CLI de código aberto do Dataform, você pode 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 o aplicativo de várias maneiras. de ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo. Para usar o ADC, você precisa primeiro forneça suas credenciais ao ADC.

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@^3.0.0-beta

Inicializar um projeto do Dataform

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

    dataform init . PROJECT_NAME DEFAULT_LOCATION

    Substitua:

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

Atualizar o Dataform

  • Para atualizar o framework 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 da 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 crie 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 do init-creds, que ensina a criar arquivos de credenciais.

Crie um projeto

Um projeto vazio do Dataform 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 e implantar recursos no BigQuery, faça o seguinte: 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: é seu ID do projeto no Google Cloud.

Clonar um projeto

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

  • Depois que o repositório for clonado, execute o seguinte comando em o 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 de 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 da operação SQL personalizada. de definição de código.

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 da operação SQL personalizada. de definição de código.

Ver 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, faça o seguinte: execute o seguinte comando:

    dataform compile

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

    dataform compile --json

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

Executar código

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

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

    dataform run

  • 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 do 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í-los do zero.

  • Para conferir o código SQL compilado final adaptado ao estado atual de sem executá-lo 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 a descrição de um comando específico, execute o seguinte comando:

    dataform help COMMAND

    Substitua COMMAND pelo comando que você quer conhecer melhor.

A seguir