Usar a CLI de código aberto do Dataform

Neste documento, mostramos como usar a interface de linha de comando (CLI) do Dataform de código aberto 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, para implantar recursos nos seguintes data warehouses:

BigQuery
Snowflake
Redshift
Azure SQL Data Warehouse
Postgres

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

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@^2.3.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, execute o seguinte comando no diretório do projeto que contém o arquivo dataform.json:
```
npm i @dataform/core@^2.3.2
```

Atualizar a CLI do Dataform

Para atualizar a ferramenta da CLI do Dataform, execute o seguinte comando:
```
npm i -g @dataform/cli@^2.3.2
```

Criar um arquivo de credenciais

O Dataform exige um arquivo de credenciais para se conectar ao seu warehouse 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 WAREHOUSE
```
Substitua WAREHOUSE pelo seu warehouse: bigquery, postgres, redshift, snowflake ou sqldatawarehouse.
Siga o assistente init-creds para instruções sobre a criação do arquivo de credenciais.

Crie um projeto

Um projeto vazio do Dataform tem a seguinte estrutura:

   project-dir
   ├── definitions
   ├── includes
   ├── package.json
   └── dataform.json

Para criar um projeto do Dataform e implantar recursos no BigQuery, execute o seguinte comando:
```
dataform init bigquery PROJECT_NAME --default-database 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.
Para criar um projeto do Dataform e implantar recursos no Postgres, Redshift, Snowflake ou Azure SQL Data Warehouse, execute o seguinte comando:
```
dataform init WAREHOUSE PROJECT_NAME
```
Substitua PROJECT_NAME pelo nome do projeto e WAREHOUSE pelo warehouse: postgres, redshift, snowflake ou sqldatawarehouse.

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 com 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 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 pela operação SQL personalizada.
- FILE pelo nome do arquivo de definição da operação SQL personalizada.

Ver a 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 visualizar a saída do processo de compilação como um objeto JSON, execute o comando abaixo:
```
dataform compile --json
```
Para ver 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 variável de compilação personalizada.

Executar código

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

Para executar o código do projeto do Dataform no seu data warehouse, execute o seguinte comando:
```
dataform run
```
Para executar o código do projeto do Dataform no seu data warehouse 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 variável de compilação personalizada.
Para executar o código do projeto do Dataform no data warehouse 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 seu warehouse, sem executá-lo dentro do warehouse, execute o seguinte comando:
```
dataform run --dry-run
```

Receba ajuda

Para listar todos os comandos e opções disponíveis, execute o seguinte:
```
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 a Referência da CLI do Dataform
Para saber mais sobre o Dataform, consulte Visão geral do Dataform.