Informações gerais sobre o Dataform Core

Neste documento, apresentamos o Dataform Core e mostramos como usá-lo no Dataform.

Informações gerais sobre o Dataform Core

O Dataform Core é uma meta-linguagem 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.

Você pode 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 tabela e coluna no código.
  • Reutilizar funções e variáveis em consultas diferentes.
  • escrever declarações de dados para garantir a consistência dos dados;

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

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

Para usar o Dataform Core, é necessário gravar 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 principal do Dataform 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, o que significa que o mesmo código é compilado no mesmo resultado de compilação SQL todas as vezes. O Dataform compila o 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 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. Qualquer arquivo SQL simples é um arquivo SQLX válido que o Dataform executa no estado em que se encontra.

No bloco "config", é 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.

Dados do documento

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

Definir testes de qualidade de dados

Você pode definir testes de qualidade de dados, chamados de declarações, para verificar a exclusividade, os 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 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, você pode executar 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 é fundamental 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ê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 outras dependências, por exemplo, executar códigos condicionalmente usando outras funções integradas essenciais do Dataform, consulte a referência principal 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, é possível especificar operações de pré 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 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 de código SQL, use blocos JavaScript. Só é possível reutilizar o código definido em um bloco JavaScript dentro do arquivo SLQX em que o bloco está definido. Para reutilizar o código em todo o repositório, crie inclusões.

Para modificar dinamicamente uma consulta, é possível usar 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 "..."

A seguir