Tabellendokumentation hinzufügen

In diesem Dokument wird beschrieben, wie Sie einer Dataform-Core-SQLX-Datei Beschreibungen für eine Tabelle und ihre Spalten und Einträge hinzufügen.

Sie können allen Tabellentypen in Dataform Beschreibungen für Tabellen, Spalten und Einträge hinzufügen: Tabellen, inkrementelle Tabellen und Ansichten.

Sie sollten Folgendes dokumentieren :

  • Der Zweck der Tabelle.
  • Der Inhalt oder die Rolle von Spalten oder Einträgen in der Tabelle.
  • Beziehung zwischen der Tabelle und anderen Objekten Ihres SQL-Workflows, z. B. Tabellen oder Ansichten, die von der aktuellen Tabelle abhängen.
  • Auf die Tabelle angewendete Behauptungen.
  • Vor- oder Nachbearbeitungen, die auf die Tabelle angewendet werden.
  • Inhaber der Tabelle, also der Nutzer, der sie erstellt hat. Das kann nützlich sein, wenn mehrere Teammitglieder an einem Workflow arbeiten.

Hinweis

Bevor Sie beginnen, erstellen Sie eine Tabelle.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen für Workspaces die IAM-Rolle Dataform Editor (roles/dataform.editor) zuzuweisen, damit Sie die Berechtigungen erhalten, die Sie zum Dokumentieren einer Tabelle benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Tabellenbeschreibung hinzufügen

So fügen Sie einer Tabelle in einer SQLX-Datei eine Beschreibung hinzu:

  1. Rufen Sie in der Cloud Console die Seite Dataform auf.

    Zur Seite „Dataform“

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

  4. Klicken Sie im Bereich Dateien auf die SQLX-Datei der Tabellendefinition, die Sie bearbeiten möchten.

  5. Geben Sie im Block config der Datei die Tabellenbeschreibung im folgenden Format ein:

    description: "Description of the table",

  6. Optional: Klicken Sie auf Formatieren.

Im folgenden Codebeispiel wird eine Tabellenbeschreibung gezeigt, die dem Block config einer SQLX-Tabellendefinitiondatei hinzugefügt wurde:

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

Spalten- und Datensatzbeschreibungen hinzufügen

So fügen Sie einer SQLX-Datei Beschreibungen einzelner Spalten und Einträge hinzu:

  1. Geben Sie in der Tabellendefinitionsdatei im Block config den Wert columns: {} ein.

  2. Geben Sie in columns: {} Spaltenbeschreibungen im folgenden Format ein:

    column_name: "Description of the column",

  3. Geben Sie in columns: {} Eintragsbeschreibungen im folgenden Format ein:

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

  4. Optional: Klicken Sie auf Formatieren.

Im folgenden Codebeispiel sind Tabellen-, Spalten- und Datensatzbeschreibungen im config-Block einer SQLX-Tabellendefinitiondatei zu sehen:

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

Spaltendokumentation in Dataform mit Includes wiederverwenden

Mit JavaScript-Includes können Sie die Beschreibung von Spalten in Ihrem SQL-Workflow wiederverwenden. Sie können die Spaltendokumentation wiederverwenden, wenn Sie in Ihrem SQL-Workflow mehrere Spalten mit demselben Namen und derselben Beschreibung haben.

Sie können eine Konstante mit einer Beschreibung einer einzelnen Spalte oder einer Konstante mit einer Satz- oder Spaltenbeschreibung definieren, um Beschreibungen aller Spalten in einer Tabelle wiederzuverwenden. Weitere Informationen zum Erstellen und Verwenden von Includes in Dataform finden Sie unter Code in einem einzelnen Repository mit Includes wiederverwenden.

Das folgende Codebeispiel zeigt mehrere Konstanten mit Beschreibungen einzelner Spalten, die in der JavaScript-Datei includes/docs.js definiert sind:


// 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,
};

Das folgende Codebeispiel zeigt die in includes/docs.js definierten Konstanten user_id und age, die in der SQLX-Tabellendefinitiondatei definitions/my_table.sqlx verwendet werden, um Dokumentation für ausgewählte Spalten in der Tabelle zu generieren:

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

Das folgende Codebeispiel zeigt eine Konstante mit einer Reihe von Spaltenbeschreibungen, die in der JavaScript-Datei includes/docs.js definiert sind:


// 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
};

Im folgenden Codebeispiel wird die in includes/table_docs.js definierte Konstante columns gezeigt, die in der SQLX-Tabellendefinitiondatei definitions/my_table.sqlx verwendet wird, um Dokumentation für alle Spalten in der Tabelle zu generieren:

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

SELECT 1 AS one

Nächste Schritte