DataWorks：HBase資料來源

HBase Reader

支援normal和multiVersionFixedColumn模式 ，配置方式參見：HBase欄位對應配置指導。。

• normal模式：把HBase中的表當成普通二維表（橫表）進行讀取，擷取最新版本資料。

  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 

  讀取後的資料如下所示。

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

• multiVersionFixedColumn模式：把HBase中的表當成豎表進行讀取。讀出的每條記錄是四列形式，依次為rowKey、family:qualifier、timestamp和value。讀取時需要明確指定要讀取的列，把每一個cell中的值，作為一條記錄（record），若有多個版本則存在多條記錄。

  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 }

  讀取後的資料（4列） 如下所示。

  rowKey	column: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

• rowkey 建置規則：目前HBase Writer支援源端多個欄位拼接作為HBase表的rowkey。

• 寫入HBase的版本（時間戳記）支援：

  • 指定目前時間作為版本。

  • 指定源端列作為版本。

  • 指定一個時間作為版本。

離線讀

• 支援讀取HBase資料類型及HBase Reader針對HBase類型的轉換列表如下表所示。

  類型分類	Data Integrationcolumn配置類型	資料庫資料類型
  整數類	long	short、int和long
  浮點類	double	float和double
  字串類	string	binary_string和string
  日期時間類	date	date
  位元組類	bytes	bytes
  布爾類	boolean	boolean

• HBase20xsql Reader支援大部分Phoenix類型，但也存在個別類型未被支援的情況，請注意檢查您的類型。

• HBase20xsql Reader針對Phoenix類型的轉換列表，如下所示。

  DataX內部類型	Phoenix資料類型
  long	INTEGER、TINYINT、SMALLINT、BIGINT
  double	FLOAT、DECIMAL、DOUBLE
  string	CHAR、VARCHAR
  date	DATE、TIME、TIMESTAMP
  bytes	BINARY、VARBINARY
  boolean	BOOLEAN

離線寫

支援讀取HBase資料類型，HBase Writer針對HBase類型的轉換列表，如下表所示。

單表離線同步任務配置指導

• 操作流程請參見嚮導模式配置、指令碼模式配置。

  使用嚮導模式時，由於HBase為無固定結構的資料來源，預設不會顯示欄位對應，您需要手動設定欄位對應。

  HBase作為資料來源時，首先需要選擇輸出模式：橫表（normal 模式）和豎表（multiVersionFixedColumn 模式）。

  兩種模式下的欄位對應配置方式不同：

  • 橫表（normal）模式：預設模式，將HBase表按普通二維表讀取，擷取最新版本資料。HBase作為資料來源，需要配置來源字段和目標字段的映射關係。源端與目的端欄位為一一映射關係。當前資料來源類型由於源端表無固定欄位，預設為同行映射，如需改變映射關係，需手動編輯欄位順序。

    新版資料開發

    在欄位對應配置中，來源欄位與目標欄位的映射關係為：rowkey → rowkey、basic:age → age、basic:name → name、score:english → english、score:math → math。來源欄位以 JSON 格式展示，包含 name 和 type（均為 string）兩個屬性。

    舊版資料開發

    欄位對應配置中，來源欄位以 類型|列族:列名 格式展示，包括 string|rowkey、string|basic:age、string|basic:name、string|score:english、string|score:math，分別映射至目標欄位 rowkey、age、name、english、math。

    目標表寫入結果包含 rowkey、age、name、english、math、pt 等欄位，樣本資料為：rowkey=s001，age=20，name=Tom，english=90，math=85，pt=222222。

  • 豎表（multiVersionFixedColumn）模式：每條輸出記錄由4列組成（rowKey、family:qualifier、timestamp、value），可讀取多版本資料。來源字段配置格式為：ColumnFamily:Qualifier（如basic:age），目標端為固定的4列表（欄位為如row_key、cf、timestamp_col、value）。配置時，無需關注映射關係。

    新版資料開發

    在欄位對應配置地區，將來源欄位與目標欄位建立映射關係。來源欄位為 JSON 格式，樣本映射如下：{"name":"rowkey","type":"string"} 映射至目標欄位 rowkey，{"name":"basic:age","type":"string"} 映射至 family，{"name":"basic:name","type":"string"} 映射至 timestamp，{"name":"score:english","type":"string"} 映射至 value。未映射的來源欄位 {"name":"score:math","type":"string"} 不參與同步。可單擊兩側的編輯按鈕分別編輯來源欄位和目標欄位。

    舊版資料開發

    在欄位對應配置地區，來源欄位包括 string|rowkey、string|basic:age、string|basic:name、string|score:english、string|score:math，目標欄位包括 rowkey、family、timestamp、value，兩側欄位按行對應排列。

    目標表寫入結果包含固定4列：row_key、cf、timestamp_col、value，樣本資料如：row_key=s001，cf=basic:age，timestamp_col=1234567890，value=20。

  • HBase作為資料去向（僅支援normal模式），需要分別配置目標字段和rowkey。其中，rowkey欄位可以由多個源端欄位拼接而成。

