Tabellendokumentation hinzufügen

In diesem Dokument erfahren Sie, wie Sie einer Dataform Core-SQLX-Datei Beschreibungen einer Tabelle und ihrer Spalten und Datensätze hinzufügen.

Sie können allen Tabellentypen in Dataform Tabellen-, Spalten- und Datensatzbeschreibungen hinzufügen: Tabellen, inkrementelle Tabellen und Ansichten.

Es empfiehlt sich, Folgendes zu dokumentieren :

  • Der Zweck der Tabelle.
  • Der Inhalt oder die Rolle von Spalten oder Datensätzen in der Tabelle.
  • Beziehung der Tabelle und anderer Objekte Ihres SQL-Workflows, z. B. die Tabellen oder Ansichten, die von der aktuellen Tabelle abhängen.
  • Auf die Tabelle angewendete Assertions
  • Vor- oder Nachvorgänge auf die Tabelle angewendet.
  • Eigentümer der Tabelle, d. h. der Nutzer, der sie erstellt hat. Dies kann nützlich sein, wenn mehrere Teammitglieder an einem Workflow arbeiten.

Hinweise

Erstellen Sie zuerst eine Tabelle.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Dataform Editor (roles/dataform.editor) für Arbeitsbereiche zu gewähren, um die Berechtigungen zu erhalten, die Sie zum Dokumentieren einer Tabelle benötigen. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

Möglicherweise können Sie 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 Files (Dateien) auf die SQLX-Tabellendefinitionsdatei, 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 Format.

Das folgende Codebeispiel zeigt eine Tabellenbeschreibung, die dem Block config einer SQLX-Tabellendefinitionsdatei hinzugefügt wird:

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

Beschreibungen für Spalten und Datensätze hinzufügen

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

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

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

    column_name: "Description of the column",

  3. Geben Sie in columns: {} die 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 Format.

Das folgende Codebeispiel zeigt Beschreibungen von Tabellen, Spalten und Einträgen im Block config einer SQLX-Tabellendefinitionsdatei:

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 Einfügungen wiederverwenden

Sie können die Beschreibung von Spalten in Ihrem gesamten SQL-Workflow mit JavaScript-Einschließen wiederverwenden. Möglicherweise möchten Sie die Spaltendokumentation wiederverwenden, wenn Sie in Ihrem SQL-Workflow mehrere Spalten mit demselben Namen und derselben Beschreibung haben.

Sie können eine Konstante mit der Beschreibung einer einzelnen Spalte oder eine Konstante mit einem Satz oder einer Spaltenbeschreibung definieren, um Beschreibungen aller Spalten in einer Tabelle wiederzuverwenden. Weitere Informationen zum Erstellen und Verwenden von Einfügungen in Dataform finden Sie unter Variablen und Funktionen mit Einfügungen in Dataform 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-Tabellendefinitionsdatei definitions/my_table.sqlx verwendet werden, um eine 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
};

Das folgende Codebeispiel zeigt die in includes/table_docs.js definierte Konstante columns, die in der SQLX-Tabellendefinitionsdatei definitions/my_table.sqlx verwendet wird, um eine 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