Aggiungere la documentazione della tabella

Questo documento mostra come aggiungere descrizioni di una tabella, delle relative colonne e dei relativi record a un file SQLX di Dataform Core.

Puoi aggiungere descrizioni di tabelle, colonne e record a tutti i tipi di tabelle in Dataform: tabelle, tabelle incrementali e visualizzazioni.

Ti consigliamo di documentare quanto segue :

  • Lo scopo della tabella.
  • I contenuti o il ruolo delle colonne o dei record nella tabella.
  • Relazione tra la tabella e altri oggetti del tuo flusso di lavoro SQL, ad esempio le tabelle o le viste che dipendono dalla tabella corrente.
  • Verifiche applicate alla tabella.
  • Operazioni preliminari o successive applicate alla tabella.
  • Proprietario della tabella, ovvero l'utente che l'ha creata. Questa opzione può essere utile se più membri del team lavorano a un flusso di lavoro.

Prima di iniziare

Prima di iniziare, crea una tabella.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per documentare una tabella, chiedi all'amministratore di concederti il ruolo IAM Editor di Dataform (roles/dataform.editor) negli spazi di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Aggiungere una descrizione della tabella

Per aggiungere una descrizione a una tabella in un file SQLX:

  1. Nella console Cloud, vai alla pagina Dataform.

    Vai alla pagina Dataform

  2. Seleziona un repository.

  3. Seleziona uno spazio di lavoro di sviluppo.

  4. Nel riquadro File, fai clic sul file SQLX di definizione della tabella che vuoi modificare.

  5. Nel blocco config del file, inserisci la descrizione della tabella nel seguente formato:

    description: "Description of the table",

  6. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra una descrizione della tabella aggiunta al blocco config di un file di definizione della tabella SQLX:

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

Aggiungere descrizioni di colonne e record

Per aggiungere descrizioni di singole colonne e record a un file SQLX:

  1. Nel blocco config del file di definizione della tabella, inserisci columns: {}.

  2. All'interno di columns: {}, inserisci le descrizioni delle colonne nel seguente formato:

    column_name: "Description of the column",

  3. All'interno di columns: {}, inserisci le descrizioni dei record nel seguente formato:

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

  4. (Facoltativo) Fai clic su Formato.

Il seguente esempio di codice mostra le descrizioni di tabelle, colonne e record nel blocco config di un file di definizione della tabella 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

Riutilizzare la documentazione delle colonne in Dataform con gli elementi include

Puoi riutilizzare la descrizione delle colonne nel flusso di lavoro SQL con gli include di JavaScript. Potresti voler riutilizzare la documentazione delle colonne se nel flusso di lavoro SQL sono presenti più colonne con lo stesso nome e la stessa descrizione.

Puoi definire una costante con una descrizione di una singola colonna o una costante con una descrizione di un insieme o di una colonna per riutilizzare le descrizioni di tutte le colonne di una tabella. Per ulteriori informazioni sulla creazione e sull'utilizzo degli include in Dataform, consulta Riutilizzare il codice in un singolo repository con gli include.

Il seguente esempio di codice mostra più costanti con descrizioni di singole colonne definite nel file 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,
};

Il seguente esempio di codice mostra le costanti user_id e age, definite in includes/docs.js, utilizzate nel file di definizione della tabella SQLX definitions/my_table.sqlx per generare la documentazione per le colonne selezionate della tabella:

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

Il seguente esempio di codice mostra una costante con un insieme di descrizioni delle colonne definite nel file 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
};

Il seguente esempio di codice mostra la costante columns, definita in includes/table_docs.js, utilizzata nel file di definizione della tabella SQLX definitions/my_table.sqlx per generare la documentazione per tutte le colonne della tabella:

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

SELECT 1 AS one

Passaggi successivi