Aggiungi la documentazione della tabella

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

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

Ti consigliamo di documentare quanto segue :

  • Lo scopo della tabella.
  • I contenuti o il ruolo delle colonne o dei record nella tabella.
  • Relazione della tabella e di altri oggetti del flusso di lavoro SQL, ad esempio le tabelle o le viste che dipendono dalla tabella corrente.
  • Asserzioni applicate alla tabella.
  • Pre-operazioni o post-operazioni applicate alla tabella.
  • Proprietario della tabella, ovvero l'utente che l'ha creata. Questo 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 Dataform (roles/dataform.editor) per le aree di lavoro. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Potresti anche essere in grado di ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Aggiungi una descrizione per la 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 un'area 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 di tabella SQLX:

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

Aggiungi descrizioni di colonne e record

Per aggiungere descrizioni di singole colonne e record a un file SQLX, segui questi passaggi:

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

Riutilizza la documentazione delle colonne in Dataform con include

Puoi riutilizzare la descrizione delle colonne nel flusso di lavoro SQL con JavaScript include. Se nel flusso di lavoro SQL sono presenti più colonne con lo stesso nome e la stessa descrizione, è consigliabile riutilizzare la documentazione relativa alle colonne.

Puoi definire una costante con la 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 in una tabella. Per ulteriori informazioni sulla creazione e sull'utilizzo delle inclusioni in Dataform, consulta Riutilizzare le variabili e le funzioni con le inclusioni in Dataform.

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