Usar a CLI do Dataform de código aberto

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

A CLI do Dataform é compatível com Application Default Credentials (ADC). Com o ADC, é possível disponibilizar credenciais para seu aplicativo em uma variedade de ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo. Para usar o ADC, primeiro é necessário fornecer suas credenciais ao ADC.

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
  

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 (opcional): o local em que você quer que o Dataform grave dados do BigQuery. Se não estiver definido, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

    • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
    • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
    • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

Atualizar o Dataform Core

• Para atualizar o framework principal do Dataform, atualize o dataformCoreVersion no arquivo workflow_settings.yaml e execute o NPM install novamente:

  npm i
  

Atualizar a CLI do Dataform

• Para atualizar a ferramenta de linha de comando do Dataform, execute o seguinte comando:

  npm i -g @dataform/cli@^3.0.50
  

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:

1. Execute este comando:

   dataform init-creds
   

2. Siga o assistente init-creds, que orienta você na criação do arquivo de credenciais.

Criar um projeto

Um projeto vazio do Dataform no Dataform Core 3.0.0 ou mais recente 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-database YOUR_GOOGLE_CLOUD_PROJECT_ID --default-location DEFAULT_LOCATION
  

  Substitua:

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

  • DEFAULT_LOCATION (opcional): o local em que você quer que o Dataform grave os dados do BigQuery. Se não estiver definido, o Dataform vai determinar o local com base nos conjuntos de dados referenciados pela consulta SQL. Isso funciona da seguinte maneira:

    • Se a consulta fizer referência a conjuntos de dados do mesmo local, o Dataform usará esse local.
    • Se a consulta fizer referência a conjuntos de dados de dois ou mais locais diferentes, um erro vai ocorrer. Para mais detalhes sobre essa limitação, consulte Replicação de conjuntos de dados entre regiões.
    • Se a consulta não fizer referência a nenhum conjunto de dados, o local padrão do Dataform será a multirregião US. Para escolher um local diferente, defina o local padrão. Como alternativa, use a variável de sistema @@location na sua consulta. Para mais informações, consulte Especificar locais.

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 no 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 da tabela.

O exemplo de código a seguir define uma visualização no arquivo example SQLX.

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/