Visão geral do Dataform

Este documento apresenta os conceitos e processos do Dataform.

O Dataform é um serviço para analistas de dados desenvolverem, testarem, controlarem versões e programarem fluxos de trabalho complexos para transformação de dados no BigQuery.

O Dataform permite gerenciar a transformação de dados no processo de extração, carregamento e transformação (ELT) para integração de dados. Depois que os dados brutos são extraídos dos sistemas de origem e carregados no BigQuery, o Dataform ajuda você a transformá-los em um conjunto de tabelas bem definido, testado e documentado.

O Dataform permite realizar as seguintes ações de transformação de dados:

  • Desenvolver e executar fluxos de trabalho para transformação de dados.
  • Colabore com os membros da equipe no desenvolvimento do fluxo de trabalho usando o Git.
  • Gerenciar um grande número de tabelas e dependências.
  • Declare dados de origem e gerencie dependências de tabelas.
  • Visualizar uma visualização da árvore de dependências do seu fluxo de trabalho.
  • Gerenciar dados com código SQL em um repositório central.
  • Reutilize o código com JavaScript.
  • Teste a precisão dos dados com testes de qualidade nas tabelas de origem e de saída.
  • Controle de versões do código SQL.
  • Documentar tabelas de dados no código SQL.

Processos de transformação de dados no Dataform

O fluxo de trabalho de transformação de dados do Dataform é o seguinte:

  1. O Dataform permite criar repositórios para gerenciar seu código.
  2. O Dataform permite criar espaços de trabalho para desenvolvimento.
  3. O Dataform permite desenvolver fluxos de trabalho em um espaço de trabalho de desenvolvimento.
  4. O Dataform compila o núcleo do Dataform em SQL.
  5. O Dataform executa a árvore de dependências.

O Dataform permite criar repositórios para gerenciar seu código

Em um repositório do Dataform, você usa o núcleo do Dataform, uma extensão do SQL, para gravar arquivos SQLX em que define seu fluxo de trabalho. Os repositórios do Dataform oferecem suporte ao controle de versões. É possível vincular um repositório do Dataform a um provedor Git de terceiros.

O Dataform permite criar espaços de trabalho para desenvolvimento

É possível criar espaços de trabalho de desenvolvimento em um repositório do Dataform para desenvolvimento do núcleo do Dataform. Em um espaço de trabalho de desenvolvimento, é possível fazer alterações no repositório, fazer a compilação, testar e enviar para o repositório principal usando o Git.

O Dataform permite desenvolver o núcleo do Dataform em um espaço de trabalho de desenvolvimento

Em um espaço de trabalho de desenvolvimento, é possível definir e documentar tabelas, as dependências delas e a lógica de transformação para criar seu fluxo de trabalho. Também é possível configurar ações em JavaScript.

O Dataform compila o núcleo do Dataform

Durante a compilação, o Dataform executa as seguintes tarefas:

  • Compila o núcleo do Dataform em um fluxo de trabalho do SQL padrão.
  • Adiciona instruções SQL boilerplate, como CREATE TABLE ou INSERT, ao código inline com a configuração da consulta.
  • Transpila (compila de origem para origem) JavaScript em SQL.
  • Resolve dependências e verifica erros, incluindo dependências ausentes ou circulares.
  • Cria a árvore de dependências de todas as ações a serem executadas no BigQuery.

A compilação do Dataform é hermética para garantir a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação SQL sempre. O Dataform compila seu código em um ambiente de sandbox sem acesso à Internet. Nenhuma ação adicional, como chamar APIs externas, está disponível durante a compilação.

Para depurar em tempo real, inspecione o fluxo de trabalho compilado do seu projeto em um gráfico interativo no espaço de trabalho de desenvolvimento.

O Dataform executa a árvore de dependências

No BigQuery, o Dataform realiza as seguintes tarefas:

  • Executa comandos SQL, seguindo a ordem da árvore de dependências.
  • Executa consultas de declaração nas suas tabelas e visualizações para verificar a correção dos dados.
  • Executa outras operações SQL definidas.

Após a execução, você pode usar as tabelas e visualizações para todas as finalidades de análise.

É possível acessar os registros para conferir quais tabelas foram criadas, se as declarações foram aprovadas ou reprovadas, quanto tempo cada ação levou para ser concluída e outras informações. Também é possível conferir o código SQL exato que foi executado no BigQuery.

Recursos do Dataform

