Tabellendokumentation hinzufügen

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

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

In diesem Fall sollten Sie Folgendes dokumentieren :

  • Der Zweck der Tabelle.
  • Der Inhalt oder die Rolle von Spalten oder Einträgen in der Tabelle.
  • Die 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 Nachbearbeitungen, die auf die Tabelle angewendet werden.
  • Eigentümer der Tabelle, d. h. der Nutzer, der die Tabelle erstellt hat. Das kann nützlich sein, wenn mehrere Teammitglieder an einem Workflow arbeiten.

Hinweise

Erstellen Sie zuerst eine Tabelle.

Erforderliche Rollen

Damit Sie die Berechtigungen zum Dokumentieren einer Tabelle erhalten, müssen Sie Ihren Administrator bitten, Ihnen die IAM-Rolle Dataform-Bearbeiter (roles/dataform.editor) für Arbeitsbereiche zu gewähren. 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 anfordern.

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 Dataform-Seite

  2. Wählen Sie ein Repository aus.

  3. Wählen Sie einen Entwicklungsarbeitsbereich aus.

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

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

description: "Description of the table",

Das folgende Codebeispiel zeigt eine Tabellenbeschreibung, die dem config-Block einer SQLX-Tabellendefinitionsdatei 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 im Block config der Tabellendefinitionsdatei columns: {} ein.
  2. Geben Sie in columns: {} Spaltenbeschreibungen im folgenden Format ein:
column_name: "Description of the column",
  1. Geben Sie in columns: {} Datensatzbeschreibungen im folgenden Format ein:
record_name: {
      description: "Description of the record",
      columns: {
        record_column_name: "Description of the record column"
      }
}

Im folgenden Codebeispiel sehen Sie Tabellen-, Spalten- und Datensatzbeschreibungen im config-Block 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 einschließen

Sie können Beschreibungen von Spalten in Ihrem SQL-Workflow mit JavaScript-Includes wiederverwenden. Sie können Spaltendokumentationen 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 einer Satz- oder Spaltenbeschreibung definieren, um Beschreibungen aller Spalten in einer Tabelle wiederzuverwenden. Weitere Informationen zum Erstellen und Verwenden von Include in Dataform finden Sie unter Variable und Funktionen mit Dataform wiederverwenden.

Im folgenden Codebeispiel sehen Sie mehrere Konstanten mit Beschreibungen der einzelnen 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,
};

Im folgenden Codebeispiel sehen Sie die in includes/docs.js definierten Konstanten user_id und age, die in der SQL-Tabellendefinitionsdatei definitions/my_table.sqlx zum Generieren der Dokumentation für ausgewählte Spalten in der Tabelle verwendet werden:

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 Konstante columns, die in includes/table_docs.js definiert ist und in der SQL-Tabellendefinitionsdatei definitions/my_table.sqlx verwendet wird, um die 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