Se usó la API de Cloud Translation para traducir esta página.

Crear tablas

En Dataform, una tabla es uno de los tipos de objetos que conforman un flujo de trabajo. Puedes crear tablas que hagan referencia a datos de las fuentes de datos declaradas para tu flujo de trabajo o de otras tablas de tu flujo de trabajo. Dataform compila tus definiciones de tablas en SQL en tiempo real. Cuando activas la ejecución, Dataform ejecuta el código SQL y crea las tablas definidas en BigQuery.

Puedes crear los siguientes tipos de tablas en un archivo SQLX type: "table":

table: Una tabla normal.
incremental: Una tabla incremental.
view: Una vista de tabla. Para obtener más información, consulta Introducción a las vistas.
- materialized: Una vista de tabla materializada. Para obtener más información, consulta Introducción a las vistas materializadas.

También puedes definir las particiones y los clústeres de la tabla.

Para llevar un registro del propósito de una tabla o su relación con otras tablas en tu flujo de trabajo, puedes agregar documentación a la tabla o a sus columnas seleccionadas.

Para probar los datos de una tabla en condiciones específicas, puedes crear consultas de prueba de calidad de datos llamadas aserciones. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo y te alerta si alguna falla.

Para anular la configuración predeterminada de la tabla, como database o schema, y, luego, inhabilitar la creación de la tabla, o bien ejecutar una instrucción de SQL antes o después de su creación, puedes configurar parámetros adicionales de la tabla.

Puedes configurar parámetros adicionales de la tabla para hacer lo siguiente:

Anula la configuración predeterminada de la tabla, como database o schema.
Inhabilita la creación de tablas.
Ejecuta una sentencia SQL antes o después de la creación de la tabla.

Para organizar tus tablas en BigQuery después de ejecutarlas, puedes agregar etiquetas de BigQuery. Para obtener más información, consulta Introducción a las etiquetas.

Para restringir el acceso a los datos a nivel de la columna de la tabla, puedes agregar etiquetas de políticas de BigQuery. Para obtener más información, consulta Introducción al control de acceso a nivel de columna.

Además de definir tablas en un archivo SQLX type: "table", puedes crear tablas vacías si defines una consulta de SQL personalizada en un archivo SQLX type: "operations". Te recomendamos que crees una tabla vacía para que un servicio diferente pueda propagarla con datos.

Antes de comenzar

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

