Aggiungi documentazione sulla tabella

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

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

Potresti voler documentare quanto segue :

  • Lo scopo della tabella.
  • Il contenuto o il ruolo delle colonne o dei record nella tabella.
  • Relazione della tabella e altri oggetti del flusso di lavoro SQL, ad esempio le tabelle o le visualizzazioni 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 su 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) sulle aree di lavoro. Per saperne di più sulla concessione dei ruoli, vedi Gestire l'accesso.

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

Aggiungi una descrizione della tabella

Per aggiungere una descrizione a una tabella in un file SQLX, segui questi passaggi:

  1. In Cloud Console, 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",

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",
 }

Aggiungi descrizioni alle colonne e ai 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",
  1. In 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"
      }
}

Il seguente esempio di codice mostra le descrizioni di tabella, colonna 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

Riutilizza la documentazione della colonna in Dataform con i

Puoi riutilizzare la descrizione delle colonne nel tuo flusso di lavoro SQL con JavaScript include. Ti consigliamo di riutilizzare la documentazione delle colonne se hai più colonne con lo stesso nome e la stessa descrizione nel tuo flusso di lavoro SQL.

Puoi definire una costante con una descrizione di una singola colonna o una costante con un insieme o una descrizione della colonna per riutilizzarle in una tabella. Per ulteriori informazioni sulla creazione e l'utilizzo delle funzionalità di inclusione in Dataform, consulta Riutilizzare le variabili e le funzioni con inclusione 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 colonna 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
};

L'esempio di codice riportato di seguito 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