Plantilla de BigQuery a Bigtable

La plantilla de BigQuery a Bigtable es una canalización por lotes que copia los datos de una tabla de BigQuery a una tabla de Bigtable existente. La plantilla puede leer toda la tabla o registros específicos a través de una consulta proporcionada.

Requisitos de la canalización

• La tabla de origen de BigQuery debe existir.
• La tabla de Bigtable debe existir.
• La cuenta de servicio de trabajador necesita el permiso roles/bigquery.datasets.create. Para obtener más información, consulta Introducción a IAM.

Parámetros de la plantilla

Parámetros obligatorios

• readIdColumn: El nombre de la columna de BigQuery que almacena el identificador único de la fila.
• bigtableWriteInstanceId : El ID de la instancia de Bigtable que contiene la tabla.
• bigtableWriteTableId : El ID de la tabla de Bigtable en la que se escribirá.
• bigtableWriteColumnFamily : El nombre de la familia de columnas de la tabla de Bigtable en la que se escribirán los datos.

Parámetros opcionales

• inputTableSpec: La tabla de BigQuery desde la que se leerá. Formato: projectId:datasetId.tablename. Si especificas inputTableSpec, la plantilla lee los datos directamente desde el almacenamiento de BigQuery con la API de BigQuery Storage Read (https://cloud.google.com/bigquery/docs/reference/storage). Para obtener información sobre las limitaciones en la API de Storage Read, consulta https://cloud.google.com/bigquery/docs/reference/storage#limitations. Debes especificar inputTableSpec o query. Si estableces ambos parámetros, la plantilla usa el parámetro query. (Ejemplo: bigquery-project:dataset.input_table).
• outputDeadletterTable: la tabla de BigQuery para los mensajes que no llegaron a la tabla de salida, en el formato <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>. Si no existe una tabla, se crea durante la ejecución de la canalización. Si no se especifica, se usa <outputTableSpec>_error_records. (Ejemplo: your-project-id:your-dataset.your-table-name).
• query : La consulta en SQL que se usará para leer datos de BigQuery. Si el conjunto de datos de BigQuery se encuentra en un proyecto diferente que el trabajo de Dataflow, especifica el nombre completo del conjunto de datos en la consulta en SQL, por ejemplo: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>. De forma predeterminada, el parámetro query usa GoogleSQL (https://cloud.google.com/bigquery/docs/introduction-sql), a menos que useLegacySql sea true. Debes especificar inputTableSpec o query. Si estableces ambos parámetros, la plantilla usa el parámetro query. (Ejemplo: selecciona * de sampledb.sample_table).
• useLegacySql: configurado como verdadero para usar un SQL heredado. Este parámetro solo se aplica cuando se usa el parámetro query. La configuración predeterminada es "false".
• queryLocation: se necesita cuando se lee desde una vista autorizada sin el permiso de la tabla subyacente. (Ejemplo: US).
• queryTempDataset : Con esta opción, puedes establecer un conjunto de datos existente para crear la tabla temporal que almacenará los resultados de la consulta. (Ejemplo: temp_dataset).
• bigtableRpcAttemptTimeoutMs : El tiempo de espera para cada intento de RPC de Bigtable en milisegundos (opcional).
• bigtableRpcTimeoutMs : El tiempo de espera total para una operación RPC de Bigtable en milisegundos (opcional).
• bigtableAdditionalRetryCodes : Los códigos de reintento adicionales. (ejemplo: RESOURCE_EXHAUSTED,DEADLINE_EXCEEDED).
• bigtableWriteAppProfile : Es el ID del perfil de la aplicación de Bigtable que se usará para la exportación. Si no especificas un perfil de app, Bigtable usa el perfil de app predeterminado (https://cloud.google.com/bigtable/docs/app-profiles#default-app-profile) de la instancia.
• bigtableWriteProjectId : el ID del proyecto de Google Cloud que contiene la instancia de Bigtable en la que se escribirán los datos.
• bigtableBulkWriteLatencyTargetMs : El objetivo de latencia de Bigtable en milisegundos para la limitación basada en la latencia.
• bigtableBulkWriteMaxRowKeyCount : Es la cantidad máxima de claves de fila en una operación de escritura por lotes de Bigtable.
• bigtableBulkWriteMaxRequestSizeBytes : Es la cantidad máxima de bytes que se incluirán por operación de escritura por lotes de Bigtable.

Ejecuta la plantilla

Console

1. 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
2. En el campo Nombre del trabajo, ingresa un nombre de trabajo único.
3. 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.

4. En el menú desplegable Plantilla de Dataflow, selecciona the BigQuery to Bigtable template.
5. En los campos de parámetros proporcionados, ingresa los valores de tus parámetros.
6. Haga clic en Ejecutar trabajo.

gcloud

Nota: Para usar Google Cloud CLI a fin de ejecutar plantillas flex, debes tener Google Cloud CLI en la versión 284.0.0 o una versión posterior.

En tu shell o terminal, ejecuta la plantilla:

gcloud dataflow flex-template run JOB_NAME \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/BigQuery_to_Bigtable \
    --parameters \
readIdColumn=READ_COLUMN_ID,\
inputTableSpec=INPUT_TABLE_SPEC,\
bigtableWriteInstanceId=BIGTABLE_INSTANCE_ID,\
bigtableWriteTableId=BIGTABLE_TABLE_ID,\
bigtableWriteColumnFamily=BIGTABLE_COLUMN_FAMILY

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de Dataflow.
• JOB_NAME: Es el nombre del trabajo que elijas
• REGION_NAME: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
• VERSION: Es la versión de la plantilla que deseas usar.

  Puedes usar los siguientes valores:

  • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/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/
  Precaución: La versión más reciente de las plantillas podría actualizarse con cambios rotundos. Los entornos de producción deben usar plantillas que se conserven en la carpeta superior con la fecha más reciente para evitar que estos cambios rotundos afecten los flujos de trabajo de producción.
• READ_COLUMN_ID: la columna de ID único de BigQuery.
• INPUT_TABLE_SPEC: Es el nombre de la tabla de BigQuery.
• BIGTABLE_INSTANCE_ID: tu ID de instancia de Bigtable.
• BIGTABLE_TABLE_ID: tu ID de tabla de Bigtable.
• BIGTABLE_COLUMN_FAMILY: tu familia de columnas de la tabla de Bigtable.

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": {
          "readIdColumn": "READ_COLUMN_ID",
          "inputTableSpec": "INPUT_TABLE_SPEC",
          "bigtableWriteInstanceId": "BIGTABLE_INSTANCE_ID",
          "bigtableWriteTableId": "BIGTABLE_TABLE_ID",
          "bigtableWriteColumnFamily": "BIGTABLE_COLUMN_FAMILY"
      },
      "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/BigQuery_to_Bigtable",
   }
}