Com o Dataform, é possível desenvolver e implantar tabelas, tabelas incrementais ou visualizações no BigQuery. O Dataform oferece um ambiente da Web para as seguintes atividades:

  • Desenvolvimento do fluxo de trabalho
  • Conexão com GitHub, GitLab, Azure DevOps Services e Bitbucket
  • Integração e implantação contínuas
  • Execução do fluxo de trabalho

As seções a seguir descrevem os principais recursos do Dataform.

Repositórios

Cada projeto do Dataform é armazenado em um repositório. Um repositório do Dataform armazena uma coleção de arquivos de configuração JSON, arquivos SQLX e arquivos JavaScript.

Os repositórios do Dataform contêm os seguintes tipos de arquivos:

  • Arquivos de configuração

    Os arquivos JSON ou SQLX de configuração permitem configurar seus fluxos de trabalho. Eles contêm configurações gerais, programações de execução ou esquemas para criar novas tabelas e visualizações.

  • Definições

    As definições são arquivos SQLX e JavaScript que definem novas tabelas, visualizações e outras operações SQL para execução no BigQuery.

  • Inclui

    Os includes são arquivos JavaScript em que você pode definir variáveis e funções para usar no seu projeto.

Cada repositório do Dataform está conectado a uma conta de serviço. É possível selecionar uma conta de serviço ao criar um repositório ou editar a conta de serviço mais tarde.

Por padrão, o Dataform usa uma conta de serviço derivada do número do projeto no seguinte formato:

service-YOUR_PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com

Controle de versão

O Dataform usa o sistema de controle de versões do Git para manter um registro de cada mudança feita nos arquivos do projeto e gerenciar as versões dos arquivos.

Cada repositório do Dataform pode gerenciar o próprio repositório Git ou ser conectado a um repositório Git remoto de terceiros. É possível conectar um repositório do Dataform a um repositório do GitHub, do GitLab, do Azure DevOps Services ou do Bitbucket.

Os usuários controlam as versões do código do fluxo de trabalho nos espaços de trabalho do Dataform. Em um espaço de trabalho do Dataform, é possível extrair mudanças do repositório, confirmar todas ou algumas delas e enviá-las para as ramificações do Git do repositório.

Desenvolvimento do fluxo de trabalho

No Dataform, você faz mudanças em arquivos e diretórios em um espaço de trabalho de desenvolvimento. Um espaço de trabalho de desenvolvimento é uma cópia virtual e editável do conteúdo de um repositório Git. O Dataform preserva o estado dos arquivos no seu espaço de trabalho de desenvolvimento entre as sessões.

Em um espaço de trabalho de desenvolvimento, é possível desenvolver ações de fluxo de trabalho SQL usando o núcleo do Dataform com SQLX e JavaScript ou exclusivamente com JavaScript. É possível formatar automaticamente o núcleo do Dataform ou o código JavaScript.

Cada elemento de um fluxo de trabalho do Dataform, como uma tabela ou declaração, corresponde a uma ação realizada pelo Dataform no BigQuery. Por exemplo, um arquivo de definição de tabela é uma ação de criação ou atualização da tabela no BigQuery.

Em um espaço de trabalho do Dataform, é possível desenvolver as seguintes ações de fluxo de trabalho:

É possível usar o JavaScript para reutilizar o código do fluxo de trabalho do Dataform das seguintes maneiras:

O Dataform compila o código do fluxo de trabalho no seu espaço de trabalho em tempo real. No seu espaço de trabalho, você pode conferir as consultas compiladas e os detalhes das ações em cada arquivo. Também é possível conferir o status da compilação e os erros no arquivo editado ou no repositório.

Para testar a saída de uma consulta SQL compilada antes de executá-la no BigQuery, você pode executar uma visualização da consulta no seu espaço de trabalho do Dataform.

Para inspecionar todo o fluxo de trabalho definido no seu espaço de trabalho, você pode visualizar um gráfico compilado interativo que mostra todas as ações compiladas no seu fluxo de trabalho e as relações entre elas.

Compilação do fluxo de trabalho

O Dataform usa configurações de compilação padrão, configuradas no arquivo de configurações do fluxo de trabalho, para compilar o código do fluxo de trabalho no seu espaço de trabalho para SQL em tempo real, criando um resultado de compilação do espaço de trabalho.

É possível substituir as configurações de compilação para personalizar como o Dataform compila seu fluxo de trabalho em um resultado de compilação.

