Adicionar documentação de tabela

Neste documento, mostramos como adicionar descrições de uma tabela e das colunas e registros de uma tabela a um arquivo SQLX principal do Dataform.

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

É recomendado 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 outros objetos do fluxo de trabalho SQL, por exemplo, as tabelas ou visualizações que dependem da tabela atual.
  • Declarações aplicadas à tabela.
  • Pré-operações ou pós-operações aplicadas à tabela.
  • Proprietário da tabela, ou seja, o usuário que a criou. Isso pode ser útil se vários membros da equipe trabalham em um fluxo de trabalho.

Antes de começar

Antes de começar, crie uma tabela.

Funções exigidas

Para ter as permissões necessárias para documentar 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.

Adicionar uma descrição à 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.

    Acessar a página do Dataform

  2. Selecione um repositório.

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

  4. No painel Arquivos, 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 seguinte formato:

    description: "Description of the table",

  6. 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:

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

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

    column_name: "Description of the column",

  3. Dentro de 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"
      }
}

  4. Opcional: clique em Formatar.

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 do 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 inclusões

É possível reutilizar a descrição de colunas em todo o fluxo de trabalho SQL com JavaScript. Convém reutilizar a documentação se você tiver várias colunas com o mesmo nome e descrição no fluxo de trabalho SQL.

Você pode definir uma constante com uma descrição de uma única coluna ou uma constante com uma descrição de conjunto ou coluna para reutilizar descrições de todas as colunas em uma tabela. Para mais informações sobre como criar e usar inclusões no Dataform, consulte Reutilizar variáveis e funções com inclusões no Dataform.

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 da tabela SQLX definitions/my_table.sqlx para gerar a 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, definida em includes/table_docs.js, usada no arquivo de definição de tabela SQLX definitions/my_table.sqlx para gerar a documentação de todas as colunas na tabela:

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

SELECT 1 AS one

A seguir