Ir a Dataform
Crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.
Opcional: Declara una fuente de datos.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue el rol de IAM de editor de Dataform (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.

Crea una tabla

En esta sección, se muestra cómo crear tablas con el núcleo de Dataform en Dataform.

Acerca de las definiciones de tablas

Para definir una tabla, debes definir el tipo de tabla y escribir una sentencia SELECT en un archivo SQLX type: "table". Luego, Dataform compila tu código principal de Dataform en SQL, ejecuta el código SQL y crea tus tablas definidas en BigQuery.

En una sentencia SELECT principal de Dataform, defines la estructura de la tabla y haces referencia a otros objetos de tu flujo de trabajo.

Además de definir tablas en un archivo type: "table" SLQX, puedes crear tablas vacías si defines una consulta de SQL personalizada en un archivo SQLX type: "operations". Para obtener más información, consulta Crea una tabla vacía.

Cómo hacer referencia a dependencias con `ref`

Para hacer referencia a un objeto de flujo de trabajo en una sentencia SELECT y agregarlo automáticamente como una dependencia, usa la función ref. Dataform ejecuta las dependencias antes que las tablas que dependen de ellas para garantizar el orden correcto de la canalización.

La función ref es una función principal integrada de Dataform que es fundamental para la administración de dependencias en Dataform. La función ref te permite hacer referencia a los siguientes objetos definidos en tu flujo de trabajo de Dataform y depender automáticamente de ellos, en lugar de codificar de forma fija los nombres de esquema y tabla:

Tablas de todos los tipos de tablas compatibles.
Declaraciones de fuentes de datos.
Operaciones de SQL personalizadas con la propiedad hasOutput establecida en true

Dataform usa la función ref para compilar un árbol de dependencias de todas las tablas que se crearán o actualizarán.

Después de la compilación, Dataform agrega instrucciones de texto modelo a la instrucción SQL, como CREATE, REPLACE, INSERT o MERGE.

En la siguiente muestra de código, se muestra una definición de tabla con el uso de la función ref:

config { type: "table" }

SELECT
  order_date AS date,
  order_id AS order_id,
  order_status AS order_status,
  SUM(item_count) AS item_count,
  SUM(amount) AS revenue

FROM ${ref("store_clean")}

GROUP BY 1, 2

En la función ref, proporcionas el nombre de la declaración de la tabla o fuente de datos de la que deseas depender. Por lo general, es el nombre del archivo SQLX en el que se define esa declaración de tabla o fuente de datos.

Si se anula el nombre de una tabla, usa el nombre anulado en la función ref. Por ejemplo, haz referencia a una tabla con config { name: "overridden_name" } como ref("overridden_name"). Para obtener más información sobre cómo anular los nombres de las tablas, consulta Configura parámetros adicionales de las tablas.

Cuando tienes varias tablas con el mismo nombre en diferentes esquemas, puedes hacer referencia a una tabla específica proporcionando dos argumentos a la función ref: el nombre del esquema y el nombre de la tabla.

En la siguiente muestra de código, se muestra la función ref con dos argumentos para especificar una tabla dentro de un esquema específico:

config { type: "table" }
SELECT * FROM ${ref("schema", "store_clean")}

También puedes agregar dependencias de tablas de forma manual al bloque config para tablas, aserciones, declaraciones de fuentes de datos o operaciones SQL personalizadas a las que no se hace referencia en una función ref en la sentencia SELECT. Dataform ejecuta estas dependencias antes que las tablas dependientes.

En la siguiente muestra de código, se muestra una dependencia de tabla en el bloque config:

config { dependencies: [ "unreferenced_table" ] }
SELECT * FROM ...

Para obtener más información sobre la administración de dependencias en tu flujo de trabajo, consulta Cómo declarar dependencias.

Cómo hacer referencia a otras tablas con `resolve`

La función resolve te permite hacer referencia a una declaración de tabla o fuente de datos en una sentencia SELECT como la función ref, pero no agrega la referencia como dependencia. Esto significa que el objeto al que se hace referencia con la función resolve no afecta la ejecución de la tabla que usa la función resolve.

Para obtener más información sobre las funciones principales integradas de Dataform, consulta la referencia principal de Dataform.

Crea un archivo SQLX para una definición de tabla

Almacena los archivos SQLX de definición de tablas en el directorio definitions/. Para crear un archivo SQLX nuevo en el directorio definitions/, sigue estos pasos:

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

Ir a Dataform
Para abrir un repositorio, haz clic en su nombre.
Para abrir un lugar de trabajo de desarrollo, haz clic en su nombre.
En el panel Archivos, junto a definitions/, haz clic en Más.
Haz clic en Crear archivo.
En el campo Agregar una ruta de archivo, ingresa el nombre del archivo seguido de .sqlx después de definitions/. Por ejemplo, definitions/my-table.sqlx.

Los nombres de archivo solo pueden incluir números, letras, guiones y guiones bajos.
Haz clic en Crear archivo.

Define el tipo de tabla

Para crear una nueva definición de tipo de tabla, sigue estos pasos:

En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio definitions/.
Selecciona el archivo SQLX de definición de tablas que deseas editar.
En el archivo, ingresa el siguiente fragmento de código:
```
config { type: "TABLE_TYPE" }
```
Reemplaza TABLE_TYPE por uno de los siguientes tipos de tablas:
- table
- incremental
- view
Opcional: Para definir una vista materializada, ingresa la propiedad materialized en type: "view" con el siguiente formato:
```
config {
  type: "view",
  materialized: true
}
```
Para obtener más información, consulta ITableConfig.
Opcional: Haz clic en Formato.

Define la estructura y las dependencias de la tabla

Para escribir una sentencia SELECT de definición de tabla y definir la estructura y las dependencias de la tabla, sigue estos pasos:

En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio definitions/.
Selecciona el archivo SQLX de definición de tablas que deseas editar.
Debajo del bloque config, escribe una sentencia SELECT.
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra una definición de tabla con una sentencia SELECT y la función ref:

config { type: "table" }
SELECT
  customers.id AS id,
  customers.first_name AS first_name,
  customers.last_name AS last_name,
  customers.email AS email,
  customers.country AS country,
  COUNT(orders.id) AS order_count,
  SUM(orders.amount) AS total_spent
FROM
  dataform-samples.dataform_sample.crm_customers AS customers
  LEFT JOIN ${ref('order_stats')} orders
    ON customers.id = orders.customer_id

WHERE
  customers.id IS NOT NULL
  AND customers.first_name <> 'Internal account'
  AND country IN ('UK', 'US', 'FR', 'ES', 'NG', 'JP')

GROUP BY 1, 2, 3, 4, 5

Cómo agregar dependencias de tablas manuales

Para agregar dependencias de tablas a las que no se hace referencia en la sentencia SELECT, pero que deben ejecutarse antes de la tabla actual, sigue estos pasos:

En el panel Files de tu espacio de trabajo de desarrollo, expande el directorio definitions/.
Selecciona el archivo SQLX de definición de tablas que deseas editar.
En el bloque config de la tabla, ingresa el siguiente fragmento de código:
```
dependencies: [ "DEPENDENCY_TABLE", ]
```
Reemplaza DEPENDENCY_TABLE por el nombre de archivo de la tabla que deseas agregar como dependencia. Puedes ingresar varios nombres de archivo.
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestran dos tablas agregadas como dependencias de tablas manuales al bloque config de un archivo de definición de tablas:

config { dependencies: [ "some_table", "some_other_table" ] }

Crea particiones y clústeres de tablas

En esta sección, se muestra cómo usar Dataform core para crear particiones y clústeres de tablas. BigQuery admite tablas particionadas y el agrupamiento en clústeres de tablas. Para obtener más información, consulta Introducción a las tablas particionadas y Crea y usa tablas agrupadas en clústeres.

Crea una partición de tabla

Para crear una partición de tabla, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Abre un archivo SQLX de definición de tablas.
En el bloque config, agrega el bloque bigquery debajo de la declaración de tipo de tabla en el siguiente formato:
```
config {
  type: "table",
  bigquery: {
  }
}
```
En el bloque bigquery, ingresa el siguiente fragmento de código:
```
    partitionBy: "PARTITION_EXPRESSION"
```
Reemplaza PARTITION_EXPRESSION por una expresión para particionar la tabla.
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra cómo particionar una tabla por hora en un archivo SQLX de definición de tablas:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATETIME_TRUNC(<timestamp_column>, HOUR)"
  }
}