Com as substituições de compilação do espaço de trabalho, é possível configurar substituições de compilação para todos os espaços de trabalho em um repositório. É possível definir substituições dinâmicas de espaços de trabalho para criar resultados de compilação personalizados para cada espaço de trabalho, transformando-os em ambientes de desenvolvimento isolados. É possível substituir o projeto Google Cloud em que o Dataform vai executar o conteúdo de um espaço de trabalho, adicionar um prefixo aos nomes de todas as tabelas compiladas e adicionar um sufixo ao esquema padrão.

Com as configurações de versão, é possível configurar modelos de configurações de compilação para criar resultados de compilação de um repositório do Dataform. Em uma configuração de lançamento, é possível substituir o projeto Google Cloud em que o Dataform vai executar os resultados da compilação, adicionar um prefixo aos nomes de todas as tabelas compiladas, adicionar um sufixo ao esquema padrão e adicionar variáveis de compilação. Também é possível definir a frequência de criação de resultados de compilação. Para programar execuções de resultados de compilação criados em uma configuração de lançamento selecionada, crie uma configuração de fluxo de trabalho.

Execução do fluxo de trabalho

Durante a execução do fluxo de trabalho, o Dataform executa os resultados de compilação de fluxos de trabalho para criar ou atualizar recursos no BigQuery.

Para criar ou atualizar as tabelas e visualizações definidas no seu fluxo de trabalho no BigQuery, você pode iniciar uma execução de fluxo de trabalho manualmente em um espaço de trabalho de desenvolvimento ou programar execuções.

É possível programar execuções do Dataform no BigQuery das seguintes maneiras:

Para depurar erros, monitore as execuções das seguintes maneiras:

Núcleo do Dataform

O núcleo do Dataform é uma metalinguagem de código aberto para criar tabelas e fluxos de trabalho SQL. O núcleo do Dataform estende o SQL fornecendo um sistema de gerenciamento de dependências, testes automatizados de qualidade de dados e documentação de dados.

É possível usar o núcleo do Dataform para os seguintes propósitos:

  • Como definir tabelas, visualizações, visualizações materializadas ou tabelas incrementais
  • Definir a lógica de transformação de dados
  • Como declarar dados de origem e gerenciar dependências de tabelas
  • Documentar descrições de tabelas e colunas no código
  • Reutilizar funções e variáveis em diferentes consultas
  • Como gravar declarações de dados para garantir a consistência dos dados

No Dataform, você usa o núcleo do Dataform para desenvolver fluxos de trabalho e implantar recursos no BigQuery.

O núcleo do Dataform faz parte do framework de modelagem de dados do Dataform de código aberto, que também inclui a CLI do Dataform. É possível compilar e executar o núcleo do Dataform localmente usando o CLI do Dataform fora de Google Cloud.

Para usar o núcleo do Dataform, você grava arquivos SQLX. Cada arquivo SQLX contém uma consulta que define uma relação de banco de dados que o Dataform cria e atualiza no BigQuery.

O Dataform compila seu código principal em tempo real para criar um resultado de compilação SQL que pode ser executado no BigQuery.

A compilação do Dataform é hermética para garantir a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação SQL sempre. O Dataform compila seu código em um ambiente de sandbox sem acesso à Internet. Nenhuma outra ação, como chamar APIs externas, está disponível durante a compilação.

Bloco de configuração do arquivo SQLX

Um arquivo SQLX consiste em um bloco de configuração e um corpo. Todas as propriedades de configuração e o próprio bloco de configuração são opcionais. Portanto, qualquer arquivo SQL simples é um arquivo SQLX válido que o Dataform executa como está.

No bloco de configuração, é possível realizar as seguintes ações:

Especificar metadados da consulta

É possível configurar como o Dataform materializa consultas no BigQuery, por exemplo, o tipo de tabela de saída, o banco de dados de destino ou os rótulos usando os metadados de configuração.

Documentar dados

É possível documentar suas tabelas e os campos delas diretamente no bloco de configuração. A documentação das suas tabelas é enviada diretamente para o BigQuery. É possível analisar essa documentação e enviá-la para outras ferramentas.

Definir testes de qualidade de dados

É possível definir testes de qualidade de dados, chamados de asserções, para verificar singularidade, valores nulos ou uma condição personalizada. O Dataform adiciona as declarações definidas no bloco de configuração à árvore de dependências do fluxo de trabalho após a criação da tabela. Também é possível definir declarações fora do bloco de configuração, em um arquivo SQLX separado.

