Ajouter de la documentation sur les tables

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

Vous pouvez ajouter des descriptions de tables, de colonnes et d'enregistrements à tous les types de tables dans Dataform: tables, tables incrémentielles et vues.

Nous vous recommandons de documenter les éléments suivants :

  • Objectif du tableau.
  • Contenu ou rôle des colonnes ou des enregistrements de la table.
  • 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 à la table.
  • Pré-opérations ou post-opérations appliquées à la table
  • le 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 flux de travail.

Avant de commencer

Avant de commencer, créez une table.

Rôles requis

Pour obtenir les autorisations nécessaires pour documenter une table, demandez à votre administrateur de vous attribuer 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 section Gérer les accès.

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 la console Cloud, 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 table que vous souhaitez modifier.

  5. Dans le bloc config du fichier, saisissez la description de la table 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 de 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 des descriptions de tables, de colonnes et d'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 sur les colonnes dans Dataform avec des inclusions

Vous pouvez réutiliser la description des colonnes dans votre workflow SQL avec 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.

Pour réutiliser les descriptions de toutes les colonnes d'une table, 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 en savoir plus sur la création et l'utilisation d'inclusions dans Dataform, consultez la page Réutiliser des variables et des fonctions avec des inclusions dans Dataform.

L'exemple de code suivant montre 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 sur 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 la documentation de toutes les colonnes de la table:

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

SELECT 1 AS one

Étapes suivantes