• 指令碼模式配置的全量參數和指令碼Demo請參見下文的附錄：指令碼Demo與參數說明。

離線任務指令碼配置方式

如果您配置離線任務時使用指令碼模式的方式進行配置，您需要按照統一的指令碼格式要求，在任務指令碼中編寫相應的參數，詳情請參見指令碼模式配置，以下為您介紹指令碼模式下資料來源的參數配置詳情。

HBase Reader指令碼Demo

{
    "type":"job",
    "version":"2.0",//版本號碼。
    "steps":[
        {
            "stepType":"hbase",//外掛程式名。
            "parameter":{
                "mode":"normal",//讀取HBase的模式，支援normal模式、multiVersionFixedColumn模式。
                "scanCacheSize":"256",//HBase client每次RPC從伺服器端讀取的行數。
                "scanBatchSize":"100",//HBase client每次RPC從伺服器端讀取的列數。 
                "hbaseVersion":"094x/11x",//HBase版本。
                "column":[//欄位。
                    {
                        "name":"rowkey",//欄位名。
                        "type":"string"//資料類型。
                    },
                    {
                        "name":"basic:age",
                        "type":"string"
                    },
                    {
                        "name":"basic:name",
                        "type":"string"
                    },
                    {
                        "name":"score:english",
                        "type":"string"
                    },
                    {
                        "name":"score:math",
                        "type":"string"
                    }
                ],
                "range":{//指定HBase Reader讀取的rowkey範圍。
                    "endRowkey":"",//指定結束rowkey。
                    "isBinaryRowkey":true,//指定配置的startRowkey和endRowkey轉換為byte[]時的方式，預設值為false。
                    "startRowkey":""//指定開始rowkey。
                },
                "maxVersion":"",//指定在多版本模式下的HBase Reader讀取的版本數。
                "encoding":"UTF-8",//編碼格式。
                "table":"student",//表名。
                "hbaseConfig":{//串連HBase叢集需要的配置資訊，JSON格式。
                    "hbase.zookeeper.quorum":"hostname",
                    "hbase.rootdir":"hdfs://ip:port/database",
                    "hbase.cluster.distributed":"true"
                }
            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"odps",//目標端外掛程式名。此處以MaxCompute為例，您可以根據實際情況替換為其他Writer外掛程式。
            "parameter":{
                "partition":"",//目標表的分區資訊。非分區表無需配置。
                "truncate":true,//寫入前是否清空表或分區中的資料，true表示清空。
                "datasource":"odps_datasource",//MaxCompute資料來源名稱。
                "column":[//目標端欄位列表。
                    "rowkey",
                    "basic_age",
                    "basic_name",
                    "score_english",
                    "score_math"
                ],
                "table":"student_target"//MaxCompute目標表名。
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//錯誤記錄數。
        },
        "speed":{
            "throttle":true,//當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent":1,//作業並發數。
            "mbps":"12"//限流，此處1mbps = 1MB/s。
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

HBase Reader指令碼Demo（multiVersionFixedColumn模式）

以下樣本展示了使用multiVersionFixedColumn模式讀取HBase資料，並寫入MaxCompute的完整指令碼配置。在該模式下，HBase中每個Cell的值將被轉換為一條獨立的記錄，每條記錄由4列組成：rowKey、family:qualifier、timestamp、value。

{
    "type":"job",
    "version":"2.0",
    "steps":[
        {
            "stepType":"hbase",//外掛程式名。
            "parameter":{
                "mode":"multiVersionFixedColumn",//讀取HBase的模式，此處使用multiVersionFixedColumn模式。
                "scanCacheSize":"256",//HBase client每次RPC從伺服器端讀取的行數。
                "scanBatchSize":"100",//HBase client每次RPC從伺服器端讀取的列數。
                "hbaseVersion":"20x",//HBase版本。
                "datasource":"hbase_datasource",//HBase資料來源名稱。
                "column":[//欄位。第一個欄位必須為rowkey，其餘欄位的name必須為"列族:列名"格式。
                    {
                        "name":"rowkey",//rowkey欄位。
                        "type":"string"
                    },
                    {
                        "name":"basic:age",//列族basic下的列age。
                        "type":"string"
                    },
                    {
                        "name":"basic:name",//列族basic下的列name。
                        "type":"string"
                    },
                    {
                        "name":"score:english",//列族score下的列english。
                        "type":"string"
                    },
                    {
                        "name":"score:math",//列族score下的列math。
                        "type":"string"
                    }
                ],
                "range":{
                    "isBinaryRowkey":false
                },
                "maxVersion":"-1",//讀取所有版本資料。multiVersionFixedColumn模式下此參數必填。取值為-1表示讀取所有版本。
                "encoding":"UTF-8",//編碼格式。
                "table":"student"//HBase表名。
            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"odps",//目標端外掛程式名。此處以MaxCompute為例。
            "parameter":{
                "partition":"",//目標表的分區資訊。非分區表無需配置。
                "truncate":true,//寫入前是否清空表或分區中的資料，true表示清空。
                "datasource":"odps_datasource",//MaxCompute資料來源名稱。
                "column":[//目標端固定4列，分別對應rowKey、family:qualifier、timestamp、value。
                    "rowkey",
                    "cf",
                    "timestamp_col",
                    "value"
                ],
                "table":"hbase_multiversion_target"//MaxCompute目標表名。
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//錯誤記錄數。
        },
        "speed":{
            "throttle":false,//不限流。
            "concurrent":2//作業並發數。
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

HBase Reader指令碼參數

HBase Writer指令碼Demo

{
    "type":"job",
    "version":"2.0",//版本號碼
    "steps":[
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"hbase",//外掛程式名。
            "parameter":{
                "mode":"normal",//寫入HBase的模式。
                "walFlag":"false",//關閉（false）放棄寫WAL日誌。
                "hbaseVersion":"094x",//Hbase版本。
                "rowkeyColumn":[//要寫入的HBase的rowkey列。
                    {
                        "index":"0",//序號。
                        "type":"string"//資料類型。
                    },
                    {
                        "index":"-1",
                        "type":"string",
                        "value":"_"
                    }
                ],
                "nullMode":"skip",//讀取的為null值時，如何處理。
                "column":[//要寫入的HBase欄位。
                    {
                        "name":"columnFamilyName1:columnName1",//欄位名。
                        "index":"0",//索引號。
                        "type":"string"//資料類型。
                    },
                    {
                        "name":"columnFamilyName2:columnName2",
                        "index":"1",
                        "type":"string"
                    },
                    {
                        "name":"columnFamilyName3:columnName3",
                        "index":"2",
                        "type":"string"
                    }
                ],
                "encoding":"utf-8",//編碼格式。
                "table":"",//表名。
                "hbaseConfig":{//串連HBase叢集需要的配置資訊，JSON格式。
                    "hbase.zookeeper.quorum":"hostname",
                    "hbase.rootdir":"hdfs: //ip:port/database",
                    "hbase.cluster.distributed":"true"
                }
            },
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//錯誤記錄數。
        },
        "speed":{
            "throttle":true,//當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent":1, //作業並發數。
            "mbps":"12"//限流
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

HBase Writer指令碼參數

"rowkeyColumn": [
          {
            "index":0,
            "type":"string"
          },
          {
            "index":-1,
            "type":"string",
            "value":"_"
          }
      ]

HBase20xsql Reader指令碼Demo

{
    "type":"job",
    "version":"2.0",//版本號碼。
    "steps":[
        {
            "stepType":"hbase20xsql",//外掛程式名。
            "parameter":{
                "queryServerAddress": "http://127.0.0.1:8765",  //填寫串連Phoenix QueryServer地址。
                "serialization": "PROTOBUF",  //QueryServer序列化格式。
                "table": "TEST",    //讀取表名。
                "column": ["ID", "NAME"],   //所要讀取列名。
                "splitKey": "ID"    //切分列，必須是表主鍵。
            },
            "name":"Reader",
            "category":"reader"
        },
        {
            "stepType":"stream",
            "parameter":{},
            "name":"Writer",
            "category":"writer"
        }
    ],
    "setting":{
        "errorLimit":{
            "record":"0"//錯誤記錄數。
        },
        "speed":{
            "throttle":true,//當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent":1,//作業並發數。
            "mbps":"12"//限流，此處1mbps = 1MB/s。
        }
    },
    "order":{
        "hops":[
            {
                "from":"Reader",
                "to":"Writer"
            }
        ]
    }
}

HBase20xsql Reader指令碼參數

HBase11xsql Writer指令碼Demo

{
  "type": "job",
  "version": "1.0",
  "configuration": {
    "setting": {
      "errorLimit": {
        "record": "0"
      },
      "speed": {
            "throttle":true,//當throttle值為false時，mbps參數不生效，表示不限流；當throttle值為true時,表示限流。
            "concurrent":1, //作業並發數。
            "mbps":"1"//限流，此處1mbps = 1MB/s。
      }
    },
    "reader": {
      "plugin": "odps",
      "parameter": {
        "datasource": "",
        "table": "",
        "column": [],
        "partition": ""
      }
    },
    "plugin": "hbase11xsql",
    "parameter": {
      "table": "目標hbase表名，大小寫有關",
      "hbaseConfig": {
        "hbase.zookeeper.quorum": "目標hbase叢集的ZK伺服器位址",
        "zookeeper.znode.parent": "目標hbase叢集的znode"
      },
      "column": [
        "columnName"
      ],
      "batchSize": 256,
      "nullMode": "skip"
    }
  }
}

HBase11xsql Writer指令碼參數