Usar a CLI de código aberto do Dataform

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

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

O Dataform distribui uma imagem do Docker que pode ser usada para executar o equivalente aos comandos da CLI do Dataform.

A CLI do Dataform é compatível com o Application Default Credentials (ADC). Com o ADC, é possível disponibilizar as credenciais para o aplicativo em vários ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo. Para usá-lo, primeiro forneça suas credenciais a ele.

Antes de começar

Antes de instalar a CLI do Dataform, instale o NPM (em inglês).

Instalar a CLI do Dataform

Para instalar a CLI do Dataform, execute o seguinte comando:
```
npm i -g @dataform/cli@^3.0.0-beta.2
```

Inicializar um projeto do Dataform

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

Atualizar 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 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.

Aviso:se você usar um sistema de controle de origem, não confirme o df-credentials.json. no seu repositório para proteger essas credenciais de acesso. Recomendamos que você adicione o arquivo .df-credentials.json a .gitignore.

Para criar o arquivo de credenciais, siga estas etapas:

Execute este comando:
```
dataform init-creds
```
Siga o assistente init-creds, que mostra como criar o arquivo 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 pelo nome do projeto e YOUR_GOOGLE_CLOUD_PROJECT_ID pelo ID do projeto do 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 pelo tipo da tabela: table, incremental ou view.
- SELECT_STATEMENT por uma instrução SELECT que define a tabela.
- FILE pelo 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 por uma instrução SELECT que define a declaração.
- FILE pelo nome do arquivo de definição de 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 pela operação SQL personalizada.
- FILE pelo nome do arquivo de definição de operação SQL personalizada.

Conferir a saída da compilação

O Dataform compila o código em tempo real.

Para conferir a saída do processo de compilação no terminal, execute o seguinte comando:
```
dataform compile
```
Para ver 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 pela variável de compilação personalizada.
- SAMPLE_VALUE pelo valor da sua 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 personalizar 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 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 pela variável de compilação personalizada.
- SAMPLE_VALUE pelo 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 tabelas incrementais sem recriá-las do zero.

Para ver o código SQL compilado final personalizado para o 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:
```
dataform help COMMAND
```
Substitua COMMAND pelo comando que você quer conhecer.

A seguir

Para saber mais sobre a CLI do Dataform, consulte Referência da CLI do Dataform.
Para saber mais sobre o Dataform, consulte a Visão geral do Dataform.