Reemplaza lo siguiente:

• PROJECT_ID: El ID del proyecto de Google Cloud en el que deseas ejecutar el trabajo de Dataflow.
• JOB_NAME: Es el nombre del trabajo que elijas
• LOCATION: La región en la que deseas implementar tu trabajo de Dataflow, por ejemplo, us-central1
• VERSION: Es la versión de la plantilla que deseas usar.

  Puedes usar los siguientes valores:

  • latest para usar la última versión de la plantilla, que está disponible en la carpeta superior non-dated en el bucket gs://dataflow-templates-REGION_NAME/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/
  Precaución: La versión más reciente de las plantillas podría actualizarse con cambios rotundos. Los entornos de producción deben usar plantillas que se conserven en la carpeta superior con la fecha más reciente para evitar que estos cambios rotundos afecten los flujos de trabajo de producción.
• READ_COLUMN_ID: la columna de ID único de BigQuery.
• INPUT_TABLE_SPEC: Es el nombre de la tabla de BigQuery.
• BIGTABLE_INSTANCE_ID: tu ID de instancia de Bigtable.
• BIGTABLE_TABLE_ID: tu ID de tabla de Bigtable.
• BIGTABLE_COLUMN_FAMILY: tu familia de columnas de la tabla de Bigtable.

Código fuente de la plantilla

Java

