Vista geral do Dataform

Este documento apresenta os conceitos e os processos do Dataform.

O Dataform é um serviço que permite aos analistas de dados desenvolver, testar, controlar versões e agendar fluxos de trabalho complexos para a transformação de dados no BigQuery.

O Dataform permite-lhe gerir a transformação de dados no processo de extração, carregamento e transformação (ELT) para a integração de dados. Depois de os dados não processados serem extraídos dos sistemas de origem e carregados no BigQuery, o Dataform ajuda a transformá-los num conjunto de tabelas de dados bem definido, testado e documentado.

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

  • Desenvolver e executar fluxos de trabalho para a transformação de dados.
  • Colabore com os membros da equipa no desenvolvimento de fluxos de trabalho através do Git.
  • Gerir um grande número de tabelas e respetivas dependências.
  • Declare dados de origem e faça a gestão das dependências das tabelas.
  • Veja uma visualização da árvore de dependências do seu fluxo de trabalho.
  • Faça a gestão de dados com código SQL num repositório central.
  • Reutilize código com JavaScript.
  • Teste a correção dos dados com testes de qualidade nas tabelas de origem e de saída.
  • Controlar as versões do código SQL.
  • Documente tabelas de dados no código SQL.

Processos de transformação de dados no Dataform

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

  1. O Dataform permite-lhe criar repositórios para gerir o seu código.
  2. O Dataform permite-lhe criar espaços de trabalho para desenvolvimento.
  3. O Dataform permite-lhe desenvolver fluxos de trabalho num 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-lhe criar repositórios para gerir o seu código

Num repositório do Dataform, usa o Dataform core, uma extensão do SQL, para escrever ficheiros SQLX nos quais define o seu fluxo de trabalho. Os repositórios do Dataform são compatíveis com o controlo de versões. Pode associar um repositório do Dataform a um fornecedor Git de terceiros.

O Dataform permite-lhe criar espaços de trabalho para desenvolvimento

Pode criar espaços de trabalho de desenvolvimento num repositório do Dataform para o desenvolvimento principal do Dataform. Num espaço de trabalho de desenvolvimento, pode fazer alterações ao repositório, compilar, testar e enviá-las para o repositório principal através do Git.

O Dataform permite-lhe desenvolver o Dataform core num espaço de trabalho de desenvolvimento

Num espaço de trabalho de desenvolvimento, pode definir e documentar tabelas, as respetivas dependências e a lógica de transformação para criar o seu fluxo de trabalho. Também pode 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 num fluxo de trabalho de SQL padrão.
  • Adiciona declarações SQL padrão, como CREATE TABLE ou INSERT, ao código incorporado na configuração da consulta.
  • Transpila (compila de origem para origem) JavaScript em SQL.
  • Resolve as dependências e verifica a existência de erros, incluindo dependências em falta 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 sempre. O Dataform compila o seu código num ambiente de sandbox sem acesso à Internet. Não estão disponíveis ações adicionais, como chamar APIs externas, durante a compilação.

Para depurar em tempo real, pode inspecionar o fluxo de trabalho compilado do seu projeto num gráfico interativo no seu 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 asserção nas suas tabelas e vistas para verificar a correção dos dados.
  • Executa outras operações SQL que definiu.

Após a execução, pode usar as tabelas e as visualizações de propriedade para todos os fins de análise.

Pode ver registos para ver que tabelas foram criadas, se as afirmações passaram ou falharam, quanto tempo demorou cada ação a ser concluída e outras informações. Também pode ver o código SQL exato que foi executado no BigQuery.

Funcionalidades do Dataform

Com o Dataform, pode desenvolver e implementar tabelas, tabelas incrementais ou vistas no BigQuery. O Dataform oferece um ambiente Web para as seguintes atividades:

  • Desenvolvimento de fluxos de trabalho
  • Ligação ao GitHub, GitLab, Azure DevOps Services e Bitbucket
  • Integração contínua e implementação contínua
  • Execução do fluxo de trabalho

As secções seguintes descrevem as principais funcionalidades do Dataform.

Repositórios

Cada projeto do Dataform é armazenado num repositório. Um repositório do Dataform aloja uma coleção de ficheiros de configuração JSON, ficheiros SQLX e ficheiros JavaScript.

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

  • Ficheiros de configuração

    Os ficheiros JSON ou SQLX de configuração permitem-lhe configurar os seus fluxos de trabalho. Contêm a configuração geral, os agendamentos de execução ou o esquema para criar novas tabelas e vistas.

  • Definições

    As definições são ficheiros SQLX e JavaScript que definem novas tabelas, vistas e operações SQL adicionais a executar no BigQuery.

  • Inclui

    Os ficheiros incluídos são ficheiros JavaScript onde pode definir variáveis e funções para usar no seu projeto.

