Com a CLI de código aberto do Dataform, é possível inicializar, compilar, testar e executar o Dataform Core localmente, fora do Google Cloud.
O Dataform distribui uma imagem Docker que pode ser usada para executar o equivalente dos comandos da CLI do Dataform.
A CLI do Dataform oferece suporte ao Application Default Credentials (ADC). Com o ADC, é possível disponibilizar credenciais para o aplicativo em vários ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo. Para usar o ADC, é preciso primeiro 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 Dataform
Para atualizar o framework do Dataform, atualize o
dataformCoreVersion
no arquivoworkflow_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 criar o arquivo .df-credentials.json
no disco.
Para criar o arquivo de credenciais, siga estas etapas:
Execute este comando:
dataform init-creds
Siga o assistente do
init-creds
, que ensina a criar arquivos de credenciais.
Criar um projeto
Um projeto vazio do Dataform 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: é seu ID do projeto no Google Cloud.
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 dentro do 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
ouview
. - SELECT_STATEMENT: uma instrução
SELECT
que define a tabela. - FILE: o nome do arquivo de definição de tabela.
- TABLE_TYPE: o tipo 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.
- SELECT_STATEMENT: uma instrução
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 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 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 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 recriá-las do zero.
Para ver o código SQL compilado final adaptado ao estado atual do BigQuery, 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 ver 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
- Para saber mais sobre a CLI do Dataform, consulte Referência da CLI do Dataform.
- Para saber mais sobre o Dataform, consulte Visão geral do Dataform.