Adicionar documentação da tabela

Neste documento, mostramos como adicionar descrições de uma tabela e das colunas e registros dela a um arquivo SQLX do núcleo 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.

Você pode documentar o seguinte :

  • A finalidade da tabela.
  • O conteúdo ou o papel das colunas ou 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.
  • 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 conseguir as permissões necessárias para documentar uma tabela, peça ao administrador que conceda a você o papel de Editor do Dataform (roles/dataform.editor) nos espaços de trabalho. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Adicionar uma descrição da 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 da 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",

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 do SQLX:

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

Adicionar coluna e registrar descrições

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. Em columns: {}, insira as descrições de coluna no seguinte formato:
column_name: "Description of the column",
  1. 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"
      }
}

A 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 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 da coluna no Dataform com o include

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

É possível definir uma constante com a descrição de uma única coluna ou uma constante com uma descrição de conjunto ou 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 variáveis e funções com inclusões no Dataform.

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