En la siguiente muestra de código, se muestra cómo particionar una tabla por un valor de número entero en un archivo SQLX de definición de tablas:

config {
  type: "table",
  bigquery: {
    partitionBy: "RANGE_BUCKET(<integer_column>, GENERATE_ARRAY(0, 1000000, 1000))"
  }
}

Cómo establecer un filtro de partición

Para establecer un filtro de partición, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Abre un archivo SQLX de definición de tabla particionada.
En el bloque bigquery, ingresa el siguiente fragmento de código:
```
requirePartitionFilter : true
```
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra un filtro de partición establecido en el bloque bigquery de un archivo SQLX de tabla particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    requirePartitionFilter : true
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Para obtener más información sobre el filtro de partición en BigQuery, consulta Cómo configurar el atributo de filtro de partición requerido en una tabla particionada.

Cómo establecer un período de retención para las particiones

Para controlar la retención de todas las particiones en una tabla particionada, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Abre un archivo SQLX de definición de tabla particionada.
En el bloque bigquery, ingresa el siguiente fragmento de código:
```
partitionExpirationDays: NUMBER_OF_DAYS
```
Reemplaza NUMBER_OF_DAYS por la cantidad de días durante los que deseas retener las particiones.
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra un período de retención para las particiones establecido en 14 días en el bloque bigquery de un archivo SQLX de tabla particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    partitionExpirationDays: 14,
  }
}
SELECT CURRENT_TIMESTAMP() AS ts

