Crear tablas

En Dataform, una tabla es uno de los tipos de objetos que componen un flujo de trabajo. Puede crear tablas que hagan referencia a datos de las fuentes de datos declaradas en su flujo de trabajo o de otras tablas del mismo. Dataform compila las definiciones de tus tablas en SQL en tiempo real. Cuando activas la ejecución, Dataform ejecuta el código SQL y crea las tablas que has definido en BigQuery.

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

También puedes definir particiones y clústeres de tablas.

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

Para probar los datos de una tabla con respecto a condiciones específicas, puede crear consultas de prueba de calidad de los datos llamadas afirmaciones. Dataform ejecuta aserciones cada vez que actualiza tu flujo de trabajo y te avisa si falla alguna.

Para anular el esquema, la base de datos y el nombre predeterminados de una tabla seleccionada, puede anular la configuración de la tabla.

Para inhabilitar la creación de tablas o ejecutar una instrucción SQL antes o después de crear una tabla, puedes configurar acciones adicionales.

Para organizar las tablas en BigQuery después de ejecutarlas, puedes añadir etiquetas de BigQuery. Para obtener más información, consulta el artículo Introducción a las etiquetas.

Para restringir el acceso a los datos a nivel de columna de la tabla, puede añadir etiquetas de política 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 type: "table" SQLX, puedes crear tablas vacías definiendo una consulta de SQL personalizada en un archivo type: "operations" SQLX. Puede que quieras crear una tabla vacía para que otro servicio pueda rellenarla con datos.

Antes de empezar

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

    Ir a Dataform

  2. Crea e inicializa un espacio de trabajo de desarrollo en tu repositorio.

  3. Opcional: declarar una fuente de datos.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Editor de Dataform (roles/dataform.editor) en los espacios de trabajo. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Crear una tabla

En esta sección se explica cómo crear tablas con Dataform Core en Dataform.

Acerca de las definiciones de tabla

Para definir una tabla, debes definir el tipo de tabla y escribir una instrucción SELECT en un archivo type: "table" SQLX. A continuación, Dataform compila el código principal de Dataform en SQL, ejecuta el código SQL y crea las tablas definidas en BigQuery.

En una instrucción SELECT de Dataform Core, se define la estructura de la tabla y se hace referencia a otros objetos del flujo de trabajo.

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

Hacer referencia a dependencias con ref

Para hacer referencia a una acción de flujo de trabajo en una instrucción SELECT y añadirla automáticamente como dependencia, usa la función ref. Dataform ejecuta las dependencias antes de las tablas que dependen de ellas para verificar el orden correcto de la canalización.

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

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

Después de compilar, Dataform añade instrucciones de relleno a la instrucción SQL, como CREATE, REPLACE, INSERT o MERGE.

En el siguiente código de ejemplo se muestra una definición de tabla con 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, debes proporcionar el nombre de la tabla o de la declaración de la fuente de datos de la que quieras depender. Normalmente, se trata del nombre del archivo SQLX en el que se define esa tabla o declaración de 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, consulta Anular la configuración de una tabla y Hacer referencia a una tabla con un nombre anulado.

Si tienes varias tablas con el mismo nombre en esquemas diferentes, 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 el siguiente ejemplo de código se muestra la función ref con dos argumentos para especificar una tabla en un esquema concreto:

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

También puedes añadir dependencias de tablas manualmente al bloque config de tablas, aserciones, declaraciones de fuentes de datos u operaciones de SQL personalizadas que no se hagan referencia en una función ref de la instrucción SELECT. Dataform ejecuta estas dependencias antes de las tablas dependientes.

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

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

Para obtener más información sobre la gestión de dependencias en tu flujo de trabajo, consulta Definir dependencias.

Hacer referencia a otras tablas con resolve

La función resolve te permite hacer referencia a una tabla o a una declaración de fuente de datos en una instrucción SELECT, como la función ref, pero no añade la referencia como dependencia. Esto significa que el objeto al que se hace referencia mediante la función resolve no afecta a 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 de Dataform Core.

Crear un archivo SQLX para una definición de tabla

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

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

    Ir a Dataform

  2. Para abrir un repositorio, haz clic en su nombre.

  3. Para abrir un espacio de trabajo de desarrollo, haz clic en su nombre.

  4. En el panel Archivos, junto a definitions/, haz clic en Más.

  5. Haz clic en Crear archivo.

  6. En el campo Añadir una ruta de archivo, introduce 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.

  7. Haz clic en Crear archivo.

