HBase data synchronization with DataWorks - DataWorks - Centro de documentación de Alibaba Cloud

El origen de datos HBase permite leer y escribir en HBase. Este tema describe sus capacidades de sincronización de datos en DataWorks.

Versiones compatibles

Existen dos tipos de plugins de HBase: el plugin HBase y el plugin HBase{xx}xsql. El plugin HBase{xx}xsql requiere tanto HBase como Phoenix.

Plugin HBase:

Compatible con HBase0.94.x, HBase1.1.x y HBase2.x. Se admiten tanto la interfaz sin código como el editor de código. Utilice el parámetro hbaseVersion para especificar la versión.
- Si su versión de HBase es HBase0.94.x, establezca hbaseVersion en 094x tanto para el lector como para el escritor.
```
"reader": {
        "hbaseVersion": "094x"
    }
```
```
"writer": {
        "hbaseVersion": "094x"
    }
```
- Si su versión de HBase es HBase1.1.x o HBase2.x, establezca hbaseVersion en 11x tanto para el lector como para el escritor.
```
"reader": {
        "hbaseVersion": "11x"
    }
```
```
"writer": {
        "hbaseVersion": "11x"
    }
```
  El plugin HBase1.1.x es compatible con HBase 2.0.
Plugin HBase{xx}xsql
1. Plugin HBase20xsql: Compatible con HBase2.x y Phoenix5.x. Solo se admite el editor de código.
  
  Plugin HBase11xsql: Compatible con HBase1.1.x y Phoenix5.x. Solo se admite el editor de código.
2. El plugin de escritura HBase{xx}xsql ofrece una forma sencilla de importar datos por lotes a tablas SQL (Phoenix) en HBase. Phoenix codifica la rowkey. Escribir datos mediante la API de HBase requiere una conversión manual de datos, lo cual es un proceso complejo y propenso a errores.
  
  Nota
  El plugin utiliza el controlador JDBC de Phoenix para ejecutar sentencias UPSERT y escribir datos en la tabla por lotes. Su interfaz de alto nivel también permite actualizaciones síncronas en las tablas de índices.

Limitaciones

HBase Reader	HBase20xsql Reader	HBase11xsql Writer
HBase Reader no puede leer datos escritos por Phoenix porque este aplica un procesamiento especial a los datos. HBase Reader solo admite serverless resource group for Data Integration (recommended) y exclusive resource group for Data Integration, pero no el resource group predeterminado ni custom resource group.	La fragmentación de tablas está restringida a una sola columna, que debe ser la clave principal. Para una fragmentación uniforme basada en la concurrencia del trabajo, la columna de fragmentación debe ser un entero o una cadena. Los nombres de tablas, esquemas y columnas distinguen entre mayúsculas y minúsculas, y deben coincidir con el formato de mayúsculas de la tabla Phoenix. HBase20xsql Reader solo puede leer datos a través de Phoenix QueryServer. Por lo tanto, debe iniciar Phoenix QueryServer para utilizar HBase20xsql Reader.	Solo se admite serverless resource group for Data Integration (recommended). No se admite la importación de datos con marca de tiempo. Solo se admiten tablas creadas con Phoenix, no tablas nativas de HBase. El orden de las columnas en el escritor debe coincidir con el orden de las columnas en el lector. El orden de las columnas del lector determina la secuencia de columnas en cada fila de salida. El orden de las columnas del escritor determina la secuencia esperada de columnas en los datos recibidos. Por ejemplo: El orden de las columnas en el lector es c1, c2, c3 y c4. El orden de las columnas en el escritor es x1, x2, x3 y x4. En este caso, el valor de la columna c1 se asigna a la columna x1. Si el orden de las columnas en el escritor es x1, x2, x4 y x3, el valor de la columna c3 se asigna a la columna x4, y el valor de la columna c4 se asigna a la columna x3. Importar datos a una tabla indexada actualiza sincrónicamente todos los índices relacionados.

