Agrega documentación a la tabla

En este documento, se muestra cómo agregar descripciones de una tabla y sus columnas y registros a un archivo SQLX principal de Dataform.

Puedes agregar descripciones de tablas, columnas y registros a todos los tipos de tablas en Dataform: tablas, tablas incrementales y vistas.

Te recomendamos que documentes lo siguiente :

  • El propósito de la tabla.
  • El contenido o el rol de las columnas o los registros de la tabla.
  • La relación de la tabla con otros objetos de tu flujo de trabajo de SQL, por ejemplo, las tablas o vistas que dependen de la tabla actual
  • Aserciones aplicadas a la tabla
  • Operaciones previas o posteriores aplicadas a la tabla.
  • Es el propietario de la tabla, es decir, el usuario que la creó. Esto puede ser útil si varios miembros del equipo trabajan en un flujo de trabajo.

Antes de comenzar

Antes de comenzar, crea una tabla.

Roles obligatorios

Para obtener los permisos que necesitas para documentar una tabla, pídele a tu administrador que te otorgue el rol de IAM Editor de formularios de datos (roles/dataform.editor) en los espacios de trabajo. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Agrega una descripción de la tabla

Para agregar una descripción a una tabla en un archivo SQLX, sigue estos pasos:

  1. En la consola de Cloud, ve a la página Dataform.

    Ve a la página Dataform

  2. Selecciona un repositorio.

  3. Selecciona un lugar de trabajo de desarrollo.

  4. En el panel Archivos, haz clic en el archivo SQLX de definición de tablas que deseas editar.

  5. En el bloque config del archivo, ingresa la descripción de la tabla en el siguiente formato:

    description: "Description of the table",

  6. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra una descripción de la tabla que se agregó al bloque config de un archivo de definición de tablas SQLX:

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

Agrega descripciones de columnas y registros

Para agregar descripciones de columnas y registros individuales a un archivo SQLX, sigue estos pasos:

  1. En el bloque config de tu archivo de definición de tablas, ingresa columns: {}.

  2. Dentro de columns: {}, ingresa las descripciones de las columnas con el siguiente formato:

    column_name: "Description of the column",

  3. Dentro de columns: {}, ingresa las descripciones de los registros con el siguiente formato:

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

  4. Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestran las descripciones de las tablas, las columnas y los registros en el bloque config de un archivo de definición de tablas 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

Cómo volver a usar la documentación de columnas en Dataform con Includes

Puedes volver a usar la descripción de las columnas en tu flujo de trabajo de SQL con las inclusiones de JavaScript. Te recomendamos que vuelvas a usar la documentación de las columnas si tienes varias columnas con el mismo nombre y descripción en tu flujo de trabajo de SQL.

Puedes definir una constante con una descripción de una sola columna o una constante con una descripción de un conjunto o una columna para volver a usar las descripciones de todas las columnas de una tabla. Para obtener más información sobre cómo crear y usar inclusiones en Dataform, consulta Cómo volver a usar código en un solo repositorio con inclusiones.

En la siguiente muestra de código, se muestran varias constantes con descripciones de columnas individuales definidas en el archivo de 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,
};

En la siguiente muestra de código, se muestran las constantes user_id y age, definidas en includes/docs.js, que se usan en el archivo de definición de la tabla SQLX definitions/my_table.sqlx para generar documentación para las columnas seleccionadas en la tabla:

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

En la siguiente muestra de código, se muestra una constante con un conjunto de descripciones de columnas definidas en el archivo 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
};

En la siguiente muestra de código, se muestra la constante columns, definida en includes/table_docs.js, que se usa en el archivo de definición de la tabla SQLX definitions/my_table.sqlx para generar documentación para todas las columnas de la tabla:

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

SELECT 1 AS one

¿Qué sigue?