Definir el tipo de tabla

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

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tabla que quieras editar.

  3. En el archivo, introduce el siguiente fragmento de código:

    config { type: "TABLE_TYPE" }

    Sustituye TABLE_TYPE por uno de los siguientes tipos de tabla:

    • table
    • incremental
    • view

  4. Opcional: Para definir una vista materializada, introduce la propiedad materialized en type: "view" con el siguiente formato:

    config {
  type: "view",
  materialized: true
}

    Para obtener más información, consulta ITableConfig.

  5. Opcional: Haz clic en Formato.

Definir la estructura y las dependencias de las tablas

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

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tabla que quieras editar.
  3. Debajo del bloque config, escribe una declaración SELECT.
  4. Opcional: Haz clic en Formato.

En el siguiente código de ejemplo se muestra una definición de tabla con una instrucción 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

Añadir dependencias de tablas manualmente

Para añadir dependencias de tabla que no se mencionen en la instrucción SELECT, pero que deban ejecutarse antes de la tabla actual, sigue estos pasos:

  1. En tu espacio de trabajo de desarrollo, en el panel Archivos, expande el directorio definitions/.
  2. Selecciona el archivo SQLX de definición de tabla que quieras editar.

  3. En el bloque config de la tabla, introduce el siguiente fragmento de código:

    dependencies: [ "DEPENDENCY_TABLE", ]

    Sustituye DEPENDENCY_TABLE por el nombre de archivo de la tabla que quieras añadir como dependencia. Puedes introducir varios nombres de archivo.

  4. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestran dos tablas añadidas como dependencias de tabla manuales al bloque config de un archivo de definición de tabla:

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

Anular la configuración de la tabla

Puedes anular el esquema, la base de datos y el nombre predeterminados de una tabla seleccionada.

De forma predeterminada, una tabla sigue la configuración del esquema y de la base de datos que hayas definido en workflow_settings.yaml. El nombre de una tabla es el mismo que el del archivo SQLX de definición de la tabla.

Para anular el esquema y el nombre de una tabla seleccionada, sigue estos pasos:

  1. Ve a tu espacio de desarrollo.

  2. En el panel Archivos, despliega definitions/.

  3. Abre un archivo de definición de tabla SQLX.

  4. En el bloque config, introduce el siguiente fragmento de código:

     {
   schema: "OVERRIDDEN_SCHEMA",
   database: "OVERRIDDEN_DATABASE",
   name: "OVERRIDDEN_NAME"
 }

    Haz los cambios siguientes:

    • OVERRIDDEN_SCHEMA: el conjunto de datos de BigQuery en el que quieres crear la tabla.

    • OVERRIDDEN_DATABASE: el ID del proyecto de BigQuery en el que quieres crear la tabla.

    • OVERRIDDEN_NAME: el nombre de la tabla, que es diferente del nombre de archivo de definición de la tabla SQLX.

  5. Opcional: Haz clic en Formato.

Para obtener más información, consulta Hacer referencia a una tabla con un nombre de tabla sustituido.

Crear 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 agrupaciones en clústeres de tablas. Para obtener más información, consulta los artículos Introducción a las tablas con particiones y Crear y usar tablas agrupadas en clústeres.

Crear una partición de tabla

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

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Abre un archivo SQLX de definición de tabla.

  4. En el bloque config, añade el bloque bigquery debajo de la declaración del tipo de tabla con el siguiente formato:

    config {
  type: "table",
  bigquery: {
  }
}

  5. En el bloque bigquery, introduce el siguiente fragmento de código:

        partitionBy: "PARTITION_EXPRESSION"

    Sustituye PARTITION_EXPRESSION por una expresión para particionar la tabla.

  6. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestra cómo particionar una tabla por horas en un archivo SQLX de definición de tabla:

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

En el siguiente ejemplo de código se muestra cómo particionar una tabla por un valor entero en un archivo SQLX de definición de tabla:

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

Definir un filtro de partición

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

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Abre un archivo SQLX de definición de tabla particionada.

  4. En el bloque bigquery, introduce el siguiente fragmento de código:

    requirePartitionFilter : true

  5. Opcional: Haz clic en Formato.

En el siguiente código de ejemplo se muestra un filtro de partición definido en el bloque bigquery de un archivo SQLX de una 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 de BigQuery, consulta Definir el atributo de filtro de partición obligatorio en una tabla con particiones.

Definir un periodo de conservación para las particiones

Para controlar la conservación de todas las particiones de una tabla con particiones, sigue estos pasos:

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Abre un archivo SQLX de definición de tabla particionada.

  4. En el bloque bigquery, introduce el siguiente fragmento de código:

    partitionExpirationDays: NUMBER_OF_DAYS

    Sustituye NUMBER_OF_DAYS por el número de días que quieras conservar las particiones.

  5. Opcional: Haz clic en Formato.

En el siguiente código de ejemplo se muestra un periodo de conservación de las particiones de 14 días en el bloque bigquery de un archivo SQLX de una tabla particionada:

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