O exemplo de código abaixo mostra como definir o tipo de tabela de saída, documentar a tabela e definir um teste de qualidade em um bloco de configuração de um arquivo SQLX.

config {
  type: "table",
    description: "This table joins orders information from OnlineStore & payment information from PaymentApp",
  columns: {
    order_date: "The date when a customer placed their order",
    id: "Order ID as defined by OnlineStore",
    order_status: "The status of an order e.g. sent, delivered",
    customer_id: "Unique customer ID",
    payment_status: "The status of a payment e.g. pending, paid",
    payment_method: "How the customer chose to pay",
    item_count: "The number of items the customer ordered",
    amount: "The amount the customer paid"
  },
    assertions: {
    uniqueKey: ["id"]
  }
}

Corpo do arquivo SQLX

No corpo de um arquivo SQLX, é possível realizar as seguintes ações:

Definir uma tabela

Para definir uma nova tabela, use instruções SELECT SQL e a função ref.

A função ref é uma função integrada do SQLX que é essencial para o gerenciamento de dependências no Dataform. A função ref permite referenciar tabelas definidas no projeto do Dataform em vez de codificar o esquema e os nomes da tabela de dados.

O Dataform usa a função ref para criar uma árvore de dependência de todas as tabelas a serem criadas ou atualizadas. Após a compilação, o Dataform adiciona declarações de modelo, como CREATE, REPLACE ou INSERT.

O exemplo de código abaixo mostra como fazer referência a uma tabela em um arquivo SQLX com a função ref.

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2, 3

O resultado será assim:

CREATE OR REPLACE TABLE Dataform.orders AS

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM Dataform_stg.store_clean

GROUP BY 1, 2, 3

Para mais informações sobre o gerenciamento de dependências, por exemplo, executando código condicionalmente usando outras funções integradas do núcleo do Dataform, consulte a referência do núcleo do Dataform.

Definir outras operações SQL

Para configurar o Dataform para executar uma ou mais instruções SQL antes ou depois de criar uma tabela ou visualização, especifique as operações antes e depois da consulta.

O exemplo de código abaixo mostra como configurar as permissões de acesso a tabelas ou visualizações em uma operação pós-consulta.

SELECT * FROM ...

post_operations {
  GRANT `roles/bigquery.dataViewer` ON TABLE ${self()} TO "group:someusers@dataform.co"
}

Encapsular código SQL

Para definir funções reutilizáveis e gerar partes repetitivas do código SQL, use blocos JavaScript. É possível reutilizar o código definido em um bloco JavaScript apenas dentro do arquivo SLQX em que o bloco é definido. Para reutilizar o código em todo o repositório, você pode criar inclusões.

Para modificar dinamicamente uma consulta, use o JavaScript inline em qualquer lugar do corpo.

O exemplo de código abaixo mostra como definir um bloco JavaScript em um arquivo SQLX e usá-lo inline em uma consulta:

js {
  const columnName = "foo";
}

SELECT 1 AS ${columnName} FROM "..."

Limitações

O Dataform tem as seguintes limitações conhecidas:

  • O Dataform em Google Cloud é executado em um ambiente de execução V8 simples e não oferece suporte a outros recursos e módulos fornecidos pelo Node.js. Se a base de código atual exigir módulos Node.js, você precisará remover essas dependências.

    Os projetos sem um campo de nome em package.json geram diferenças em package-lock.json sempre que os pacotes são instalados. Para evitar esse resultado, é necessário adicionar uma propriedade name em package.json.

  • Não há suporte para URLs git+https:// para dependências em package.json.

    Converta esses URLs em URLs de arquivo https:// simples. Por exemplo, converta git+https://github.com/dataform-co/dataform-segment.git#1.5 em https://github.com/dataform-co/dataform-segment/archive/1.5.tar.gz.

  • A execução manual de testes de unidade não está disponível.

  • A pesquisa de conteúdo de arquivos nos espaços de trabalho de desenvolvimento não está disponível.

  • A partir do núcleo do Dataform 3.0.0., o Dataform não distribui uma imagem do Docker. Você pode criar sua própria imagem Docker do Dataform, que pode ser usada para executar o equivalente aos comandos da CLI do Dataform. Para criar sua própria imagem do Docker, consulte Colocar um aplicativo em contêiner na documentação do Docker.

  • Os métodos da API Dataform a seguir não estão em conformidade com as diretrizes AIP.134 tratando a entrada de caractere curinga * como uma solicitação inválida e atualiza todos os campos em vez de definir campos quando field_mask é omitido:

A seguir