Funcionalidades

HBase Reader

HBase Reader admite los modos normal y multiVersionFixedColumn. Consulte HBase field mapping guide para obtener instrucciones de configuración.

En el modo normal, HBase Reader trata una tabla HBase como una tabla bidimensional estándar (tabla ancha) y lee la versión más reciente de los datos.

hbase:007:0> scan 'student'
ROW                                   COLUMN+CELL
s001                                 column=basic:age, timestamp=2026-03-09T14:41:40.240, value=20
s001                                 column=basic:name, timestamp=2026-03-09T14:41:40.214, value=Tom
s001                                 column=score:english, timestamp=2026-03-09T14:41:40.333, value=90
s001                                 column=score:math, timestamp=2026-03-09T14:41:40.277, value=85
1 row(s) in 0.0580 seconds

La siguiente tabla muestra los datos de salida.

Row key	basic:age	basic:name	score:english	score:math
s001	20	Tom	90	85

Modo multiVersionFixedColumn: Lee una tabla HBase como una tabla estrecha. Cada registro devuelto consta de cuatro columnas: rowKey, family:qualifier, timestamp y value. Debe especificar explícitamente las columnas que desea leer. El valor de cada celda se trata como un registro. Si existen múltiples versiones, se devuelven varios registros.

hbase:007:0> scan 'student',{VERSIONS=>5}
ROW                                   COLUMN+CELL
s001                                 column=basic:age, timestamp=2026-03-09T14:41:40.240, value=20
s001                                 column=basic:age, timestamp=2026-03-09T14:30:00.100, value=19
s001                                 column=basic:name, timestamp=2026-03-09T14:41:40.214, value=Tom
s001                                 column=score:english, timestamp=2026-03-09T14:41:40.333, value=90
s001                                 column=score:math, timestamp=2026-03-09T14:41:40.277, value=85
1 row(s) in 0.0260 seconds }

Row key	family:qualifier	Timestamp	Value
s001	basic:age	2026-03-09T14:41:40.240	20
s001	basic:age	2026-03-09T14:30:00.100	19
s001	basic:name	2026-03-09T14:41:40.214	Tom
s001	score:english	2026-03-09T14:41:40.333	90
s001	score:math	2026-03-09T14:41:40.277	85

HBase Writer

Regla de generación de rowkey: Actualmente, HBase Writer admite la concatenación de varios campos del origen para usarlos como rowkey de una tabla HBase.
Puede especificar una versión (marca de tiempo) para escribir datos en HBase. Las opciones disponibles son:
- Usar la hora actual como versión.
- Especificar una columna de origen como versión.
- Especificar una hora como versión.

Tipos de datos compatibles

Lectura por lotes

Esta tabla muestra los tipos de datos de HBase admitidos y cómo los convierte HBase Reader.

Categoría	Tipo de columna de Data Integration	Tipo de dato de base de datos
Entero	long	short, int y long
Punto flotante	double	float y double
Cadena	string	binary_string y string
Fecha y hora	date	date
Byte	bytes	bytes
Booleano	boolean	boolean

HBase20xsql Reader admite la mayoría de los tipos de datos de Phoenix, pero no todos. Asegúrese de que sus tipos de datos sean compatibles.

Esta tabla muestra cómo HBase20xsql Reader asigna los tipos de datos de Phoenix a los tipos internos de DataX.

Tipo interno de DataX	Tipo de dato de Phoenix
long	INTEGER, TINYINT, SMALLINT, BIGINT
double	FLOAT, DECIMAL, DOUBLE
string	CHAR, VARCHAR
date	DATE, TIME, TIMESTAMP
bytes	BINARY, VARBINARY
boolean	BOOLEAN

Escritura por lotes

Esta tabla enumera los tipos de datos que admite HBase Writer.

Nota