Cada repositório do Dataform está ligado a uma conta de serviço. Pode selecionar uma conta de serviço quando criar um repositório ou editar a conta de serviço mais tarde.

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

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

Controlo de versões

O Dataform usa o sistema de controlo de versões Git para manter um registo de cada alteração feita aos ficheiros do projeto e para gerir as versões dos ficheiros.

Cada repositório do Dataform pode gerir o seu próprio repositório Git ou estar ligado a um repositório Git remoto de terceiros. Pode associar um repositório do Dataform a um repositório do GitHub, GitLab, Azure DevOps Services ou Bitbucket.

Os utilizadores controlam as versões do código do fluxo de trabalho nos espaços de trabalho do Dataform. Num espaço de trabalho do Dataform, pode obter alterações do repositório, confirmar todas as alterações ou as selecionadas e enviá-las para ramos do Git do repositório.

Desenvolvimento de fluxos de trabalho

No Dataform, faz alterações a ficheiros e diretórios num 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 ficheiros no seu espaço de trabalho de desenvolvimento entre sessões.

Num espaço de trabalho de desenvolvimento, pode desenvolver ações de fluxo de trabalho usando o Dataform core com SQLX e JavaScript, ou exclusivamente com JavaScript. Pode formatar automaticamente o código JavaScript ou o Dataform core.

Cada elemento de um fluxo de trabalho do Dataform, como uma tabela ou uma afirmação, corresponde a uma ação que o Dataform realiza no BigQuery. Por exemplo, um ficheiro de definição de tabela é uma ação de criação ou atualização da tabela no BigQuery.

Num espaço de trabalho do Dataform, pode desenvolver as seguintes ações do fluxo de trabalho:

Pode usar JavaScript para reutilizar o código do fluxo de trabalho do Dataform das seguintes formas:

O Dataform compila o código do fluxo de trabalho no seu espaço de trabalho em tempo real. No espaço de trabalho, pode ver as consultas compiladas e os detalhes das ações em cada ficheiro. Também pode ver o estado de compilação e os erros no ficheiro editado ou no repositório.

Para testar o resultado de uma consulta SQL compilada antes de a executar no BigQuery, pode executar uma pré-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, pode ver 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 as predefinições de compilação, configuradas no ficheiro de definiçõ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.

Pode substituir as definições de compilação para personalizar a forma como o Dataform compila o seu fluxo de trabalho num resultado de compilação.

Com as substituições de compilação do espaço de trabalho, pode configurar substituições de compilação para todos os espaços de trabalho num repositório. Pode definir substituições dinâmicas do espaço de trabalho para criar resultados de compilação personalizados para cada espaço de trabalho, transformando os espaços de trabalho em ambientes de desenvolvimento isolados. Pode substituir o Google Cloud projeto no qual 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 predefinido.

Com as configurações de lançamento, pode configurar modelos de definições de compilação para criar resultados de compilação de um repositório do Dataform. Numa configuração de lançamento, pode substituir o Google Cloud projeto no qual o Dataform executa os resultados da compilação, adicionar um prefixo aos nomes de todas as tabelas compiladas, adicionar um sufixo ao esquema predefinido e adicionar variáveis de compilação. Também pode definir a frequência de criação de resultados de compilação. Para agendar execuções de resultados de compilação criados numa configuração de lançamento selecionada, pode criar uma configuração de fluxo de trabalho.

Execução do fluxo de trabalho

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

Para criar ou atualizar as tabelas e as vistas definidas no seu fluxo de trabalho no BigQuery, pode iniciar uma execução do fluxo de trabalho manualmente num espaço de trabalho de desenvolvimento ou agendar execuções.

Pode agendar execuções do Dataform no BigQuery das seguintes formas:

Para depurar erros, pode monitorizar as execuções das seguintes formas:

Dataform core

O Dataform core é uma metalinguagem de código aberto para criar tabelas SQL e fluxos de trabalho. O Dataform Core expande o SQL fornecendo um sistema de gestão de dependências, testes de qualidade de dados automatizados e documentação de dados.

Pode usar o Dataform core para os seguintes fins:

  • Definir tabelas, vistas, vistas materializadas ou tabelas incrementais.
  • Definir a lógica de transformação de dados.
  • Declarar dados de origem e gerir dependências de tabelas.
  • Documentar descrições de tabelas e colunas no código.
  • Reutilizar funções e variáveis em diferentes consultas.
  • Escrever afirmações de dados para validar a consistência dos dados.

No Dataform, usa o Dataform core para desenvolver fluxos de trabalho e implementar recursos no BigQuery.

