Configura una tabla incremental

En este documento, se muestra cómo usar Dataform Core para configurar una tabla incremental.

Acerca de una tabla incremental

Dataform actualiza las tablas de manera diferente según su tipo. Durante cada ejecución de una tabla o una vista, Dataform vuelve a compilar toda la tabla o la 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 columnas que ya existen en la tabla incremental. Si realizas cambios en la consulta de definición de la tabla incremental, por ejemplo, si agregas una columna nueva, debes volver a compilar la tabla desde cero. Para hacerlo, 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 registros web o datos de estadísticas, es posible que desees procesar solo 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 y frecuencia, lo que reduce la latencia descendente de las tablas de salida.
Resúmenes diarios
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.

    Ir a la página de 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.

Funciones obligatorias

Si quieres obtener los permisos que necesitas para configurar una tabla incremental, 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 a través de funciones personalizadas o, también, otras funciones predefinidas.

Procesar un subconjunto de filas en una tabla incremental

Si quieres determinar un subconjunto de filas para que Dataform lo procese 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 Files, expande definitions/.
  3. Abre un archivo SQLX de definición de tabla incremental.

  4. Ingresa una cláusula WHERE en el siguiente formato:

    config { type: "incremental" }

SELECT_STATEMENT

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

    Reemplaza lo siguiente:

    • SELECT_STATEMENT: Es la declaración SELECT que define tu tabla.

    • INCREMENTAL_CONDITION: Es la condición que especificas en la cláusula WHERE para seleccionar filas para que Dataform las procese 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 para que Dataform las procese 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 indica una tabla incremental que procesa filas de forma incremental 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()})`) }

Combinar filas en una tabla incremental

Para asegurarte de que una tabla incremental contenga solo una fila correspondiente a una combinación de columnas seleccionada, establece las columnas seleccionadas como uniqueKey para combinar filas que tengan el mismo uniqueKey. Cuando se actualiza la tabla, Dataform combina 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 Files, expande definitions/.
  3. Seleccionar un archivo SQLX de definición de tabla incremental

  4. En el bloque config, configura 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 la siguiente muestra de código, aparece 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()})`) }

Filtrar filas en una tabla incremental

En una tabla particionada incremental, a fin de evitar que Dataform analice toda la tabla para encontrar filas que coincidan, configura updatePartitionFilter para que solo considere un subconjunto de registros.

En la siguiente muestra de código, se observa 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 la tabla cuando se transfieren datos desde una tabla particionada

Cuando creas una tabla incremental que hace referencia a una tabla particionada, te recomendamos que compiles 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 si usas una expresión constante en tu consulta de tabla. Para convertir un valor de la tabla particionada en una expresión constante, usa la secuencia 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 en función de 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 Files, expande definitions/.
  3. Seleccionar un archivo SQLX de definición de tabla incremental
  4. En el bloque pre_operations, declara una variable con la secuencia de comandos de BigQuery.
  5. Filtra la declaració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 la siguiente muestra de código, se observa una tabla incremental en la que event_timestamp particiona la tabla raw_events a la que se hace referencia:

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, se usa la variable event_timestamp_checkpoint como expresión constante en la cláusula WHERE.

Vuelve a compilar una tabla incremental desde cero con una actualización completa

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

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

Protege una tabla incremental de la actualización completa

Para evitar que una tabla incremental se vuelva a compilar desde cero y se produzca una posible pérdida de datos, puedes establecerla como protected. Es posible que quieras 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 Files, 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 la siguiente muestra de código, se muestran tablas incrementales marcadas como protected:

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

¿Qué sigue?