Crear un clúster de tablas

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

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Abre un archivo SQLX de definición de tabla.

  4. En el bloque bigquery, introduce el siguiente fragmento de código:

        clusterBy: ["CLUSTER_COLUMN"]

    Sustituye CLUSTER_COLUMN por el nombre de la columna por la que quieras agrupar la tabla. Para obtener más información, consulta clustering_column_list.

  5. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestra una tabla con particiones agrupada en clústeres por las columnas name y revenue:

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

Configurar una tabla incremental

En esta sección se explica cómo usar Dataform Core para configurar una tabla incremental.

Acerca de las tablas incrementales

Dataform actualiza las tablas de forma diferente en función del tipo de tabla. Durante cada ejecución de una tabla o una vista, Dataform vuelve a crear la tabla o la vista completa desde cero.

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

Dataform solo inserta filas nuevas en las columnas que ya existen en la tabla incremental. Si modifica la definición de la tabla incremental (por ejemplo, añadiendo una columna), debe volver a crear la tabla desde cero. Para ello, la próxima vez que inicies una ejecución de la tabla, selecciona la opción Ejecutar con actualización completa.

Estos son algunos casos prácticos habituales de las tablas incrementales:

Optimización del rendimiento
En el caso de algunos tipos de datos, como los registros web o los datos analíticos, puede que solo quiera procesar 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 de forma rápida pero frecuente, lo que reduce la latencia de las tablas de salida.
Instantáneas diarias
Puede configurar una tabla incremental para crear instantáneas diarias de los datos de la tabla. Por ejemplo, puede usarla para hacer un análisis longitudinal de los ajustes de los usuarios almacenados en una base de datos de producción.

Procesar un subconjunto de filas de una tabla incremental

Para determinar un subconjunto de filas que Dataform debe procesar durante cada ejecución, añade una cláusula WHERE condicional al archivo de definición SQLX de la tabla incremental. En la cláusula WHERE, puede 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:

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Abre un archivo SQLX de definición de tabla incremental.

  4. Introduce una cláusula WHERE con el siguiente formato:

    config { type: "incremental" }

SELECT_STATEMENT

${when(incremental(), `WHERE INCREMENTAL_CONDITION`, `WHERE NON_INCREMENTAL_CONDITION`) }

    Haz los cambios siguientes:

    • SELECT_STATEMENT: la instrucción SELECT que define tu tabla.
    • INCREMENTAL_CONDITION: la condición que especifiques en la cláusula WHERE para seleccionar las filas que Dataform debe procesar durante la ejecución de la tabla sin que se realice una actualización completa.
    • NON_INCREMENTAL_CONDITION: la condición que especifiques en la cláusula WHERE para seleccionar las filas que Dataform debe procesar durante la ejecución de la tabla con una actualización completa.

  5. Opcional: Haz clic en Formato.

En el siguiente código de ejemplo 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 el siguiente ejemplo 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()})`) }

Combinar filas en una tabla incremental

Para verificar que una tabla incremental contiene solo una fila correspondiente a una combinación de columnas seleccionada, defina las columnas seleccionadas como uniqueKey para combinar las filas que tengan el mismo valor de uniqueKey. Al actualizar la tabla, Dataform combina las filas que tienen el mismo valor de uniqueKey en lugar de añadirlas.

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

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Selecciona un archivo SQLX de definición de tabla incremental

  4. En el bloque config, define las columnas seleccionadas como uniqueKey con el siguiente formato:

    uniqueKey: ["COLUMN_NAME"]

    Sustituye COLUMN_NAME por el nombre de una columna seleccionada.

  5. Opcional: Haz clic en Formato.

En el siguiente código de ejemplo se muestra una tabla incremental con la columna transaction_id definida como uniqueKey para verificar que siempre contiene una fila:

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

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

Filtrar filas en una tabla incremental

En una tabla con particiones incrementales, para evitar que Dataform analice toda la tabla en busca de filas coincidentes, defina updatePartitionFilter para que solo tenga en cuenta un subconjunto de registros.

En el siguiente ejemplo de código se muestra una tabla particionada incremental con la combinación configurada mediante 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()})`) }

Evitar análisis completos de tablas al ingerir datos de una tabla con particiones

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

Puedes limitar el número 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 secuencias de comandos de BigQuery para declarar el valor como una variable en el bloque pre_operations. A continuación, utilice la variable como expresión constante en una cláusula WHERE de la consulta SELECT.

Con esta configuración, Dataform actualiza la tabla incremental en función de las particiones más recientes de la tabla con particiones 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 la tabla, sigue estos pasos:

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Selecciona un archivo SQLX de definición de tabla incremental
  4. En el bloque pre_operations, declara una variable con secuencias de comandos de BigQuery.
  5. Filtra la instrucción SELECT que define la tabla con una cláusula WHERE que hace referencia a la variable declarada.
  6. 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 el ejemplo de código anterior, la variable event_timestamp_checkpoint se define en el bloque pre_operations. La variable event_timestamp_checkpoint se usa como expresión constante en la cláusula WHERE.

