Esta página foi traduzida pela API Cloud Translation.

Criar tabelas

No Dataform, uma tabela é um dos tipos de objetos que compõem um fluxo de trabalho. É possível criar tabelas que referenciam dados das fontes de dados declaradas para seu fluxo de trabalho ou de outras tabelas nele. O Dataform compila suas definições de tabela em SQL em tempo real. Quando você aciona a execução, o Dataform executa o código SQL e cria as tabelas definidas no BigQuery.

É possível criar os seguintes tipos de tabela em um arquivo type: "table" SQLX:

table: uma tabela normal.
incremental: uma tabela incremental.
view: uma visualização em tabela. Para mais informações, consulte Introdução às visualizações.
- materialized: uma visualização em tabela materializada. Para mais informações, consulte Introdução às visualizações materializadas.

Você também pode definir partições e clusters de tabela.

Para manter um registro da finalidade de uma tabela ou da relação dela com outras tabelas no seu fluxo de trabalho, adicione documentação à tabela ou às colunas selecionadas.

Para testar os dados em uma tabela de acordo com condições específicas, crie consultas de teste de qualidade de dados chamadas asserções. O Dataform executa declarações sempre que atualiza seu fluxo de trabalho e alerta você se alguma declaração falhar.

Para substituir as configurações padrão da tabela, como database ou schema, desativar a criação de tabelas ou executar uma instrução SQL antes ou depois da criação da tabela, configure outras configurações de tabela.

É possível configurar outras opções de tabela para fazer o seguinte:

Substitua as configurações padrão da tabela, como database ou schema.
Desative a criação de tabelas.
Execute uma instrução SQL antes ou depois da criação da tabela.

Para organizar suas tabelas no BigQuery depois de executá-las, você pode adicionar rótulos do BigQuery. Para saber mais, consulte Introdução aos rótulos.

Para restringir o acesso a dados no nível da coluna da tabela, adicione tags de política do BigQuery. Para saber mais, consulte Introdução ao controle de acesso no nível da coluna.

Além de definir tabelas em um arquivo SQLX type: "table", é possível criar tabelas vazias definindo uma consulta SQL personalizada em um arquivo SQLX type: "operations". Talvez você queira criar uma tabela vazia para que um serviço diferente possa preenchê-la com dados.

Antes de começar

No Google Cloud console, acesse a página Dataform.

Acesse o Dataform
Crie e inicialize um espaço de trabalho de desenvolvimento no seu repositório.
Opcional: declarar uma fonte de dados.

Funções exigidas

Para receber as permissões necessárias para concluir as tarefas neste documento, peça ao administrador para conceder a você o papel Editor do Dataform (roles/dataform.editor) do IAM em 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 uma tabela

Nesta seção, mostramos como criar tabelas com o Dataform Core no Dataform.

Sobre as definições de tabela

Para definir uma tabela, defina o tipo dela e escreva uma instrução SELECT em um arquivo type: "table" SQLX. 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 do Dataform Core, você define a estrutura da tabela e faz referência a outros objetos do seu fluxo de trabalho.

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

Referenciar dependências com `ref`

Para referenciar um objeto de fluxo de trabalho 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 verificar a ordenação correta do pipeline.

A função ref é uma função principal integrada 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 seu fluxo de trabalho do Dataform, em vez de codificar os nomes de esquema e tabela:

Tabelas de todos os tipos de tabela compatíveis.
Declarações de origem de dados.
Operações SQL personalizadas com a propriedade hasOutput definida como true.

O Dataform usa a função ref para criar uma árvore de dependências de todas as tabelas a serem criadas ou atualizadas.

Depois da compilação, o Dataform adiciona instruções boilerplate à instrução SQL, como CREATE, REPLACE, INSERT ou MERGE.

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, você fornece o nome da tabela ou da declaração de fonte de dados de que quer depender. Normalmente, esse é o nome do arquivo SQLX em que a declaração da tabela ou da fonte de dados é 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 como substituir nomes de tabelas, consulte Configurar outras definições de tabela.

Quando você tem várias tabelas com o mesmo nome em esquemas diferentes, é possível referenciar uma tabela específica fornecendo dois argumentos à 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 a seguir 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 seu fluxo de trabalho, consulte Definir dependências.

Fazer referência a 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 a função resolve não afeta a execução da tabela que usa essa função.resolve

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

criar um arquivo SQLX para uma definição de tabela

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