Crea un clúster de tablas

Para crear un clúster de tablas, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Abre un archivo SQLX de definición de tablas.
En el bloque bigquery, ingresa el siguiente fragmento de código:
```
    clusterBy: ["CLUSTER_COLUMN"]
```
Reemplaza CLUSTER_COLUMN por el nombre de la columna por la que deseas agrupar la tabla. Para obtener más información, consulta clustering_column_list.
Opcional: Haz clic en Formato.

En el siguiente ejemplo de código, se muestra una tabla particionada agrupada por columnas name y revenue:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    clusterBy: ["name", "revenue"]
  }
}
SELECT CURRENT_TIMESTAMP() as ts, name, revenue

Configura una tabla incremental

En esta sección, se muestra cómo usar el núcleo de Dataform para configurar una tabla incremental.

Acerca de las tablas incrementales

Dataform actualiza las tablas de manera diferente según el tipo de tabla. Durante cada ejecución de una tabla o vista, Dataform vuelve a compilar toda la tabla o vista desde cero.

Cuando defines una tabla incremental, Dataform la compila desde cero solo por primera vez. Durante las ejecuciones posteriores, Dataform solo inserta o combina filas nuevas en la tabla incremental según las condiciones que configures.

Dataform inserta filas nuevas solo en las columnas que ya existen en la tabla incremental. Si realizas cambios en la consulta de definición de tabla incremental (por ejemplo, si agregas una columna nueva), debes volver a compilar la tabla desde cero. Para ello, la próxima vez que actives una ejecución de la tabla, selecciona la opción Run with full refresh.

Estos son algunos casos de uso comunes de las tablas incrementales:

Optimización del rendimiento: Para algunos tipos de datos, como los registros web o los datos de estadísticas, es posible que desees procesar solo los registros nuevos en lugar de volver a procesar toda la tabla.
Reducción de la latencia: Puedes usar tablas incrementales para ejecutar flujos de trabajo con rapidez, pero con frecuencia, lo que reduce la latencia descendente de las tablas de resultados.
Instantáneas diarias: Puedes configurar una tabla incremental para crear instantáneas diarias de los datos de la tabla, por ejemplo, para el análisis longitudinal de la configuración del usuario almacenada en una base de datos de producción.

Cómo procesar un subconjunto de filas en una tabla incremental

Para determinar un subconjunto de filas que Dataform procesará durante cada ejecución, agrega una cláusula WHERE condicional al archivo de definición SQLX de la tabla incremental. En la cláusula WHERE, puedes especificar una condición incremental y una condición no incremental. Dataform aplica la condición incremental durante la ejecución de la tabla sin una actualización completa y la condición no incremental durante la ejecución con una actualización completa.

Para configurar una tabla incremental, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Abre un archivo SQLX de definición de tablas incremental.
Ingresa una cláusula WHERE con el siguiente formato:
```
config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }
```
Reemplaza lo siguiente:
- SELECT_STATEMENT: La sentencia SELECT que define tu tabla.
- INCREMENTAL_CONDITION: Es la condición que especificas en la cláusula WHERE para seleccionar filas que Dataform procesará durante la ejecución de la tabla sin una actualización completa.
- NON_INCREMENTAL_CONDITION: Es la condición que especificas en la cláusula WHERE para seleccionar filas que Dataform procesará durante la ejecución de la tabla con una actualización completa.
Opcional: Haz clic en Formato.

