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
En la consola de Google Cloud, ve a la página Dataform.
Selecciona o crea un repositorio.
Selecciona o crea un lugar de trabajo de desarrollo.
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:
- Ve a tu lugar de trabajo de desarrollo.
- En el panel Files, expande
definitions/
. - Abre un archivo SQLX de definición de tabla incremental.
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.
- SELECT_STATEMENT: Es la declaración
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:
- Ve a tu lugar de trabajo de desarrollo.
- En el panel Files, expande
definitions/
. - Seleccionar un archivo SQLX de definición de tabla incremental
En el bloque
config
, configura las columnas seleccionadas comouniqueKey
en el siguiente formato:uniqueKey: ["COLUMN_NAME"]
Reemplaza COLUMN_NAME por el nombre de una columna seleccionada.
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:
- Ve a tu lugar de trabajo de desarrollo.
- En el panel Files, expande
definitions/
. - Seleccionar un archivo SQLX de definición de tabla incremental
- En el bloque
pre_operations
, declara una variable con la secuencia de comandos de BigQuery. - Filtra la declaración
SELECT
que define la tabla con una cláusulaWHERE
que hace referencia a la variable declarada. - 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:
- Ve a tu lugar de trabajo de desarrollo.
- En el panel Files, expande
definitions/
. - Selecciona un archivo SQLX de definición de tabla incremental.
- En el bloque
config
, ingresaprotected: true
. - 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?
- Si deseas aprender a definir una tabla, consulta Cómo crear una tabla.
- Para aprender a usar la interfaz de línea de comandos de Dataform, consulta Cómo usar la CLI de Dataform.
- Para aprender a activar ejecuciones de forma manual, consulta Activa la ejecución.