O Dataform core faz parte da estrutura de modelagem de dados do Dataform de código aberto que também inclui a CLI do Dataform. Pode compilar e executar o Dataform core localmente através da CLI do Dataform fora do Google Cloud.

Para usar o Dataform core, escreve ficheiros SQLX. Cada ficheiro SQLX contém uma consulta que define uma relação de base de dados que o Dataform cria e atualiza no BigQuery.

O Dataform compila o seu código principal do Dataform em tempo real para criar um resultado de compilação SQL que pode executar 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 sempre. O Dataform compila o seu código num ambiente de sandbox sem acesso à Internet. Não estão disponíveis ações adicionais, como chamar APIs externas, durante a compilação.

Bloco de configuração do ficheiro SQLX

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

No bloco de configuração, pode realizar as seguintes ações:

Especifique os metadados da consulta

Pode configurar a forma como o Dataform materializa as consultas no BigQuery, por exemplo, o tipo de tabela de saída, a base de dados de destino ou as etiquetas, através dos metadados de configuração.

Dados do documento

Pode documentar as tabelas e os respetivos campos diretamente no bloco de configuração. A documentação das suas tabelas é enviada diretamente para o BigQuery. Pode analisar esta documentação e enviá-la para outras ferramentas.

Defina testes de qualidade de dados

Pode definir testes de qualidade de dados, denominados afirmações, para verificar a unicidade, os valores nulos ou uma condição personalizada. O Dataform adiciona asserções definidas no bloco de configuração à árvore de dependências do fluxo de trabalho após a criação da tabela. Também pode definir asserções fora do bloco de configuração, num ficheiro SQLX separado.

O exemplo de código seguinte mostra como definir o tipo de tabela de saída, documentar a tabela e definir um teste de qualidade num bloco de configuração de um ficheiro 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 ficheiro SQLX

No corpo de um ficheiro SQLX, pode realizar as seguintes ações:

Defina uma tabela

Para definir uma nova tabela, pode usar declarações SQL SELECT e a função ref.

A função ref é uma função incorporada do SQLX essencial para a gestão de dependências no Dataform. A função ref permite-lhe fazer referência a tabelas definidas no seu projeto do Dataform em vez de codificar os nomes do esquema e da tabela da sua tabela 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 declarações padrão, como CREATE, REPLACE ou INSERT.

O exemplo de código seguinte mostra como referenciar uma tabela num ficheiro 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 é semelhante ao seguinte:

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 a gestão de dependências adicionais, por exemplo, a execução de código condicionalmente, a utilização de outras funções incorporadas do Dataform core, consulte a referência do Dataform core.

Defina operações SQL adicionais

Para configurar o Dataform para executar uma ou mais declarações SQL antes ou depois de criar uma tabela ou uma vista, pode especificar operações de pré-consulta e pós-consulta.

O seguinte exemplo de código mostra como configurar autorizações de acesso a tabelas ou visualizações numa operação pós-consulta.

SELECT * FROM ...

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

Encapsule código SQL

Para definir funções reutilizáveis para gerar partes repetitivas do código SQL, pode usar blocos JavaScript. Só pode reutilizar código definido num bloco de JavaScript no ficheiro SLQX onde o bloco está definido. Para reutilizar código em todo o seu repositório, pode criar inclusões.

Para modificar dinamicamente uma consulta, pode usar JavaScript inline em qualquer parte do corpo.

O exemplo de código seguinte mostra como definir um bloco JavaScript num ficheiro SQLX e usá-lo inline numa consulta:

js {
  const columnName = "foo";
}

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

Limitações

O Dataform tem as seguintes limitações conhecidas:

  • O Dataform é executado num tempo de execução V8 simples e não suporta capacidades e módulos adicionais fornecidos pelo Node.js. Google Cloud Se a sua base de código existente exigir módulos Node.js, tem de remover estas 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 este resultado, tem de adicionar uma propriedade do name no package.json.

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

    Converta esses URLs em URLs de arquivo simples https://. 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 unitários não está disponível.

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

  • A partir do Dataform core 3.0.0., o Dataform não distribui uma imagem Docker. Pode criar a sua própria imagem do Docker do Dataform, que pode usar para executar o equivalente aos comandos da CLI do Dataform. Para criar a sua própria imagem do Docker, consulte o artigo Transforme uma aplicação em contentor na documentação do Docker.

  • Os seguintes métodos da API Dataform não estão em conformidade com as diretrizes AIP.134 ao tratar a entrada com carateres universais * como um pedido inválido e ao atualizar todos os campos em vez dos campos definidos quando field_mask é omitido:

O que se segue?