No Google Cloud console, acesse a página Dataform.

Acesse o Dataform
Para abrir um repositório, clique no nome dele.
Para abrir um espaço de trabalho de desenvolvimento, clique no nome dele.
No painel Arquivos, ao lado de definitions/, clique em Mais.
Selecione Criar arquivo.
No campo Adicionar um caminho de arquivo, insira 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.
Selecione Criar arquivo.

Definir o tipo de tabela

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

No espaço de trabalho de desenvolvimento, no painel Arquivos, abra o diretório definitions/.
Selecione o arquivo SQLX de definição de tabela que você quer editar.
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
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 ITableConfig.
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:

No espaço de trabalho de desenvolvimento, no painel Arquivos, abra o diretório definitions/.
Selecione o arquivo SQLX de definição de tabela que você quer editar.
Abaixo do bloco config, escreva uma instrução SELECT.
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 de tabela manual

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:

No espaço de trabalho de desenvolvimento, no painel Arquivos, abra o diretório definitions/.
Selecione o arquivo SQLX de definição de tabela que você quer editar.
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.
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" ] }

Criar partições e clusters de tabelas

Nesta seção, mostramos como usar o Dataform Core para criar partições e clusters de tabela. O BigQuery é compatível com tabelas particionadas e clustering de tabelas. Para mais informações, consulte Introdução às tabelas particionadas e Como criar e usar tabelas em cluster.

Criar uma partição de tabela

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

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Abra um arquivo SQLX de definição de tabela.
No bloco config, adicione o bloco bigquery abaixo da declaração do tipo de tabela no seguinte formato:
```
config {
  type: "table",
  bigquery: {
  }
}
```
No bloco bigquery, insira o seguinte snippet de código:
```
    partitionBy: "PARTITION_EXPRESSION"
```
Substitua PARTITION_EXPRESSION por uma expressão para particionar a tabela.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra o particionamento de uma tabela por hora em um arquivo SQLX de definição de tabela:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

O exemplo de código a seguir mostra o particionamento de uma tabela por um valor inteiro em um arquivo SQLX de definição de tabela:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Definir um filtro de partição

Para definir um filtro de partição, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Abra um arquivo SQLX de definição de tabela particionada.
No bloco bigquery, insira o seguinte snippet de código:
```
requirePartitionFilter : true
```
Opcional: clique em Formatar.

O exemplo de código a seguir mostra um filtro de partição definido no bloco bigquery de um arquivo SQLX de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Para mais informações sobre o filtro de partição no BigQuery, consulte Como configurar o atributo "require partition filter" em uma tabela particionada.

Definir um período de armazenamento para partições

Para controlar a retenção de todas as partições em uma tabela particionada, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Abra um arquivo SQLX de definição de tabela particionada.
No bloco bigquery, insira o seguinte snippet de código:
```
partitionExpirationDays: NUMBER_OF_DAYS
```
Substitua NUMBER_OF_DAYS pelo número de dias que você quer manter as partições.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra um período de armazenamento para partições definidas como 14 dias no bloco bigquery de um arquivo SQLX de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Criar um cluster de tabelas

Para criar um cluster de tabelas, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Abra um arquivo SQLX de definição de tabela.
No bloco bigquery, insira o seguinte snippet de código:
```
    clusterBy: ["CLUSTER_COLUMN"]
```
Substitua CLUSTER_COLUMN pelo nome da coluna que você quer usar para agrupar a tabela. Para mais informações, consulte clustering_column_list.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma tabela particionada agrupada por colunas name e revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Configurar uma tabela incremental

Nesta seção, mostramos como usar o Dataform Core para configurar uma tabela incremental.

Sobre as tabelas incrementais

O Dataform atualiza as tabelas de maneira diferente com base no tipo delas. Durante cada execução de uma tabela ou visualização, o Dataform recria toda a tabela ou visualização do zero.

Quando você define uma tabela incremental, o Dataform a cria do zero apenas na primeira vez. Durante as execuções subsequentes, o Dataform só insere ou mescla novas linhas na tabela incremental de acordo com as condições configuradas.

O Dataform insere novas linhas apenas em colunas que já existem na tabela incremental. Se você fizer mudanças na consulta de definição da tabela incremental, por exemplo, adicionando uma nova coluna, será necessário recriar a tabela do zero. Para isso, na próxima vez que você acionar uma execução da tabela, selecione a opção Executar com atualização completa.