El tipo de datos configurado de cada columna debe coincidir con el tipo de datos correspondiente en la tabla HBase.
Solo se admiten los tipos de datos enumerados en la tabla.

Categoría	Tipo de dato de base de datos
Entero	INT, LONG y SHORT
Punto flotante	FLOAT y DOUBLE
Booleano	BOOLEAN
Cadena	STRING

Precauciones

Si encuentra el error "tried to access method com.google.common.base.Stopwatch" al probar la conectividad, agregue la propiedad hbaseVersion a la configuración del origen de datos para especificar la versión de HBase.

Agregar un origen de datos

Antes de desarrollar una tarea de sincronización en DataWorks, debe agregar el origen de datos requerido siguiendo las instrucciones en Data source configuration. Puede consultar las descripciones de parámetros en la consola de DataWorks para comprender el significado de los parámetros al agregar un origen de datos.

Desarrollar una tarea de sincronización de datos

Para obtener información sobre el punto de entrada y el procedimiento para configurar una tarea de sincronización, consulte las siguientes guías de configuración.

Configurar sincronización por lotes de tabla única

Para más detalles, consulte Codeless UI configuration y script mode configuration.

Dado que HBase es un origen de datos sin esquema, la interfaz sin código no muestra las asignaciones de campos de forma predeterminada. Debe configurarlas manualmente.

Al utilizar HBase como origen de datos, primero debe seleccionar un Output Mode: modo normal o modo multiVersionFixedColumn.

La configuración de asignación de campos difiere para cada modo:
- Modo normal: Es el modo predeterminado. Este modo lee una tabla HBase como una tabla bidimensional estándar y recupera la versión más reciente de los datos. Al usar HBase como origen de datos, debe configurar la asignación entre el Source Field y el Target Field. Los campos de origen y destino tienen una asignación uno a uno. Como la tabla de origen no tiene campos fijos, los campos se asignan por su orden de forma predeterminada. Para cambiar la asignación, debe editar manualmente el orden de los campos.
  
  New version
  
  En la configuración de asignación de campos, las asignaciones son: rowkey → rowkey, basic:age → age, basic:name → name, score:english → english y score:math → math. Los campos de origen se muestran en formato JSON e incluyen las propiedades name y type (ambas son string).
  
  Legacy version
  
  En la configuración de asignación de campos, los campos de origen se muestran en el formato Type|ColumnFamily:ColumnName, que incluye string|rowkey, string|basic:age, string|basic:name, string|score:english y string|score:math. Estos se asignan a los campos de destino rowkey, age, name, english y math, respectivamente.
  
  La tabla de destino contiene campos como rowkey, age, name, english, math y pt. Por ejemplo: rowkey=s001, age=20, name=Tom, english=90, math=85, pt=222222.
- Modo multiVersionFixedColumn: Cada registro de salida consta de cuatro columnas (rowKey, family:qualifier, timestamp y value), y este modo permite leer múltiples versiones de datos. El Source Field se configura en el formato ColumnFamily:Qualifier, como basic:age. La tabla de destino tiene cuatro columnas fijas: row_key, cf, timestamp_col y value. No se requiere configuración de asignación.
  
  New version
  
  En el área de asignación de campos, asigne los campos de origen a los campos de destino. Los campos de origen están en formato JSON. Ejemplos de asignaciones: {"name":"rowkey","type":"string"} se asigna al campo de destino rowkey, {"name":"basic:age","type":"string"} se asigna a family, {"name":"basic:name","type":"string"} se asigna a timestamp y {"name":"score:english","type":"string"} se asigna a value. El sistema no sincroniza el campo de origen no asignado {"name":"score:math","type":"string"}. Puede hacer clic en el botón Edit en cualquiera de los lados para editar los campos de origen y destino respectivamente.
  
  Legacy version
  
  En el área de asignación de campos, el source field incluye string|rowkey, string|basic:age, string|basic:name, string|score:english y string|score:math. El target field incluye rowkey, family, timestamp y value. Los campos de origen y destino se asignan fila por fila.
  
  La tabla de destino contiene cuatro columnas fijas: row_key, cf, timestamp_col y value. Por ejemplo: row_key=s001, cf=basic:age, timestamp_col=1234567890, value=20.
