Ajouter la documentation du tableau

Ce document explique comment ajouter des descriptions d'une table, de ses colonnes et de ses enregistrements à un fichier SQLX de base Dataform.

Vous pouvez ajouter des descriptions de table, de colonne et d'enregistrement à tous les types de tableaux dans Dataform: tableaux, tableaux incrémentaux et vues.

Vous pouvez documenter les éléments suivants :

  • Objectif de la table.
  • Contenu ou rôle des colonnes ou des enregistrements du tableau.
  • Relation entre la table et les autres objets de votre workflow SQL, par exemple, les tables ou les vues qui dépendent de la table actuelle.
  • Assertions appliquées au tableau.
  • Pré-opérations ou post-opérations appliquées au tableau.
  • Propriétaire de la table, c'est-à-dire l'utilisateur qui l'a créée. Cela peut être utile si plusieurs membres de l'équipe travaillent sur un workflow.

Avant de commencer

Avant de commencer, créez un tableau.

Rôles requis

Pour obtenir les autorisations nécessaires pour documenter une table, demandez à votre administrateur de vous accorder le rôle IAM Éditeur Dataform (roles/dataform.editor) sur les espaces de travail. Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Ajouter une description de la table

Pour ajouter une description à une table dans un fichier SQLX, procédez comme suit:

  1. Dans Cloud Console, accédez à la page Dataform.

    Accéder à la page Dataform

  2. Sélectionnez un dépôt.

  3. Sélectionnez un espace de travail de développement.

  4. Dans le volet Fichiers, cliquez sur le fichier SQLX de définition de la table que vous souhaitez modifier.

  5. Dans le bloc config du fichier, saisissez la description du tableau au format suivant:

    description: "Description of the table",

  6. Facultatif: cliquez sur Format.

L'exemple de code suivant montre une description de table ajoutée au bloc config d'un fichier de définition de table SQLX:

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

Ajouter des descriptions de colonnes et d'enregistrements

Pour ajouter des descriptions de colonnes et d'enregistrements individuels à un fichier SQLX, procédez comme suit:

  1. Dans le bloc config de votre fichier de définition de table, saisissez columns: {}.

  2. Dans columns: {}, saisissez les descriptions des colonnes au format suivant:

    column_name: "Description of the column",

  3. Dans columns: {}, saisissez les descriptions des enregistrements au format suivant:

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

  4. Facultatif: cliquez sur Format.

L'exemple de code suivant montre les descriptions de la table, des colonnes et des enregistrements dans le bloc config d'un fichier de définition de table 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

Réutiliser la documentation des colonnes dans Dataform avec des inclusions

Vous pouvez réutiliser la description des colonnes dans votre workflow SQL à l'aide d'inclusions JavaScript. Vous pouvez réutiliser la documentation des colonnes si plusieurs colonnes portent le même nom et la même description dans votre workflow SQL.

Vous pouvez définir une constante avec la description d'une seule colonne, ou une constante avec une description d'ensemble ou de colonne pour réutiliser les descriptions de toutes les colonnes d'une table. Pour en savoir plus sur la création et l'utilisation d'inclusions dans Dataform, consultez la section Réutiliser du code dans un seul dépôt avec des inclusions.

L'exemple de code suivant présente plusieurs constantes avec des descriptions de colonnes individuelles définies dans le fichier 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,
};

L'exemple de code suivant montre les constantes user_id et age, définies dans includes/docs.js, utilisées dans le fichier de définition de table SQLX definitions/my_table.sqlx pour générer de la documentation pour les colonnes sélectionnées dans la table:

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

L'exemple de code suivant montre une constante avec un ensemble de descriptions de colonnes définies dans le fichier 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'exemple de code suivant montre la constante columns, définie dans includes/table_docs.js, utilisée dans le fichier de définition de table SQLX definitions/my_table.sqlx pour générer de la documentation pour toutes les colonnes de la table:

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

SELECT 1 AS one

Étape suivante