Criar uma tabela

Neste documento, mostramos como definir tabelas com o núcleo do Dataform no Dataform.

Sobre as definições de tabela

Para definir uma tabela, defina o tipo dela e grave 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", é possível criar tabelas vazias definindo uma consulta SQL personalizada em um arquivo SQLX type: "operations". Para saber mais, consulte Criar uma tabela vazia.

Dependências de referência 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 a ordem correta do pipeline.

A função ref é uma função integrada fundamental do Dataform fundamental para o gerenciamento de dependências no Dataform. A função ref permite fazer referência e depender automaticamente dos seguintes objetos definidos no fluxo de trabalho SQL do Dataform, em vez de codificar o esquema e os nomes da tabela:

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, INSERT ou MERGE à instrução SQL.

O exemplo de código a seguir 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, forneça o nome da tabela ou da declaração da fonte de dados de que você quer depender. Normalmente, é o nome do arquivo SQLX em que essa tabela ou declaração de fonte de dados está definida.

Se um nome de 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 a modificação de nomes de tabelas, consulte Definir outras configurações de tabelas.

Quando você tem várias tabelas com o mesmo nome em esquemas diferentes, é possível referenciar 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, declaraçõ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 a seguir mostra uma dependência de tabela no bloco config:

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

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

Referenciar outras tabelas com resolve

A função resolve permite referenciar uma tabela ou declaração de 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 origem de dados.

Funções exigidas

Para receber as permissões necessárias para definir uma tabela, peça ao administrador para conceder a você o papel do IAM de Editor do Dataform (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou 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.

    Acessar 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. Clique em Criar arquivo.

  6. No campo Add a file path, insira o nome do arquivo seguido de .sqlx após definitions/. Por exemplo, definitions/my-table.sqlx.

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

  7. Clique em Criar arquivo.

Definir o tipo de tabela

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

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

  3. No arquivo, digite o seguinte 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 principal do ITableConfig Dataform.

  5. Opcional: clique em Formatar.

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, expanda 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 Formatar.

O exemplo de código a seguir 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 manuais de tabelas

Para adicionar dependências de tabela que não são mencionadas 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, expanda 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 dependência. Você pode inserir vários nomes de arquivos.

  4. Opcional: clique em Formatar.

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

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

A seguir