Adicionar documentação da tabela

Este documento 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.
  • Relação da tabela e de outros objetos do fluxo de trabalho SQL, por exemplo, as tabelas ou visualizações que dependem da tabela atual.
  • Declarações aplicadas à tabela.
  • Operações anteriores ou posteriores aplicadas à tabela.
  • Proprietário da tabela, ou seja, o usuário que a criou. Isso pode ser útil se vários membros da equipe trabalharem em um fluxo de trabalho.

Antes de começar

Antes de começar, crie uma tabela.

Funções exigidas

Para receber as permissões necessárias para documentar uma tabela, peça ao administrador que conceda a você o Papel do IAM (roles/dataform.editor) do Dataform 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.

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 Cloud, acesse a página Dataform.

    Acesse a página do 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 no Dataform com inclui

É possível reutilizar a descrição de colunas em todo o fluxo de trabalho SQL com incluiçõ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 para 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 a seguir mostra a constante columns, definida em includes/table_docs.js, 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