En la siguiente muestra de código, se muestra una tabla incremental que procesa de forma incremental las filas de la tabla productiondb.logs:

config { type: "incremental" }

SELECT timestamp, message FROM ${ref("productiondb", "logs")}

${when(incremental(),
   `WHERE date > (SELECT MAX(date) FROM ${self()}) AND country = "UK"`,
   `WHERE country = "UK"`)}

En la siguiente muestra de código, se muestra una tabla incremental que crea una instantánea de la tabla productiondb.customers:

config { type: "incremental" }

SELECT CURRENT_DATE() AS snapshot_date, customer_id, name, account_settings FROM ${ref("productiondb", "customers")}

${when(incremental(), `WHERE snapshot_date > (SELECT MAX(snapshot_date) FROM ${self()})`) }

Cómo combinar filas en una tabla incremental

Para garantizar que una tabla incremental contenga solo una fila que corresponda a una combinación de columnas seleccionada, establece las columnas seleccionadas como uniqueKey para combinar las filas que tengan el mismo valor de uniqueKey. Cuando se actualiza la tabla, Dataform combina las filas con el mismo valor uniqueKey en lugar de agregarlas.

Para configurar la combinación en una tabla incremental, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Selecciona un archivo SQLX de definición de tabla incremental
En el bloque config, establece las columnas seleccionadas como uniqueKey en el siguiente formato:
```
uniqueKey: ["COLUMN_NAME"]
```
Reemplaza COLUMN_NAME por el nombre de una columna seleccionada.
Opcional: Haz clic en Formato.

En el siguiente ejemplo de código, se muestra una tabla incremental con la columna transaction_id configurada como uniqueKey para garantizar que siempre contenga una fila:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"]
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Cómo filtrar filas en una tabla incremental

En una tabla particionada incremental, para evitar que Dataform analice toda la tabla para encontrar filas coincidentes, establece updatePartitionFilter para que solo considere un subconjunto de registros.

En el siguiente ejemplo de código, se muestra una tabla particionada incremental con la combinación configurada mediante la configuración de las propiedades uniqueKey y updatePartitionFilter:

config {
  type: "incremental",
  uniqueKey: ["transaction_id"],
  bigquery: {
    partitionBy: "DATE(timestamp)",
    updatePartitionFilter:
        "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"
  }
}

SELECT timestamp, action FROM weblogs.user_actions
${ when(incremental(), `WHERE timestamp > (SELECT MAX(timestamp) FROM ${self()})`) }

Evita los análisis completos de tablas cuando transfieres datos desde una tabla particionada

Cuando creas una tabla incremental que hace referencia a una tabla particionada, te recomendamos que crees tu consulta de tabla para evitar análisis completos de la tabla particionada durante cada actualización incremental.

Puedes limitar la cantidad de particiones que analiza BigQuery para actualizar la tabla incremental usando una expresión constante en la consulta de la tabla. Para convertir un valor de la tabla particionada en una expresión constante, usa la escritura de secuencias de comandos de BigQuery para declarar el valor como una variable en el bloque pre_operations. Luego, usa la variable como una expresión constante en una cláusula WHERE en la consulta SELECT.

Con esta configuración, Dataform actualiza la tabla incremental según las particiones más recientes de la tabla particionada a la que se hace referencia, sin analizar toda la tabla.

Para configurar una tabla incremental que haga referencia a una tabla particionada y evite los análisis completos de tablas, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Selecciona un archivo SQLX de definición de tabla incremental
En el bloque pre_operations, declara una variable con la escritura de secuencias de comandos de BigQuery.
Filtra la sentencia SELECT que define la tabla con una cláusula WHERE que hace referencia a la variable declarada.
Opcional: Haz clic en Formato.

En el siguiente ejemplo de código, se muestra una tabla incremental en la que la tabla raw_events a la que se hace referencia se particiona por event_timestamp:

config {
  type: "incremental",
}

pre_operations {
  DECLARE event_timestamp_checkpoint DEFAULT (
    ${when(incremental(),
    `SELECT max(event_timestamp) FROM ${self()}`,
    `SELECT timestamp("2000-01-01")`)}
  )
}

SELECT
  *
FROM
  ${ref("raw_events")}
WHERE event_timestamp > event_timestamp_checkpoint

En la muestra de código anterior, la variable event_timestamp_checkpoint se define en el bloque pre_operations. Luego, la variable event_timestamp_checkpoint se usa como una expresión constante en la cláusula WHERE.

Cómo volver a compilar una tabla incremental desde cero con una actualización completa

Puedes forzar que una tabla incremental se vuelva a compilar desde cero con la interfaz de línea de comandos con la opción --full-refresh o la opción Run with full refresh cuando activas una ejecución de flujo de trabajo.

Cuando seleccionas la opción de actualización completa, en tu lugar de trabajo de desarrollo o con Dataform CLI, Dataform ignora el parámetro ${when(incremental(), ... } durante la ejecución y vuelve a crear la tabla con una sentencia CREATE OR REPLACE.

Protege una tabla incremental de la actualización completa

Para proteger una tabla incremental de la reconstrucción desde cero y la posible pérdida de datos, puedes configurarla como protected. Es posible que desees evitar que se vuelva a compilar una tabla incremental si tu fuente de datos es temporal.

Para marcar una tabla incremental como protected, sigue estos pasos:

Ve a tu lugar de trabajo de desarrollo.
En el panel Archivos, expande definitions/.
Selecciona un archivo SQLX de definición de tabla incremental.
En el bloque config, ingresa protected: true.
Opcional: Haz clic en Formato.

En el siguiente ejemplo de código, se muestra una tabla incremental marcada como protected:

config {
  type: "incremental",
  protected: true
}
SELECT ...

Agrega documentación a la tabla

En esta sección, 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 y otras acciones de tu flujo de trabajo, por ejemplo, las tablas o vistas que dependen de la tabla actual.
Las aserciones aplicadas a la tabla
Las operaciones previas o posteriores aplicadas a la tabla
El propietario de la tabla, es decir, el usuario que la creó. Esta información podría ser útil si varios miembros del equipo trabajan en un flujo de trabajo.

Agrega una descripción de la tabla

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

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

Ir a Dataform
Selecciona un repositorio.
Selecciona un lugar de trabajo de desarrollo.
En el panel Archivos, haz clic en el archivo SQLX de definición de tablas que deseas editar.
En el bloque config del archivo, ingresa la descripción de la tabla en el siguiente formato:
```
description: "Description of the table",
```
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:

En el bloque config de tu archivo de definición de tablas, ingresa columns: {}.
Dentro de columns: {}, ingresa las descripciones de las columnas con el siguiente formato:
```
column_name: "Description of the column",
```

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"
      }
}

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 con Includes

Puedes volver a usar las descripciones de las columnas en Dataform en tu flujo de trabajo de SQL con las incorporaciones 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.

Para crear una descripción de columna reutilizable, define una constante de inclusión de JavaScript con el nombre de la columna y su descripción.

Puedes definir una constante con una descripción de una sola columna o una constante con una descripción de conjunto o 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, que se define en includes/table_docs.js y 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?

Para obtener información sobre cómo configurar parámetros adicionales de la tabla, consulta Configura parámetros adicionales de la tabla.
Para aprender a probar datos de tablas con aserciones, consulta Cómo probar tablas con aserciones.
Para aprender a definir tablas con JavaScript, consulta Crea flujos de trabajo de Dataform con JavaScript.
Para obtener información sobre cómo volver a usar código con incorporaciones, consulta Cómo volver a usar código en un solo repositorio con incorporaciones.
Para obtener información sobre cómo usar la interfaz de línea de comandos de Dataform, consulta Usa la CLI de Dataform.