Confira alguns casos de uso comuns para tabelas incrementais:

Otimização de desempenho: Para alguns tipos de dados, como registros da Web ou dados de análise, talvez seja melhor processar apenas os novos registros em vez de reprocessar a tabela inteira.
Redução de latência: É possível usar tabelas incrementais para executar fluxos de trabalho com rapidez e frequência, reduzindo a latência downstream das tabelas de saída.
Snapshots diários: É possível configurar uma tabela incremental para criar snapshots diários dos dados da tabela, por exemplo, para análise longitudinal das configurações do usuário armazenadas em um banco de dados de produção.

Processar um subconjunto de linhas em uma tabela incremental

Para determinar um subconjunto de linhas que o Dataform vai processar durante cada execução, adicione uma cláusula condicional WHERE ao arquivo de definição SQLX da tabela incremental. Na cláusula WHERE, é possível especificar uma condição incremental e uma condição não incremental. O Dataform aplica a condição incremental durante a execução da tabela sem uma atualização completa e a condição não incremental durante a execução com uma atualização completa.

Para configurar uma tabela incremental, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Abra um arquivo SQLX de definição de tabela incremental.
Insira uma cláusula WHERE no seguinte formato:
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
```
Substitua:
- SELECT_STATEMENT: a instrução SELECT que define sua tabela.
- INCREMENTAL_CONDITION: a condição especificada na cláusula WHERE para selecionar linhas que o Dataform vai processar durante a execução da tabela sem uma atualização completa.
- NON_INCREMENTAL_CONDITION: a condição especificada na cláusula WHERE para selecionar linhas que o Dataform vai processar durante a execução da tabela com uma atualização completa.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma tabela incremental que processa incrementalmente linhas da tabela productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

O exemplo de código a seguir mostra uma tabela incremental que cria um snapshot da tabela productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Mesclar linhas em uma tabela incremental

Para verificar se uma tabela incremental contém apenas uma linha correspondente a uma combinação selecionada de colunas, defina as colunas selecionadas como uniqueKey para mesclar linhas que têm o mesmo valor de uniqueKey. Ao atualizar a tabela, o Dataform mescla as linhas com o mesmo valor de uniqueKey em vez de anexá-las.

Para configurar a fusão em uma tabela incremental, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Selecionar um arquivo SQLX de definição de tabela incremental
No bloco config, defina as colunas selecionadas como uniqueKey no seguinte formato:
```
uniqueKey: ["COLUMN_NAME"]
```
Substitua COLUMN_NAME pelo nome de uma coluna selecionada.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma tabela incremental com a coluna transaction_id definida como uniqueKey para verificar se ela sempre contém uma linha:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Filtrar linhas em uma tabela incremental

Em uma tabela particionada incremental, para evitar que o Dataform verifique a tabela inteira em busca de linhas correspondentes, defina updatePartitionFilter para considerar apenas um subconjunto de registros.

A exemplo de código a seguir mostra uma tabela particionada incremental com mesclagem configurada definindo as propriedades uniqueKey e updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Evite verificações de tabela completas ao ingerir dados de uma tabela particionada

Ao criar uma tabela incremental que faz referência a uma tabela particionada, recomendamos que você crie a consulta da tabela para evitar verificações completas da tabela particionada durante cada atualização incremental.

É possível limitar o número de partições que o BigQuery verifica para atualizar a tabela incremental usando uma expressão constante na consulta da tabela. Para transformar um valor da tabela particionada em uma expressão constante, use a programação de scripts do BigQuery para declarar o valor como uma variável no bloco pre_operations. Em seguida, use a variável como uma expressão constante em uma cláusula WHERE na consulta SELECT.

Com essa configuração, o Dataform atualiza a tabela incremental com base nas partições mais recentes da tabela particionada referenciada, sem verificar a tabela inteira.

Para configurar uma tabela incremental que faz referência a uma tabela particionada e evita verificações completas, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Selecionar um arquivo SQLX de definição de tabela incremental
No bloco pre_operations, declare uma variável com a linguagem de script do BigQuery.
Filtre a instrução SELECT que define a tabela com uma cláusula WHERE que faz referência à variável declarada.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma tabela incremental em que a tabela raw_events referenciada é particionada por event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

No exemplo de código anterior, a variável event_timestamp_checkpoint é definida no bloco pre_operations. A variável event_timestamp_checkpoint é usada como uma expressão constante na cláusula WHERE.

Recriar uma tabela incremental do zero com atualização completa

É possível forçar a reconstrução de uma tabela incremental do zero usando a interface de linha de comando com a opção --full-refresh ou a opção Executar com atualização completa ao acionar a execução de um fluxo de trabalho.

Quando você seleciona a opção de atualização completa no espaço de trabalho de desenvolvimento ou usando a CLI do Dataform, o Dataform ignora o parâmetro ${when(incremental(), ... } durante a execução e recria a tabela com uma instrução CREATE OR REPLACE.

Proteger uma tabela incremental contra atualização completa

Para proteger uma tabela incremental contra reconstrução do zero e possível perda de dados, defina a tabela incremental como protected. Talvez seja necessário impedir que uma tabela incremental seja recriada se a fonte de dados for temporária.

Para marcar uma tabela incremental como protected, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Selecione um arquivo SQLX de definição de tabela incremental.
No bloco config, digite protected: true.
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma tabela incremental marcada como protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Adicionar documentação da tabela

Nesta seção, mostramos como adicionar descrições de uma tabela e das colunas e registros dela a um arquivo SQLX principal do Dataform.

É possível adicionar descrições de tabelas, colunas e registros a todos os tipos de tabelas no Dataform: tabelas, tabelas incrementais e visualizações.

É recomendável documentar o seguinte:

A finalidade da tabela.
O conteúdo ou a função das colunas ou dos registros na tabela.
A relação da tabela e outras ações do seu fluxo de trabalho, por exemplo, as tabelas ou visualizações que dependem da tabela atual.
As declarações aplicadas à tabela.
As pré-operações ou pós-operações aplicadas à tabela.
O proprietário da tabela, ou seja, o usuário que a criou. Essas informações podem ser úteis se vários membros da equipe trabalharem em um fluxo de trabalho.

Adicionar uma descrição da tabela

Para adicionar uma descrição a uma tabela em um arquivo SQLX, siga estas etapas:

No Google Cloud console, acesse a página Dataform.

Acesse o Dataform
Selecione um repositório.
Selecione um espaço de trabalho de desenvolvimento.
No painel Arquivos, clique no arquivo SQLX de definição de tabela que você quer editar.
No bloco config do arquivo, insira a descrição da tabela no seguinte formato:
```
description: "Description of the table",
```
Opcional: clique em Formatar.

O exemplo de código a seguir mostra uma descrição de tabela adicionada ao bloco config de um arquivo de definição de tabela SQLX:

config {
  type: "table",
  description: "Description of the table",
 }

Adicionar descrições de colunas e registros

Para adicionar descrições de colunas e registros individuais a um arquivo SQLX, siga estas etapas:

No bloco config do arquivo de definição de tabela, insira columns: {}.
Em columns: {}, insira as descrições de coluna no seguinte formato:
```
column_name: "Description of the column",
```

Em columns: {}, insira as descrições de registro no seguinte formato:

  record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

Opcional: clique em Formatar.

O exemplo de código a seguir mostra descrições de tabelas, colunas e registros no bloco config de um arquivo de definição de tabela SQLX:

config {
  type: "table",
  description: "Description of the table.",
  columns: {
    column1_name: "Description of the first column",
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    record_name: {
      description: "Description of the record.",
      columns: {
       record_column1_name: "Description of the first record column",
       record_column2_name: "Description of the second record column",
      }
    }
  }
}
SELECT
  "first_column_value" AS column_1_name,
  "second_column_value" AS column_2_name,
  "third_column_value" AS column_3_name,
  STRUCT("first" AS record_column1_name,
    "second" AS record_column2_name) AS record_name

Reutilizar a documentação de colunas com inclusões

É possível reutilizar descrições de colunas no Dataform em todo o fluxo de trabalho SQL com inclusões de JavaScript. Talvez você queira reutilizar a documentação de colunas se tiver várias colunas com o mesmo nome e descrição no fluxo de trabalho do SQL.

Para criar uma descrição de coluna reutilizável, defina uma constante de inclusão do JavaScript com o nome e a descrição da coluna.

É possível definir uma constante com a descrição de uma única coluna ou com um conjunto ou descrição de coluna para reutilizar as descrições de todas as colunas em uma tabela. Para mais informações sobre como criar e usar inclusões no Dataform, consulte Reutilizar código em um único repositório com inclusões.

O exemplo de código a seguir mostra várias constantes com descrições de colunas individuais definidas no arquivo JavaScript includes/docs.js:


// filename is includes/docs.js

const user_id = `A unique identifier for a user`;
const age = `The age of a user`;
const creation_date = `The date this user signed up`;
const user_tenure = `The number of years since the user's creation date`;
const badge_count = `The all-time number of badges the user has received`;
const questions_and_answer_count = `The all-time number of questions and answers the user has created`;
const question_count = `The all-time number of questions the user has created`;
const answer_count = `The all-time number of answers the user has created`;
const last_badge_received_at = `The time the user received their most recent badge`;
const last_posted_at = `The time the user last posted a question or answer`;
const last_question_posted_at = `The time the user last posted an answer`;
const last_answer_posted_at = `The time the user last posted a question`;