- Al utilizar HBase como destino de datos (solo se admite el modo normal), debe configurar el Target Field y rowkey. Puede formar el campo rowkey concatenando varios campos de origen.
Para ver parámetros y ejemplos de scripts para el modo script, consulte Appendix: Script examples and parameter descriptions.

Preguntas frecuentes

P: ¿Cuál es una configuración de concurrencia adecuada? ¿Ayuda aumentar la concurrencia cuando la velocidad de importación es lenta?

R: El tamaño predeterminado del montículo para Java Virtual Machine (JVM) en un proceso de importación de datos es de 2 GB. La concurrencia se implementa mediante subprocesos múltiples y se configura según el número de canales. Un exceso de subprocesos puede degradar el rendimiento sin mejorar la velocidad de importación debido a la recolección frecuente de basura. Se recomienda utilizar entre 5 y 10 subprocesos concurrentes (canales).
P: ¿Cuál es un valor óptimo para batchSize?

R: El valor predeterminado es 256. Calcule el batchSize óptimo según el tamaño de la fila. Un solo lote debería contener típicamente entre 2 y 4 MB de datos. Divida este volumen de datos entre el tamaño de la fila para determinar el batchSize recomendado.
P: Al leer datos de HBase en modo multiVersionFixedColumn, recibo un error java.lang.StringIndexOutOfBoundsException: String index out of range: -1. ¿Cómo puedo resolverlo?

R: Este error suele ocurrir porque el campo name en la configuración de columnas no sigue el formato columnFamily:qualifier (columnFamily:qualifier). Por ejemplo, podría haber especificado solo el calificador, como age, en lugar de basic:age. Para resolver esto, asegúrese de que el name de cada columna, excepto rowkey, tenga el formato columnFamily:qualifier.

Apéndice: Script de ejemplo y parámetros

Configurar una tarea de sincronización por lotes mediante el editor de código

Si desea configurar una tarea de sincronización por lotes mediante el editor de código, debe configurar los parámetros relacionados en el script basándose en los requisitos unificados de formato de script. Para más información, consulte Script mode configuration. La siguiente información describe los parámetros que debe configurar para los orígenes de datos cuando configura una tarea de sincronización por lotes mediante el editor de código.

Ejemplo de HBase Reader

