Configura una tabla incremental

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

Acerca de una tabla incremental

Dataform actualiza las tablas de forma 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.

El formulario de datos 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, 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 para 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.

Antes de comenzar

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

    Ve a la página Dataform

  2. Selecciona o crea un repositorio.

  3. Selecciona o crea un lugar de trabajo de desarrollo.

  4. Crea una tabla del tipo de tabla incremental.

Roles obligatorios

Para obtener los permisos que necesitas para configurar una tabla incremental, 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.

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 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 lugar de trabajo de desarrollo.
  2. En el panel Archivos, expande definitions/.
  3. Abre un archivo SQLX de definición de tablas incrementales.

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

  5. 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 asegurarte de que una tabla incremental contenga solo una fila que corresponda a una combinación seleccionada de columnas, establece las columnas seleccionadas como uniqueKey para combinar filas que tengan el mismo uniqueKey. Cuando se actualiza la tabla, Dataform combina las filas con uniqueKey en lugar de agregarlas.

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

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

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

  5. 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 con una expresión constante en tu consulta de 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 la tabla, sigue estos pasos:

  1. Ve a tu lugar de trabajo de desarrollo.
  2. En el panel Archivos, expande definitions/.
  3. Selecciona un archivo SQLX de definición de tabla incremental
  4. En el bloque pre_operations, declara una variable con la escritura de secuencias de comandos de BigQuery.
  5. Filtra la sentencia 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 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 con 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:

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

En el siguiente ejemplo de código, se muestran tablas incrementales marcadas como protected:

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

¿Qué sigue?