module.exports = {
   user_id,
   age,
   creation_date,
   user_tenure,
   badge_count,
   questions_and_answer_count,
   question_count,
   answer_count,
   last_badge_received_at,
   last_posted_at,
   last_question_posted_at,
   last_answer_posted_at,
};

O exemplo de código a seguir mostra as constantes user_id e age, definidas em includes/docs.js, usadas no arquivo de definição da tabela definitions/my_table.sqlx SQLX para gerar documentação das colunas selecionadas na tabela:

config {
  type: "table",
  description: "Table description.",
  columns: {
    user_id: docs.user_id,
    column2_name: "Description of the second column",
    column3_name: "Description of the third column",
    age: docs.age,
  }
}

SELECT ...

O exemplo de código a seguir mostra uma constante com um conjunto de descrições de colunas definidas no arquivo JavaScript includes/docs.js:


// filename is includes/docs.js

const columns = {
    user_id = `A unique identifier for a user`,
    age = `The age of a user`,
    creation_date = `The date this user signed up`,
    user_tenure = `The number of years since the user's creation date`,
    badge_count = `The all-time number of badges the user has received`,
    questions_and_answer_count = `The all-time number of questions and answers the user has created`,
    question_count = `The all-time number of questions the user has created`,
    answer_count = `The all-time number of answers the user has created`,
    last_badge_received_at = `The time the user received their most recent badge`,
    last_posted_at = `The time the user last posted a question or answer`,
    last_question_posted_at = `The time the user last posted an answer`,
    last_answer_posted_at = `The time the user last posted a question`,
}


