Criar uma tabela

Este documento mostra como definir tabelas com o núcleo do Dataform no Dataform.

Sobre as definições de tabela

Para definir uma tabela, você define o tipo de tabela e escreve uma instrução SELECT em um arquivo SQLX type: "table". Em seguida, o Dataform compila o código principal do Dataform em SQL, executa o código SQL e cria as tabelas definidas no BigQuery.

Em uma instrução SELECT principal do Dataform, você define a estrutura da tabela e faz referência a outros objetos do fluxo de trabalho SQL.

Além de definir tabelas em um arquivo SLQX type: "table", você pode criar tabelas vazias definindo uma consulta SQL personalizada em um arquivo SQLX type: "operations". Para mais informações, consulte Criar uma tabela vazia.

Referências a dependências com ref

Para fazer referência a um objeto de fluxo de trabalho SQL em uma instrução SELECT e adicioná-lo automaticamente como uma dependência, use a função ref. O Dataform executa dependências antes das tabelas que dependem delas para garantir o correto ordenação do pipeline.

A função ref é uma função integrada do núcleo do Dataform que é essencial para o gerenciamento de dependências no Dataform. A função ref permite referenciar e depender automaticamente dos seguintes objetos definidos no fluxo de trabalho do Dataform SQL em vez de codificar os nomes do esquema e da tabela:

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 instruções padrão como CREATE, REPLACE, INSERT ou MERGE à instrução SQL.

O exemplo de código abaixo mostra uma definição de tabela com o uso da 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

Na função ref, você fornece o nome da declaração de tabela ou fonte de dados da qual você quer depender. Geralmente, é o nome do arquivo SQLX em que a declaração da tabela ou da fonte de dados é definida.

Se o nome de uma tabela for substituído, use o nome substituído na função ref. Por exemplo, faça referência a uma tabela com config { name: "overridden_name" } como ref("overridden_name"). Para mais informações sobre como substituir nomes de tabelas, consulte Configurar outras configurações de tabela.

Quando você tem várias tabelas com o mesmo nome em esquemas diferentes, é possível fazer referência a uma tabela específica fornecendo dois argumentos para a função ref: nome do esquema e nome da tabela.

O exemplo de código a seguir mostra a função ref com dois argumentos para especificar uma tabela em um esquema específico:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

Também é possível adicionar dependências de tabela manualmente ao bloco config para tabelas, asserções, declarações de fonte de dados ou operações SQL personalizadas que não são referenciadas em uma função ref na instrução SELECT. O Dataform executa essas dependências antes das tabelas dependentes.

O exemplo de código abaixo mostra uma dependência de tabela no bloco config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Para mais informações sobre o gerenciamento de dependências no fluxo de trabalho SQL, consulte Declarar dependências.

Fazer referência a outras tabelas com resolve

A função resolve permite referenciar uma declaração de tabela ou fonte de dados em uma instrução SELECT, como a função ref, mas não adiciona a referência como uma dependência. Isso significa que o objeto referenciado usando resolve não afeta a execução da tabela que usa resolve.

Para mais informações sobre as funções principais integradas do Dataform, consulte a referência principal do Dataform.

Antes de começar

  1. Crie e inicialize um espaço de trabalho de desenvolvimento no seu repositório.
  2. Opcional: declare uma fonte de dados.

Funções exigidas

Para receber as permissões necessárias para definir uma tabela, peça ao administrador que conceda a você o papel do IAM Editor de formulário de dados (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

criar um arquivo SQLX para definição de tabela

Armazene arquivos SQLX de definição de tabela no diretório definitions/. Para criar um novo arquivo SQLX no diretório definitions/, siga estas etapas:

  1. No Console do Cloud, acesse a página Dataform.

    Acesse a página do Dataform

  2. Para abrir um repositório, clique no nome dele.

  3. Para abrir um espaço de trabalho de desenvolvimento, clique no nome dele.

  4. No painel Arquivos, ao lado de definitions/, clique no menu Mais.

  5. Selecione Criar arquivo.

  6. No campo Adicionar um caminho de arquivo, digite o nome do arquivo seguido por .sqlx após definitions/. Por exemplo, definitions/my-table.sqlx.

    Os nomes de arquivo só podem incluir números, letras, hifens e sublinhados.

  7. Selecione Criar arquivo.

Definir o tipo de tabela

Para criar uma nova definição de tipo de tabela, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Files, abra o diretório definitions/.
  2. Selecione o arquivo SQLX de definição de tabela que você quer editar.

  3. No arquivo, digite este snippet de código:

    config { type: "TABLE_TYPE" }

    Substitua TABLE_TYPE por um dos seguintes tipos de tabela:

    • table
    • incremental
    • view

  4. Opcional: para definir uma visualização materializada, insira a propriedade materialized em type: "view" no seguinte formato:

    config {
  type: "view",
  materialized: true
}

    Para mais informações, consulte a referência de núcleo do Dataform ITableConfig.

  5. Opcional: clique em Formato.

Definir a estrutura e as dependências da tabela

Para escrever uma instrução SELECT de definição de tabela e definir a estrutura e as dependências da tabela, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Files, abra o diretório definitions/.
  2. Selecione o arquivo SQLX de definição de tabela que você quer editar.
  3. Abaixo do bloco config, escreva uma instrução SELECT.
  4. Opcional: clique em Formato.

O exemplo de código abaixo mostra uma definição de tabela com uma instrução SELECT e a função ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Adicionar dependências de tabelas manuais

Para adicionar dependências de tabela que não são referenciadas na instrução SELECT, mas precisam ser executadas antes da tabela atual, siga estas etapas:

  1. No espaço de trabalho de desenvolvimento, no painel Files, abra o diretório definitions/.
  2. Selecione o arquivo SQLX de definição de tabela que você quer editar.

  3. No bloco config da tabela, insira o seguinte snippet de código:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Substitua DEPENDENCY_TABLE pelo nome do arquivo da tabela que você quer adicionar como uma dependência. É possível inserir vários nomes de arquivo.

  4. Opcional: clique em Formato.

O exemplo de código a seguir mostra duas tabelas adicionadas como dependências manuais de tabela ao bloco config de um arquivo de definição de tabela:

config { dependencies: [ "some_table", "some_other_table" ] }

A seguir