Agregar documentación de tablas

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 documentar lo siguiente :

  • El propósito de la tabla.
  • El contenido o la función de las columnas o los registros en la tabla.
  • Relación de la tabla y otros objetos de tu flujo de trabajo de SQL, por ejemplo, las tablas o vistas que dependen de la tabla actual
  • Son las aserciones que se aplican a la tabla.
  • Operaciones previas o posteriores aplicadas a la tabla.
  • 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.

Funciones obligatorias

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

Es posible que también puedas obtener los permisos necesarios mediante funciones personalizadas, o bien otras funciones predefinidas.

Agrega una descripción a 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.

    Ir 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 incluye una descripción de tabla agregada al bloque config de un archivo de definición de tablas de 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. En columns: {}, ingresa descripciones de 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 descripciones de tablas, columnas y registros en el bloque config de un archivo de definición de tablas de 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

Vuelve a usar la documentación de columnas en Dataform con inclusiones

Puedes volver a usar la descripción de columnas en tu flujo de trabajo de SQL con JavaScript. Es posible que desees volver a usar la documentación de columnas si tienes varias columnas con el mismo nombre y descripción en tu flujo de trabajo de SQL.

Puedes definir una constante con la descripción de una sola columna o una constante con un conjunto o una descripción de columna para reutilizar 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 Reutiliza variables y funciones con inclusiones en Dataform.

En la siguiente muestra de código, verás varias constantes con descripciones de columnas individuales definidas en el archivo 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 incluyen las constantes user_id y age, definidas en includes/docs.js, que se usan en el archivo de definición de tablas de SQLX definitions/my_table.sqlx para generar documentación para las columnas seleccionadas de 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 observa 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 indica la constante columns, definida en includes/table_docs.js, que se usa en el archivo de definición de tablas de 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?