module.exports = {
  columns
};

O exemplo de código a seguir mostra a constante columns, que é definida em includes/table_docs.js e usada no arquivo de definição da tabela definitions/my_table.sqlx SQLX para gerar documentação de todas as colunas da tabela:

config { type: "table",
description: "My table description",
columns: docs.columns
}

SELECT 1 AS one

Adicionar rótulos do BigQuery

Esta seção mostra como adicionar rótulos a tabelas no Dataform.

O BigQuery permite adicionar rótulos aos recursos. Para mais informações sobre rótulos no BigQuery, consulte Introdução aos rótulos.

Para adicionar um rótulo do BigQuery a uma tabela no Dataform, adicione o rótulo ao bloco bigquery no bloco config do arquivo SQLX de definição da tabela.

Para adicionar um rótulo do BigQuery a um arquivo de definição de tabela, siga estas etapas:

Acesse o espaço de trabalho de desenvolvimento.
No painel Arquivos, expanda definitions/.
Selecione um arquivo de definição de tabela SQLX.
No bloco config, adicione um rótulo no seguinte formato:
```
bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }
```
Substitua:
- LABEL1: o nome do seu rótulo
- VALUE_OF_LABEL1: o valor do seu rótulo
Opcional: para adicionar um rótulo com um nome que contenha caracteres especiais, insira o nome do rótulo entre aspas ("").
Opcional: clique em Formatar.

O exemplo de código a seguir mostra os rótulos department:shipping e cost-center:logistics adicionados ao bloco bigquery em um arquivo SQLX de definição de tabela particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

A seguir

Para saber como configurar outras opções de tabela, consulte Configurar outras opções de tabela.
Para saber como testar dados de tabela com asserções, consulte Testar tabelas com asserções.
Para saber como definir tabelas com JavaScript, consulte Criar fluxos de trabalho do Dataform com JavaScript.
Para saber como reutilizar código com inclusões, consulte Reutilizar código em um único repositório com inclusões.
Para saber como usar a interface de linha de comando do Dataform, consulte Usar a CLI do Dataform.

Criar tabelas Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.