Con la plantilla de flujos de cambios de Spanner a BigQuery, transmites registros de cambios de datos de Spanner y los escribes en tablas de BigQuery con el ejecutor portátil de Dataflow. Esto integra tus datos de Spanner con BigQuery para el análisis en tiempo real y el almacenamiento de datos.
Descripción general de la plantilla
Las columnas que no se observan no se incluyen en la fila de BigQuery. Cualquier cambio de Spanner que sea menor que la marca de agua de Dataflow se aplica de forma correcta a las tablas de BigQuery o se almacena en la cola de mensajes no entregados para reintentar aplicarlo. Las filas de BigQuery se insertan de forma desordenada en comparación con el orden original de las marcas de tiempo de confirmación de Spanner.
Si las tablas de BigQuery necesarias no existen, la canalización las crea. De lo contrario, se usan las tablas de BigQuery existentes. El esquema de las tablas de BigQuery existentes debe
contener las columnas con seguimiento correspondientes de las tablas de Spanner y cualquier columna
de metadatos adicionales que la opción ignoreFields no ignore de forma explícita.
Consulta la descripción de los campos de metadatos en la siguiente lista.
Cada fila nueva de BigQuery incluye todas las columnas
observadas por el flujo de cambios de su fila correspondiente en tu tabla de Spanner en la
marca de tiempo del registro de cambios.
Los siguientes campos de metadatos se agregan a las tablas de BigQuery. Para obtener más detalles sobre estos campos, consulta Registros de cambios de datos en la sección “Cambia particiones, registros y consultas”.
_metadata_spanner_mod_type: el tipo de modificación (inserción, actualización o eliminación) de la transacción de Spanner. Se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_table_name: el nombre de la tabla de Spanner. Este campo no es el nombre de la tabla de metadatos del conector._metadata_spanner_commit_timestamp: la marca de tiempo de confirmación de Spanner, que es el momento en que se confirma un cambio. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_server_transaction_id: Una cadena única a nivel global que representa la transacción de Spanner en la que se confirmó el cambio. Usa este valor solo en el contexto del procesamiento de registros de flujos de cambios. No está correlacionado con el ID de transacción en la API de Spanner. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_record_sequence: el número de secuencia para el registro dentro de la transacción de Spanner. Los números de secuencia siempre son únicos y aumentan de forma monótona, pero no necesariamente contiguos, dentro de una transacción. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_is_last_record_in_transaction_in_partition: indica si el registro es el último de una transacción de Spanner en la partición actual. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_number_of_records_in_transaction: Es la cantidad de registros de cambios de datos que forman parte de la transacción de Spanner en todas las particiones de flujos de cambios. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_spanner_number_of_partitions_in_transaction: La cantidad de particiones que muestran registros de cambios de datos para la transacción de Spanner. Este valor se extrae del registro de cambios de los datos de flujos de cambios._metadata_big_query_commit_timestamp: la marca de tiempo de confirmación del momento en que se inserta la fila en BigQuery. SiuseStorageWriteApiestrue, la canalización no crea esta columna de forma automática en la tabla de registros de cambios. En ese caso, debes agregar esta columna de forma manual en la tabla de registro de cambios y establecerCURRENT_TIMESTAMPcomo su valor predeterminado si es necesario.
Cuando uses esta plantilla, ten en cuenta los siguientes detalles:
- Puedes usar esta plantilla para propagar columnas nuevas en tablas existentes o tablas nuevas de Spanner a BigQuery. Para obtener más información, consulta Controla la adición de tablas o columnas de seguimiento.
- Para los tipos de captura de valor
OLD_AND_NEW_VALUESyNEW_VALUES, cuando el registro de cambios de datos contiene un cambio UPDATE, la plantilla debe realizar una lectura inactiva en Spanner en la marca de tiempo de confirmación del registro de cambios de datos para recuperar las columnas que sí se observaron, pero no se modificaron. Asegúrate de configurar la base de datos “'version_retention_period” de forma adecuada para la lectura inactiva. Para el tipo de captura del valorNEW_ROW, la plantilla es más eficiente, porque el registro de cambios de datos captura la fila nueva completa, incluidas las columnas que no se actualizan en las solicitudes UPDATE, y la plantilla no necesita realizar una lectura inactiva. - Para minimizar la latencia de la red y los costos de transporte de la red, ejecuta el trabajo de Dataflow desde la misma región que tu instancia de Spanner o tus tablas de BigQuery. Si usas fuentes, receptores, ubicaciones de archivos de etapa de pruebas o ubicaciones de archivos temporales que se encuentran fuera de la región del trabajo, es posible que los datos se envíen a través de diferentes regiones. Para obtener más información, consulta Regiones de Dataflow.
- Esta plantilla admite todos los tipos de datos válidos de Spanner. Si el tipo de Spanner
es más preciso que el de BigQuery, podría producirse una pérdida de precisión durante la
transformación. Específicamente:
- Para el tipo
JSONde Spanner, el orden de los miembros de un objeto se ordena de forma lexicográfica, pero no existe esa garantía para el tipoJSONde BigQuery. - Spanner admite la precisión de nanosegundos para el tipo
TIMESTAMP, pero esta plantilla escribe en las columnasTIMESTAMPde BigQuery con precisión de microsegundos, lo que genera el truncamiento de las marcas de tiempo inferiores a microsegundos. Si necesitas conservar la precisión de nanosegundos en BigQuery, almacena los valores de marca de tiempo comoINT64(nanosegundos desde el tiempo Unix) oSTRINGen Spanner.
- Para el tipo
Obtén más información sobre los flujos de cambios, cómo compilar canalizaciones de Dataflow de flujos de cambio y prácticas recomendadas.
Requisitos de la canalización
- La instancia de Spanner debe existir antes de ejecutar la canalización.
- La base de datos de Spanner debe existir antes de ejecutar la canalización.
- La instancia de metadatos de Spanner debe existir antes de ejecutar la canalización.
- La base de datos de metadatos de Spanner debe existir antes de ejecutar la canalización.
- El flujo de cambios de Spanner debe existir antes de ejecutar la canalización.
- Solo se admiten los flujos de cambios que supervisan las tablas en el esquema predeterminado.
- Los flujos de cambios que observan tablas en otros esquemas arrojan un [error de tabla no encontrada](https://github.com/GoogleCloudPlatform/DataflowTemplates/issues/2622).
- El conjunto de datos de BigQuery debe existir antes de ejecutar la canalización.
Controla la adición de tablas o columnas de seguimiento
En esta sección, se describen las prácticas recomendadas para agregar tablas y columnas de seguimiento de Spanner
mientras se ejecuta la canalización. La versión de plantilla más antigua compatible con esta función es la 2024-09-19-00_RC00.
Antes de agregar una columna nueva a un alcance de flujo de cambios de Spanner, primero agrégala a la tabla de registro de cambios de BigQuery. La columna agregada debe tener un tipo de datos coincidente y ser
NULLABLE. Espera al menos 10 minutos antes de continuar con la creación de la columna o tabla nueva en Spanner. Si escribes en la columna nueva sin esperar, es posible que se genere un registro sin procesar con un código de error no válido en la cola de mensajes no entregados.Para los tipos de captura de valores
NEW_ROWoNEW_ROW_AND_OLD_VALUES, se admite agregar una columna nueva con un valor predeterminado durante una canalización en ejecución. Para ello, primero se agrega la columna a la tabla de BigQuery y, luego, a la tabla de Spanner.En el caso de
NEW_VALUESoOLD_AND_NEW_VALUES, agregar una columna nueva con un valor predeterminado a una canalización en ejecución puede provocar la pérdida de datos. Para evitar la pérdida de datos, debes realizar una exportación y, luego, una importación manuales de tus datos con el siguiente proceso:- Detén la canalización de Dataflow.
- Agrega la columna a la tabla de BigQuery.
- Agrega la columna con un valor predeterminado en Spanner.
- Espera a que se completen el cambio de esquema y el reabastecimiento de Spanner.
- Exporta los datos de la tabla de Spanner con una marca de tiempo posterior a la finalización del reabastecimiento.
- Importa los datos a la tabla de BigQuery y asegúrate de controlar la columna nueva correctamente.
- Inicia la canalización de Dataflow desde la misma marca de tiempo que se usó para la exportación.
- Para agregar una tabla nueva, primero agrégala a la base de datos de Spanner. La tabla se crea automáticamente en BigQuery cuando la canalización recibe un registro para la tabla nueva.
- Después de agregar las columnas o tablas nuevas a la base de datos de Spanner, asegúrate de alterar tu flujo de cambios para hacer un seguimiento de las columnas o tablas nuevas que deseas si aún no se les hace un seguimiento implícito.
- La plantilla no descarta tablas ni columnas de BigQuery. Si se quita una columna de la tabla de Spanner, los valores nulos se propagan a las columnas del registro de cambios de BigQuery para los registros generados después de que se quiten las columnas de la tabla de Spanner, a menos que quites la columna de BigQuery de forma manual.
- La plantilla no admite actualizaciones de tipo de columna. Aunque
Spanner admite cambiar una columna
STRINGa unaBYTESo una columnaBYTESa unaSTRING, no puedes modificar el tipo de datos de una columna existente ni usar el mismo nombre de columna con diferentes tipos de datos en BigQuery. Si sueltas y vuelves a crear una columna con el mismo nombre, pero con un tipo diferente en Spanner, es posible que los datos se escriban en la columna de BigQuery existente, pero el tipo no cambiará. - Esta plantilla no admite actualizaciones del modo de columna. Las columnas de metadatos
replicadas en BigQuery se configuran en el modo
REQUIRED. Todas las demás columnas replicadas en BigQuery se establecen enNULLABLE, independientemente de si se definen comoNOT NULLen la tabla de Spanner. No puedes actualizar las columnasNULLABLEal modoREQUIREDen BigQuery. - No se admite cambiar el tipo de captura de valor de un flujo de cambios para ejecutar canalizaciones.
Parámetros de la plantilla
Parámetros obligatorios
- spannerInstanceId: Es la instancia de Spanner desde la que se leerán los flujos de cambios.
- spannerDatabase: Es la base de datos de Spanner desde la que se leerán los flujos de cambios.
- spannerMetadataInstanceId: Es la instancia de Spanner que se usará para la tabla de metadatos del conector de flujos de cambios.
- spannerMetadataDatabase: Es la base de datos de Spanner que se usará para la tabla de metadatos del conector de flujos de cambios.
- spannerChangeStreamName: Es el nombre del flujo de cambios de Spanner desde el que se leerá.
- bigQueryDataset: Es el conjunto de datos de BigQuery de salida de los flujos de cambios.
Parámetros opcionales
- spannerProjectId: Es el proyecto desde el que se leerán los flujos de cambios. Este valor es también el proyecto en el que se crea la tabla de metadatos del conector de flujos de cambios. El valor predeterminado para este parámetro es el proyecto en el que se ejecuta la canalización de Dataflow.
- spannerDatabaseRole: Es el rol de base de datos de Spanner que se usará cuando se ejecute la plantilla. Este parámetro solo es necesario cuando el principal de IAM que ejecuta la plantilla es un usuario de control de acceso detallado. El rol de la base de datos debe tener el privilegio
SELECTen el flujo de cambios y el privilegioEXECUTEen la función de lectura del flujo de cambios. Para obtener más información, consulta Control de acceso detallado para los flujos de cambios (https://cloud.google.com/spanner/docs/fgac-change-streams). - spannerMetadataTableName: Es el nombre de la tabla de metadatos del conector de flujos de cambios de Spanner que se usará. Si no se proporciona, una tabla de metadatos de conectores de flujos de cambios de Spanner se crea de forma automática durante el flujo de la canalización. Debes proporcionar este parámetro cuando actualices una canalización existente. De lo contrario, no proporciones este parámetro.
- rpcPriority: Es la prioridad de solicitud para llamadas de Spanner. El valor debe ser uno de estos valores:
HIGH,MEDIUMoLOW. El valor predeterminado esHIGH. - spannerHost: Es el extremo de Cloud Spanner al que se llamará en la plantilla. Solo se usa para pruebas. Por ejemplo,
https://batch-spanner.googleapis.com - startTimestamp: Es la fecha y hora de inicio (https://datatracker.ietf.org/doc/html/rfc3339), inclusiva, que se usará para leer los flujos de cambios. Ej.: 2021-10-12T07:20:50.52Z. El valor predeterminado es la marca de tiempo del inicio de la canalización, es decir, la hora actual.
- endTimestamp: La fecha y hora de finalización (https://datatracker.ietf.org/doc/html/rfc3339), inclusiva, que se usará para leer los flujos de cambios.Ex-2021-10-12T07:20:50.52Z. El valor predeterminado es un tiempo infinito en el futuro.
- bigQueryProjectId: Es el proyecto de BigQuery. El valor predeterminado es el proyecto para el trabajo de Dataflow.
- bigQueryChangelogTableNameTemplate: Es la plantilla para el nombre de la tabla de BigQuery que contiene el registro de cambios. El valor predeterminado es: {_metadata_spanner_table_name}_changelog.
- deadLetterQueueDirectory: Es la ruta para almacenar los registros no procesados. La ruta predeterminada es un directorio en la ubicación temporal del trabajo de Dataflow. Por lo general, el valor predeterminado es suficiente.
- dlqRetryMinutes: Es la cantidad de minutos entre reintentos de la cola de mensajes no entregados. El valor predeterminado es
10. - ignoreFields: Es una lista separada por comas de campos (distingue mayúsculas de minúsculas) que se deben ignorar. Estos campos pueden ser de tablas observadas o campos de metadatos que agregan la canalización. Los campos ignorados no se insertan en BigQuery. Cuando ignoras el campo _metadata_spanner_table_name, también se ignora el parámetro bigQueryChangelogTableNameTemplate. La configuración predeterminada es vacía.
- disableDlqRetries: Indica si se deben inhabilitar o no los reintentos para la DLQ. La configuración predeterminada es "false".
- spannerChangeStreamTvfNameList: Es la lista separada por punto y coma de los nombres de TVF del flujo de cambios de Spanner que se consultarán y unirán. La configuración predeterminada es vacía.
- spannerDirectedReadOptions: Son las opciones de lectura dirigida para las lecturas de flujos de cambios de Cloud Spanner. El valor debe ser un formato de cadena JSON de DirectedReadOptions (p.ej., {"includeReplicas":{"replicaSelections":[{"location":"us-central1","type":"READ_ONLY"}]}}). Para obtener más información, consulta Lecturas dirigidas (https://docs.cloud.google.com/spanner/docs/directed-reads). La configuración predeterminada es vacía.
- useStorageWriteApi: Si es verdadero, la canalización usa la API de BigQuery Storage Write (https://cloud.google.com/bigquery/docs/write-api). El valor predeterminado es
false. Para obtener más información, consulta Usa la API de Storage Write (https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api). - useStorageWriteApiAtLeastOnce: Cuando usas la API de Storage Write, se especifica la semántica de escritura. Para usar una semántica de al menos una vez (https://beam.apache.org/documentation/io/built-in/google-bigquery/#at-least-once-semantics), configura este parámetro en
true. Para usar una semántica de una y solo una vez, configura el parámetro enfalse. Este parámetro se aplica solo cuandouseStorageWriteApiestrue. El valor predeterminado esfalse. - numStorageWriteApiStreams: Cuando usas la API de Storage Write, se especifica la cantidad de transmisiones de escritura. Si
useStorageWriteApiestrueyuseStorageWriteApiAtLeastOnceesfalse, debes configurar este parámetro. La configuración predeterminada es 0. - storageWriteApiTriggeringFrequencySec: Cuando se usa la API de Storage Write, se especifica la frecuencia de activación en segundos. Si
useStorageWriteApiestrueyuseStorageWriteApiAtLeastOnceesfalse, debes configurar este parámetro.
Ejecuta la plantilla
Console
- Ve a la página Crear un trabajo a partir de una plantilla de Dataflow. Ir a Crear un trabajo a partir de una plantilla
- En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
- Opcional: Para Extremo regional, selecciona un valor del menú desplegable. La región predeterminada es
us-central1.Para obtener una lista de regiones en las que puedes ejecutar un trabajo de Dataflow, consulta Ubicaciones de Dataflow.
- En el menú desplegable Plantilla de Dataflow, selecciona la plantilla Flujos de cambios de Cloud Spanner a BigQuery.
- En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
- Haga clic en Ejecutar trabajo.
gcloud
En tu shell o terminal, ejecuta la plantilla:
gcloud dataflow flex-template run JOB_NAME \ --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_BigQuery \ --region REGION_NAME \ --parameters \ spannerInstanceId=SPANNER_INSTANCE_ID,\ spannerDatabase=SPANNER_DATABASE,\ spannerMetadataInstanceId=SPANNER_METADATA_INSTANCE_ID,\ spannerMetadataDatabase=SPANNER_METADATA_DATABASE,\ spannerChangeStreamName=SPANNER_CHANGE_STREAM,\ bigQueryDataset=BIGQUERY_DATASET
Reemplaza lo siguiente:
JOB_NAME: Es el nombre del trabajo que elijasVERSION: Es la versión de la plantilla que deseas usar.Puedes usar los siguientes valores:
latestpara usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket: gs://dataflow-templates/latest/- el nombre de la versión, como
2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket: gs://dataflow-templates/
REGION_NAME: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo,us-central1SPANNER_INSTANCE_ID: ID de la instancia de SpannerSPANNER_DATABASE: base de datos de SpannerSPANNER_METADATA_INSTANCE_ID: ID de la instancia de metadatos de SpannerSPANNER_METADATA_DATABASE: base de datos de metadatos de SpannerSPANNER_CHANGE_STREAM: flujo de cambios de SpannerBIGQUERY_DATASET: El conjunto de datos de BigQuery de salida de los flujos de cambios.
API
Para ejecutar la plantilla con la API de REST, envía una solicitud POST HTTP. Para obtener más información de la API y sus permisos de autorización, consulta projects.templates.launch.
POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch { "launch_parameter": { "jobName": "JOB_NAME", "parameters": { "spannerInstanceId": "SPANNER_INSTANCE_ID", "spannerDatabase": "SPANNER_DATABASE", "spannerMetadataInstanceId": "SPANNER_METADATA_INSTANCE_ID", "spannerMetadataDatabase": "SPANNER_METADATA_DATABASE", "spannerChangeStreamName": "SPANNER_CHANGE_STREAM", "bigQueryDataset": "BIGQUERY_DATASET" }, "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Spanner_Change_Streams_to_BigQuery", } }
Reemplaza lo siguiente:
PROJECT_ID: el ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de DataflowJOB_NAME: Es el nombre del trabajo que elijasVERSION: Es la versión de la plantilla que deseas usar.Puedes usar los siguientes valores:
latestpara usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket: gs://dataflow-templates/latest/- el nombre de la versión, como
2023-09-12-00_RC00, para usar una versión específica de la plantilla, que se puede encontrar anidada en la carpeta superior con fecha correspondiente en el bucket: gs://dataflow-templates/
LOCATION: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo,us-central1SPANNER_INSTANCE_ID: ID de la instancia de SpannerSPANNER_DATABASE: base de datos de SpannerSPANNER_METADATA_INSTANCE_ID: ID de la instancia de metadatos de SpannerSPANNER_METADATA_DATABASE: base de datos de metadatos de SpannerSPANNER_CHANGE_STREAM: flujo de cambios de SpannerBIGQUERY_DATASET: El conjunto de datos de BigQuery de salida de los flujos de cambios.
Consideraciones de producción
Cuando ejecutes la plantilla de flujos de cambios de Spanner a BigQuery en un entorno de producción, ten en cuenta las siguientes prácticas recomendadas para garantizar la confiabilidad y evitar la pérdida de datos:
Aprovisionamiento y escalamiento de trabajadores
- Configura
maxNumWorkersde forma adecuada: Si no hay suficientes trabajadores de Dataflow, la canalización puede retrasarse en el procesamiento de los datos del flujo de cambios. Esto puede aumentar la latencia y, en algunas situaciones, provocar una posible pérdida de datos debido a tiempos de espera internos del conector y condiciones de carrera. La cantidad máxima de trabajadores debe ser suficiente para controlar la capacidad de procesamiento de escritura máxima de Spanner. - Guía de dimensionamiento: Si bien la cantidad óptima varía según la carga de trabajo, consulta la guía de flujos de cambios de Spanner sobre cómo dimensionar tu clúster de Dataflow. Supervisa el rendimiento de tu canalización y realiza los ajustes necesarios. Por ejemplo, algunas cargas de trabajo de alta capacidad de procesamiento pueden requerir un aumento significativo de
maxNumWorkers(por ejemplo, de 20 a 100 o más). - Ajuste del escalado automático: El escalado automático horizontal predeterminado de Dataflow se basa principalmente en la CPU. Si tu canalización se retrasa, pero el uso de CPU no es alto, considera ajustar el ajuste de escala automático. Reducir el parámetro
worker_utilization_hintpuede hacer que el escalado automático responda mejor a otros cuellos de botella. Consulta Ajusta el escalado automático horizontal para obtener más detalles.
Supervisión y alertas
- Actualidad de los datos de salida (retraso del sistema): Esta es la métrica más importante que se debe supervisar para esta plantilla. Un aumento constante en la "Actualidad de los datos de salida" (
dataflow.googleapis.com/job/system_lag) indica que la canalización no se mantiene al día con los cambios entrantes de Spanner . - Configura alertas: Configura alertas de Cloud Monitoring en la métrica "Actualidad de los datos de salida". Establece un modelo de referencia para tu canalización y configura umbrales según los requisitos de tu empresa para la latencia de datos. Investiga de inmediato cualquier alerta de aumentos sostenidos en esta métrica. Para obtener más información, consulta Métricas de trabajos de Dataflow.
Interpreta los registros
SpannerException: DEADLINE_EXCEEDED: Si bien el conector tiene reintentos, los mensajes frecuentes decom.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDEDen los registros de los trabajadores de Dataflow son un indicador claro de que los trabajadores tienen dificultades para leer los datos de los flujos de cambios de Spanner de manera oportuna. Esto suele indicar que la canalización no tiene suficientes recursos de trabajadores.
Configuración del flujo de cambios de Spanner
- Período de retención: Asegúrate de que el
retention_periodde tu flujo de cambios de Spanner esté configurado con una duración suficiente para controlar posibles ralentizaciones o interrupciones de la canalización de Dataflow. El valor predeterminado es de 7 días. Considera establecer este valor entre 3 y 7 días para proporcionar un búfer más grande para que la canalización recupere y procese cualquier trabajo pendiente sin pérdida de datos debido a que los cambios vencen de la transmisión.
Si implementas estas prácticas, puedes mejorar la resiliencia y el rendimiento de tu canalización de Dataflow de flujos de cambios de Spanner a BigQuery.
¿Qué sigue?
- Obtén información sobre las plantillas de Dataflow.
- Consulta la lista de plantillas que proporciona Google.