Criar tabelas

No Dataform, uma tabela é um dos tipos de objetos que compõem um fluxo de trabalho. É possível criar tabelas que fazem referência a dados das fontes de dados declaradas para o fluxo de trabalho ou de outras tabelas no fluxo de trabalho. O Dataform compila as definições de tabelas 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 SQLX type: "table":

Também é possível definir partições e clusters de tabelas.

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 de uma tabela em relação a 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 delas falhar.

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

É possível configurar outras configurações de tabela para:

  • 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, adicione 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", você pode 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

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

    Acessar o Dataform

  2. Crie e inicialize um espaço de trabalho de desenvolvimento no repositório.

  3. Opcional: declare uma fonte de dados.

Funções exigidas

Para receber as permissões necessárias para concluir as tarefas neste documento, 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 uma tabela

Esta seção mostra como criar tabelas com o núcleo do 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 seu fluxo de trabalho.

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 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 ordenamento correto 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 fluxo de trabalho do Dataform, em vez de codificar o esquema e os nomes de 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 padrão à instrução SQL, como CREATE, REPLACE, INSERT ou MERGE.

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. Esse é normalmente 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, consulte 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 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 Declarar 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 a 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 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 Google Cloud, acesse a página Dataform.

    Acessar o 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 em 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 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 que 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" ] }

Criar partições e clusters de tabelas

Esta seção mostra como usar o núcleo do Dataform para criar partições e clusters de tabelas. O BigQuery oferece suporte a 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela.

  4. No bloco config, adicione o bloco bigquery abaixo da declaração de tipo de tabela neste formato:

    config {
  type: "table",
  bigquery: {
  }
}

  5. No bloco bigquery, insira o seguinte snippet de código:

        partitionBy: "PARTITION_EXPRESSION"

    Substitua PARTITION_EXPRESSION por uma expressão para particionar a tabela.

  6. Opcional: clique em Formato.

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:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela particionada.

  4. No bloco bigquery, insira o seguinte snippet de código:

    requirePartitionFilter : true

  5. Opcional: clique em Formato.

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 definir o atributo "require partition filter" em uma tabela particionada.

Definir um período de retenção para partições

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

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela particionada.

  4. No bloco bigquery, insira o seguinte snippet de código:

    partitionExpirationDays: NUMBER_OF_DAYS

    Substitua NUMBER_OF_DAYS pelo número de dias em que você quer reter as partições.

  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra um período de retenção para partições definido 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela.

  4. 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.

  5. Opcional: clique em Formato.

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

Esta seção mostra como usar o núcleo do Dataform 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 cria a tabela incremental 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 alterações na consulta de definição de tabela incremental, por exemplo, adicionando uma nova coluna, será necessário recriar a tabela do zero. Para fazer 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 novos registros em vez de repetir o processamento da tabela inteira.
Redução da latência
É possível usar tabelas incrementais para executar fluxos de trabalho rapidamente, mas com 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 processará durante cada execução, adicione uma cláusula WHERE condicional ao arquivo de definição SQLX da tabela incremental. Na cláusula WHERE, é possível especificar uma condição incremental e uma 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Abra um arquivo SQLX de definição de tabela incremental.

  4. 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 a 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.

  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental que processa de forma incremental 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 abaixo 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 garantir que uma tabela incremental contenha apenas uma linha correspondente a uma combinação selecionada de colunas, defina as colunas selecionadas como uniqueKey para mesclar linhas com o mesmo valor uniqueKey. Ao atualizar a tabela, o Dataform mescla linhas com o mesmo valor de uniqueKey em vez de anexá-las.

Para configurar a mesclagem em uma tabela incremental, siga estas etapas:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental

  4. No bloco config, defina as colunas selecionadas como uniqueKey no seguinte formato:

    uniqueKey: ["COLUMN_NAME"]

    Substitua COLUMN_NAME pelo nome de uma coluna selecionada.

  5. Opcional: clique em Formato.

O exemplo de código a seguir mostra uma tabela incremental com a coluna transaction_id definida como uniqueKey para garantir que ela sempre contenha 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 analise toda a tabela para encontrar linhas correspondentes, defina updatePartitionFilter para considerar apenas um subconjunto de registros.

O exemplo de código abaixo 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 fazer a ingestão de uma tabela particionada

Ao criar uma tabela incremental que faz referência a uma tabela particionada, recomendamos que você crie a consulta de 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 de tabela. Para transformar um valor da tabela particionada em uma expressão constante, use script 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 procurar a tabela inteira.

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

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental
  4. No bloco pre_operations, declare uma variável com o script do BigQuery.
  5. Filtre a instrução SELECT que define a tabela com uma cláusula WHERE que faz referência à variável declarada.
  6. Opcional: clique em Formato.

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.

Reconstruir 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 Run with full refresh ao acionar uma execução de fluxo de trabalho.

Quando você seleciona a opção de atualização completa no seu 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 a reconstrução do zero e a possível perda de dados, defina-a como protected. Talvez você queira 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:

  1. Acesse seu espaço de trabalho de desenvolvimento.
  2. No painel Files, abra definitions/.
  3. Selecione um arquivo SQLX de definição de tabela incremental.
  4. No bloco config, digite protected: true.
  5. Opcional: clique em Formato.

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

Esta seção mostra como adicionar descrições de uma tabela e suas colunas e registros 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.

Talvez você queira 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 de tabela

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

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

    Acessar o Dataform

  2. Selecione um repositório.

  3. Selecione um espaço de trabalho de desenvolvimento.

  4. No painel Files, clique no arquivo SQLX de definição de tabela que você quer editar.

  5. No bloco config do arquivo, insira a descrição da tabela no formato abaixo:

    description: "Description of the table",

  6. Opcional: clique em Formato.

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:

  1. No bloco config do arquivo de definição de tabela, insira columns: {}.

  2. Dentro de columns: {}, insira as descrições das colunas no seguinte formato:

    column_name: "Description of the column",

  3. Dentro de columns: {}, insira as descrições dos registros no seguinte formato:

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

  4. Opcional: clique em Formato.

O exemplo de código a seguir mostra descrições de tabela, coluna e registro 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 inclui

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

É possível definir uma constante com uma descrição de uma única coluna ou uma constante com uma descrição de conjunto ou 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 abaixo 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 de tabela SQLX definitions/my_table.sqlx para gerar documentação de 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 definido 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 abaixo mostra a constante columns, que é definida em includes/table_docs.js e usada no arquivo de definição de tabela SQLX definitions/my_table.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

A seguir