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.
  • Colaborar com membros da equipe no desenvolvimento do fluxo de trabalho usando o Git.
  • Gerenciar um grande número de tabelas e dependências.
  • Declarar dados de origem e gerenciar dependências de tabelas.
  • Conferir uma visualização da árvore de dependências do fluxo de trabalho.
  • Gerenciar dados com código SQL em um repositório central.
  • Reutilizar código com JavaScript.
  • Testar a correção dos dados com testes de qualidade nas tabelas de origem e de saída.
  • Controlar a versão do código SQL.
  • Documentar tabelas de dados dentro do 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 Dataform Core 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 Dataform Core, uma extensão do SQL, para gravar arquivos SQLX em que define o fluxo de trabalho. Os repositórios do Dataform aceitam 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 dentro de um repositório do Dataform para o desenvolvimento do Dataform Core. Em um espaço de trabalho de desenvolvimento, é possível fazer mudanças no repositório, compilar, testar e enviar para o repositório principal usando o Git.

O Dataform permite desenvolver o Dataform Core em um espaço de trabalho de desenvolvimento

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

O Dataform compila o Dataform Core

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

  • Compila o Dataform Core 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 de 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 verificar a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação SQL todas as vezes. 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 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 tabelas e visualizações para verificar a correção dos dados.
  • Executa outras operações SQL definidas.
  • Atualiza os metadados no Knowledge Catalog (visualização).

Após a execução, é possível usar as tabelas e visualizações para todas as finalidades de análise.

É possível conferir os registros para saber 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 de 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 contém 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 de configuração JSON ou SQLX permitem configurar os fluxos de trabalho. Eles contêm configuração geral, programações de execução ou esquema 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 a serem executadas no BigQuery.

  • Inclui

    As inclusões são arquivos JavaScript em que é possível definir variáveis e funções para usar no projeto.

Cada repositório do Dataform precisa estar conectado a uma conta de serviço personalizada. Você seleciona uma conta de serviço personalizada ao criar um repositório. É possível editar a conta de serviço mais tarde.

Controle de versão

O Dataform usa o sistema de controle de versões Git para manter um registro de cada mudança feita nos arquivos do projeto e para gerenciar versões de 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, GitLab, Azure DevOps Services ou Bitbucket.

Os usuários controlam a versão 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 mudanças e enviá-las para ramificações Git do repositório.

Desenvolvimento de fluxo de trabalho

No Dataform, você faz mudanças em arquivos e diretórios dentro de 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 usando o Dataform Core com SQLX e JavaScript ou apenas com JavaScript. É possível formatar automaticamente o código do Dataform Core ou JavaScript.

Cada elemento de um fluxo de trabalho do Dataform, como uma tabela ou declaração, corresponde a uma ação que o Dataform realiza 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 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 espaço de trabalho em tempo real. No espaço de trabalho, é possível 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 a visualização da consulta no espaço de trabalho do Dataform.

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

Compilação do fluxo de trabalho

O Dataform usa as 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 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 o 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 do espaço de trabalho para criar resultados de compilação personalizados para cada espaço de trabalho, transformando espaços de trabalho em ambientes de desenvolvimento isolados. É possível substituir o Google Cloud projeto em que o Dataform executa 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 versão, é possível substituir o Google Cloud projeto em que o Dataform executa 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 versão selecionada, você pode criar uma configuração de fluxo de trabalho.

Execução do fluxo de trabalho

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

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

Quando você aciona uma execução do fluxo de trabalho, o Dataform executa as ações na ordem definida pelas dependências. Para cada ação, o Dataform realiza as seguintes etapas:

  1. Executa o SQL compilado no BigQuery.
  2. Atualiza o status da ação no registro de execução.
  3. Após a conclusão de uma ação, o Dataform inicia automaticamente uma sincronização de metadados com o Knowledge Catalog (visualização). Esse processo de enriquecimento atualiza o Knowledge Catalog com os metadados semânticos definidos na configuração SQLX. A sincronização acontece de forma assíncrona e usa um mecanismo de repetição, garantindo que as atualizações de metadados não afetem a latência do pipeline nem causem falhas no fluxo de trabalho se a API Dataplex estiver temporariamente indisponível.

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

Também é possível automatizar execuções com gatilhos do Cloud Build.

Para depurar erros, é possível monitorar execuções das seguintes maneiras:

Dataform Core

O Dataform Core é uma metalinguagem de código aberto para criar tabelas e fluxos de trabalho SQL. O Dataform Core 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 Dataform Core para as seguintes finalidades:

  • Definir tabelas, visualizações, visualizações materializadas ou tabelas incrementais.
  • Definir a lógica de transformação de dados.
  • Declarar dados de origem e gerenciar dependências de tabelas.
  • Documentar descrições de tabelas e colunas dentro do código.
  • Reutilizar funções e variáveis em diferentes consultas.
  • Gravar declarações de dados para verificar a consistência dos dados.

No Dataform, você usa o Dataform Core para desenvolver fluxos de trabalho e implantar recursos no BigQuery.

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

Para usar o Dataform Core, grave 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 o código do Dataform Core 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 verificar a consistência da compilação, o que significa que o mesmo código é compilado para o mesmo resultado de compilação SQL todas as vezes. 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.

Bloco de configuração de 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 de 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 as tabelas e os campos diretamente no bloco de configuração. A documentação das tabelas é enviada diretamente para o BigQuery e o Knowledge Catalog (visualização). É possível analisar essa documentação e enviá-la para outras ferramentas.

O exemplo de código a seguir mostra como definir o tipo de tabela de saída, documentar a tabela e adicionar metadados para o Knowledge Catalog 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, for example, sent, delivered",
    customer_id: "Unique customer ID",
    payment_status: "The status of a payment, for example, 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"
  },
  metadata: {
    overview: "This table provides joined orders and payment data.",
    extraProperties: {
      generic: {
        system: "BigQuery",
        type: "table"
      }
    }
  }
}

Definir testes de qualidade de dados

É possível definir testes de qualidade de dados, chamados de declarações, para verificar a exclusividade, valores nulos ou uma condição personalizada. O Dataform adiciona 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 a seguir mostra como definir um teste de qualidade em um bloco de configuração de um arquivo SQLX:

config {
  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 SQL SELECT 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 das tabelas de dados.

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

O exemplo de código a seguir mostra como referenciar 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 adicionais, por exemplo, a execução condicional de código, o uso de outras funções integradas do Dataform Core, consulte a referência do Dataform Core.

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, você pode especificar operações de pré-consulta e pós-consulta.

O exemplo de código a seguir mostra como configurar permissões de acesso a tabelas ou visualizações em uma operação de 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 para 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 SQLX em que o bloco está definido. Para reutilizar o código em todo o repositório, você pode criar inclusões.

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

O exemplo de código a seguir 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 é executado em um ambiente de execução V8 simples e não oferece suporte a outros recursos e módulos fornecidos pelo Node.js. Google Cloud Se a base de código atual exigir módulos Node.js, remova essas dependências.

    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, adicione uma propriedade name em package.json.

  • Os URLs git+https:// para dependências em package.json não são aceitos.

    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.

  • Não é possível executar testes de unidade manualmente.

  • Não é possível pesquisar o conteúdo do arquivo em espaços de trabalho de desenvolvimento.

  • A partir do Dataform Core 3.0.0., o Dataform não distribui uma imagem Docker. É possível criar sua própria imagem do 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 Como containerizar um aplicativo na documentação do Docker.

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

  • Se uma execução de configuração de fluxo de trabalho programada não terminar antes do início da próxima execução programada, a próxima execução programada será ignorada e marcada com um erro.

A seguir