{
    "type":"job",
    "version":"2.0",// The version number.
    "steps":[
        {
            "stepType":"hbase",// The plugin name.
            "parameter":{
                "mode":"normal",// Specifies the mode for reading data from HBase. Valid values: `normal` and `multiVersionFixedColumn`.
                "scanCacheSize":"256",// Specifies the number of rows to fetch from the server per RPC.
                "scanBatchSize":"100",// Specifies the number of columns to fetch from the server per RPC. 
                "hbaseVersion":"094x/11x",// The HBase version.
                "column":[// The fields to read.
                    {
                        "name":"rowkey",// The field name.
                        "type":"string"// The data type.
                    },
                    {
                        "name":"basic:age",
                        "type":"string"
                    },
                    {
                        "name":"basic:name",
                        "type":"string"
                    },
                    {
                        "name":"score:english",
                        "type":"string"
                    },
                    {
                        "name":"score:math",
                        "type":"string"
                    }
                ],
                "range":{// Specifies the rowkey range to read.
                    "endRowkey":"",// The end rowkey.
                    "isBinaryRowkey":true,// Specifies whether to use binary conversion for startRowkey and endRowkey. The default value is false.
                    "startRowkey":""// The start rowkey.
                },
                "maxVersion":"",// Specifies the number of versions to read in multi-version mode.
                "encoding":"UTF-8",// The encoding format.
                "table":"student",// The table name.
                "hbaseConfig":{// The connection configuration for the HBase cluster, in JSON format.
                    "hbase.zookeeper.quorum":"hostname",
                    "hbase.rootdir":"hdfs://ip:port/database",
                    "hbase.cluster.distributed":"true"
                }
            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"odps",// The plugin name for the destination. This example uses MaxCompute. You can replace it with another Writer plugin.
            "parameter":{
                "partition":"",// Partition information for the destination table. Not required for non-partitioned tables.
                "truncate":true,// Specifies whether to clear the destination table or partition before writing data.
                "datasource":"odps_datasource",// The MaxCompute data source name.
                "column":[// The destination fields.
                    "rowkey",
                    "basic_age",
                    "basic_name",
                    "score_english",
                    "score_math"
                ],
                "table":"student_target"// The name of the destination MaxCompute table.
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"// The maximum number of error records to allow before the job fails.
        },
        "speed":{
            "throttle":true,// Specifies whether to enable rate limiting. If set to false, the mbps parameter is ignored.
            "concurrent":1,// The number of concurrent jobs.
            "mbps":"12"// The rate limit in megabytes per second (MB/s).
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

Script de HBase Reader (modo multiVersionFixedColumn)

El siguiente ejemplo muestra un script completo para leer datos de HBase en modo multiVersionFixedColumn y escribirlos en MaxCompute. En este modo, el valor de cada celda en HBase se convierte en un registro independiente. Cada registro consta de cuatro columnas: rowkey, family:qualifier, timestamp y value.

{
    "type":"job",
    "version":"2.0",
    "steps":[
        {
            "stepType":"hbase",// Plugin name.
            "parameter":{
                "mode":"multiVersionFixedColumn",// The mode for reading data from HBase. This example uses multiVersionFixedColumn mode.
                "scanCacheSize":"256",// The number of rows that the HBase client reads from the server in each remote procedure call (RPC).
                "scanBatchSize":"100",// The number of columns that the HBase client reads from the server in each RPC.
                "hbaseVersion":"20x",// HBase version.
                "datasource":"hbase_datasource",// HBase data source name.
                "column":[// The columns to read. The first column must be rowkey. The names of other columns must be in the "column family:qualifier" format.
                    {
                        "name":"rowkey",// The rowkey column.
                        "type":"string"
                    },
                    {
                        "name":"basic:age",// The age column in the basic column family.
                        "type":"string"
                    },
                    {
                        "name":"basic:name",// The name column in the basic column family.
                        "type":"string"
                    },
                    {
                        "name":"score:english",// The english column in the score column family.
                        "type":"string"
                    },
                    {
                        "name":"score:math",// The math column in the score column family.
                        "type":"string"
                    }
                ],
                "range":{
                    "isBinaryRowkey":false
                },
                "maxVersion":"-1",// The maximum number of versions to read. This parameter is required in multiVersionFixedColumn mode. A value of -1 specifies that all versions are read.
                "encoding":"UTF-8",// Encoding format.
                "table":"student"// HBase table name.
            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"odps",// The name of the destination plugin. This example uses MaxCompute.
            "parameter":{
                "partition":"",// The partition of the destination table. This parameter is not required for non-partitioned tables.
                "truncate":true,// If set to true, this clears the destination table or partition before writing data.
                "datasource":"odps_datasource",// MaxCompute data source name.
                "column":[// The destination has four fixed columns that correspond to the rowkey, family:qualifier, timestamp, and value from the source, respectively.
                    "row_key",
                    "cf",
                    "timestamp_col",
                    "value"
                ],
                "table":"hbase_multiversion_target"// The name of the destination MaxCompute table.
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"// The maximum number of error records allowed.
        },
        "speed":{
            "throttle":false,// No rate limiting.
            "concurrent":2// Job concurrency.
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}