Reconstruir una tabla incremental desde cero con una actualización completa

Puedes forzar la reconstrucción de una tabla incremental desde cero mediante la interfaz de línea de comandos con la opción --full-refresh o la opción Ejecutar con actualización completa al activar la ejecución de un flujo de trabajo.

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

Proteger una tabla incremental de una actualización completa

Para evitar que una tabla incremental se vuelva a compilar desde cero y que se pierdan datos, puedes definirla como protected. Si tu fuente de datos es temporal, puede que quieras evitar que se vuelva a compilar una tabla incremental.

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

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Selecciona un archivo SQLX de definición de tabla incremental.
  4. En el bloque config, introduce protected: true.
  5. Opcional: Haz clic en Formato.

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

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

Añadir documentación de la tabla

En esta sección se explica cómo añadir descripciones de una tabla, sus columnas y sus registros a un archivo SQLX de Dataform Core.

Puede añadir descripciones de tablas, columnas y registros a todos los tipos de tablas de Dataform: tablas, tablas incrementales y vistas.

Te recomendamos que documentes lo siguiente:

  • El objetivo 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 puede ser útil si varios miembros del equipo trabajan en un flujo de trabajo.

Añadir una descripción de la tabla

Para añadir una descripción a una tabla de un archivo SQLX, sigue estos pasos:

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

    Ir a Dataform

  2. Selecciona un repositorio.

  3. Selecciona un espacio de trabajo de desarrollo.

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

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

    description: "Description of the table",

  6. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestra una descripción de tabla añadida al bloque config de un archivo de definición de tabla SQLX:

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

Añadir descripciones de columnas y registros

Para añadir descripciones de columnas y registros concretos a un archivo SQLX, siga estos pasos:

  1. En el bloque config del archivo de definición de la tabla, introduce columns: {}.

  2. En columns: {}, introduzca las descripciones de las columnas con el siguiente formato:

    column_name: "Description of the column",

  3. En columns: {}, introduce 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 el siguiente ejemplo de código se muestran las descripciones de la tabla, la columna y el registro en el bloque config de un archivo de definición de tabla 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

Reutilizar la documentación de columnas con includes

Puedes reutilizar las descripciones de las columnas de Dataform en todo tu flujo de trabajo de SQL con las inclusiones de JavaScript. Puede que quieras reutilizar la documentación de las columnas si tienes varias columnas con el mismo nombre y la misma 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 includes en Dataform, consulta el artículo Reutilizar código en un mismo repositorio con includes.

En el siguiente código de ejemplo se muestran 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 el siguiente ejemplo 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 definitions/my_table.sqlx SQLX para generar documentación de 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 el siguiente ejemplo 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 el siguiente ejemplo 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 definitions/my_table.sqlx SQLX para generar documentación de todas las columnas de la tabla:

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

SELECT 1 AS one

Añadir etiquetas de BigQuery

En esta sección se explica cómo añadir etiquetas a las tablas de Dataform.

BigQuery permite añadir etiquetas a los recursos. Para obtener más información sobre las etiquetas de BigQuery, consulta el artículo Introducción a las etiquetas.

Para añadir una etiqueta de BigQuery a una tabla de Dataform, añade la etiqueta al bloque bigquery del bloque config del archivo SQLX de definición de la tabla.

Para añadir una etiqueta de BigQuery a un archivo de definición de tabla, sigue estos pasos:

  1. Ve a tu espacio de desarrollo.
  2. En el panel Archivos, despliega definitions/.
  3. Selecciona un archivo de definición de tabla SQLX.

  4. En el bloque config, añade una etiqueta con el siguiente formato:

    bigquery: {
    labels: {
      LABEL1: "VALUE_OF_LABEL1"
    }
  }

    Haz los cambios siguientes:

    • LABEL1: el nombre de tu sello
    • VALUE_OF_LABEL1: el valor de la etiqueta

  5. Opcional: Para añadir una etiqueta con un nombre que contenga caracteres especiales, escribe el nombre entre comillas ("").

  6. Opcional: Haz clic en Formato.

En el siguiente ejemplo de código se muestran las etiquetas department:shipping y cost-center:logistics añadidas al bloque bigquery en un archivo SQLX de definición de tabla particionada:

config {
  type: "table",
  bigquery: {
    partitionBy: "DATE(ts)",
    labels: {
      department: "shipping",
      "cost-center": "logistics"
    }
  }
}

SELECT CURRENT_TIMESTAMP() AS ts

Siguientes pasos