/*
 * Copyright (C) 2021 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
package com.google.cloud.teleport.v2.templates;

import static com.google.cloud.teleport.v2.bigtable.utils.BigtableConfig.generateCloudBigtableWriteConfiguration;

import com.google.cloud.bigtable.beam.CloudBigtableIO;
import com.google.cloud.bigtable.beam.CloudBigtableTableConfiguration;
import com.google.cloud.teleport.metadata.Template;
import com.google.cloud.teleport.metadata.TemplateCategory;
import com.google.cloud.teleport.metadata.TemplateParameter;
import com.google.cloud.teleport.v2.bigtable.options.BigtableCommonOptions;
import com.google.cloud.teleport.v2.bigtable.transforms.BigtableConverters;
import com.google.cloud.teleport.v2.common.UncaughtExceptionLogger;
import com.google.cloud.teleport.v2.templates.BigQueryToBigtable.BigQueryToBigtableOptions;
import com.google.cloud.teleport.v2.transforms.BigQueryConverters;
import org.apache.beam.sdk.Pipeline;
import org.apache.beam.sdk.extensions.gcp.options.GcpOptions;
import org.apache.beam.sdk.io.gcp.bigquery.BigQueryIO;
import org.apache.beam.sdk.options.PipelineOptionsFactory;
import org.apache.beam.sdk.options.Validation.Required;
import org.apache.hadoop.hbase.client.Mutation;

/**
 * Dataflow template which reads BigQuery data and writes it to Bigtable. The source data can be
 * either a BigQuery table or an SQL query.
 *
 * <p>Check out <a
 * href="https://github.com/GoogleCloudPlatform/DataflowTemplates/blob/main/v2/bigquery-to-bigtable/README_BigQuery_to_Bigtable.md">README</a>
 * for instructions on how to use or modify this template.
 */
@Template(
    name = "BigQuery_to_Bigtable",
    category = TemplateCategory.BATCH,
    displayName = "BigQuery to Bigtable",
    description = "A pipeline to export a BigQuery table into Bigtable.",
    optionsClass = BigQueryToBigtableOptions.class,
    optionsOrder = {
      BigQueryToBigtableOptions.class,
      BigQueryConverters.BigQueryReadOptions.class,
      BigtableCommonOptions.class,
      BigtableCommonOptions.WriteOptions.class
    },
    optionalOptions = {"inputTableSpec"},
    flexContainerName = "bigquery-to-bigtable",
    documentation =
        "https://cloud.google.com/dataflow/docs/guides/templates/provided/bigquery-to-bigtable",
    contactInformation = "https://cloud.google.com/support",
    requirements = {
      "The source BigQuery table must exist.",
      "The Bigtable table must exist.",
      "The <a href=\"https://cloud.google.com/dataflow/docs/concepts/security-and-permissions#worker-service-account\">worker service account</a>"
          + " needs the <code>roles/bigquery.datasets.create</code> permission. For"
          + " more information, see <a href=\"https://cloud.google.com/bigquery/docs/access-control\">Introduction to IAM</a>."
    })
public class BigQueryToBigtable {

  /**
   * The {@link BigQueryToBigtableOptions} class provides the custom execution options passed by the
   * executor at the command-line.
   */
  public interface BigQueryToBigtableOptions
      extends BigQueryConverters.BigQueryReadOptions,
          BigtableCommonOptions.WriteOptions,
          GcpOptions {

    @TemplateParameter.Text(
        order = 1,
        regexes = {"[A-Za-z_][A-Za-z_0-9]*"},
        description = "Unique identifier column",
        helpText = "The name of the BigQuery column storing the unique identifier of the row.")
    @Required
    String getReadIdColumn();

    void setReadIdColumn(String value);
  }

  /**
   * Runs a pipeline which reads data from BigQuery and writes it to Bigtable.
   *
   * @param args arguments to the pipeline
   */
  public static void main(String[] args) {
    UncaughtExceptionLogger.register();

    BigQueryToBigtableOptions options =
        PipelineOptionsFactory.fromArgs(args).withValidation().as(BigQueryToBigtableOptions.class);

    CloudBigtableTableConfiguration bigtableTableConfig =
        generateCloudBigtableWriteConfiguration(options);

    Pipeline pipeline = Pipeline.create(options);

    pipeline
        .apply(
            "AvroToMutation",
            BigQueryConverters.ReadBigQuery.<Mutation>newBuilder()
                .setOptions(options.as(BigQueryToBigtableOptions.class))
                .setReadFunction(
                    BigQueryIO.read(
                        BigtableConverters.AvroToMutation.newBuilder()
                            .setColumnFamily(options.getBigtableWriteColumnFamily())
                            .setRowkey(options.getReadIdColumn())
                            .build()))
                .build())
        .apply("WriteToTable", CloudBigtableIO.writeToTable(bigtableTableConfig));

    pipeline.run();
  }
}

¿Qué sigue?

• Obtén información sobre las plantillas de Dataflow.
• Consulta la lista de plantillas que proporciona Google.