參數

描述

是否必選

默認值

path

要讀取的文件路徑，如果要讀取多個文件，可以使用簡單正則表達式匹配，例如/hadoop/data_201704*，如果文件以時間命名且較為規律，則可以結合調度參數使用，調度參數將根據業務時間動態替換，詳情請參見調度參數支持的格式：

• 當指定單個HDFS文件時，HDFS Reader暫時只能使用單線程進行數據抽取。

• 當指定多個HDFS文件時，HDFS Reader支持使用多線程進行數據抽取，線程并發數通過作業并發數concurrent指定。

  說明

  實際啟動的并發數是您的HDFS待讀取文件數量和您配置作業并發數兩者中的小者。

• 當指定通配符，HDFS Reader嘗試遍歷出多個文件信息。例如指定/代表讀取/目錄下所有的文件，指定/bazhen/代表讀取bazhen目錄下游所有的文件。HDFS Reader目前只支持*和?作為文件通配符，語法類似于通常的Linux命令行文件通配符。

請注意以下事項：

• 數據集成會將一個同步作業所有待讀取文件視作同一張數據表。您必須自己保證所有的File能夠適配同一套schema信息，并且提供給數據集成權限可讀。

• 注意分區讀取：Hive在建表時，可以指定分區。例如創建分區partition(day="20150820", hour="09")，對應的HDFS文件系統中，相應的表的目錄下則會多出/20150820和/09兩個目錄且/20150820是/09的父目錄。

  分區會列成相應的目錄結構，在按照某個分區讀取某個表所有數據時，則只需配置好JSON中path的值即可。例如需要讀取表名叫mytable01下分區day為20150820這一天的所有數據，則配置如下。

  "path": "/user/hive/warehouse/mytable01/20150820/*"

是

無

defaultFS

Hadoop HDFS文件系統namenode節點地址。公共資源組不支持Hadoop高級參數HA的配置。

是

無

fileType

文件的類型，目前僅支持您配置為TEXT、ORC、RC、SEQ、CSV和parquet。HDFS Reader能夠自動識別文件的類型，并使用對應文件類型的讀取策略。HDFS Reader在做數據同步前，會檢查您配置的路徑下所有需要同步的文件格式是否和fileType一致，如果不一致任務會失敗。

fileType可以配置的參數值列表如下所示：

• TEXT：表示TextFile文件格式。

• ORC：表示ORCFile文件格式。

• RC：表示RCFile文件格式。

• SEQ：表示SequenceFile文件格式。

• CSV：表示普通HDFS文件格式（邏輯二維表）。

• PARQUET：表示普通Parquet文件格式。

由于TextFile和ORCFile是兩種不同的文件格式，所以HDFS Reader對這兩種文件的解析方式也存在差異，這種差異導致Hive支持的復雜復合類型（例如map、array、struct和union）在轉換為數據集成支持的String類型時，轉換的結果格式略有差異，以map類型為例：

• ORCFile map類型經HDFS Reader解析，轉換成數據集成支持的STRING類型后，結果為{job=80, team=60, person=70}。

• TextFile map類型經HDFS Reader解析，轉換成數據集成支持的STRING類型后，結果為{job:80, team:60, person:70}。

如上述轉換結果所示，數據本身沒有變化，但是表示的格式略有差異。所以如果您配置的文件路徑中要同步的字段在Hive中是復合類型的話，建議配置統一的文件格式 。

最佳實踐建議：

• 如果需要統一復合類型解析出來的格式，建議您在Hive客戶端將TextFile格式的表導成ORCFile格式的表。

• 如果是Parquet文件格式，后面的parquetSchema則必填，此屬性用來說明要讀取的Parquet格式文件的格式。

對于您指定的column信息，type必須填寫，index和value必須選擇其一。

是

無

column

讀取字段列表，type指定源數據的類型，index指定當前列來自于文本第幾列（以0開始），value指定當前類型為常量。不從源頭文件讀取數據，而是根據value值自動生成對應的列。默認情況下，您可以全部按照STRING類型讀取數據，配置為"column": ["*"]。

您也可以指定column字段信息（文件數據列和常量列配置二選一），配置如下。

{
  "type": "long",
  "index": 0
  //從本地文件文本第一列（下標索引從0開始計數）獲取INT字段，index表示從數據文件中獲取列數據。
},
{
  "type": "string",
  "value": "alibaba"
  //HDFS Reader內部生成alibaba的字符串字段作為當前字段，value表示常量列。
}

是

無

fieldDelimiter

讀取的字段分隔符，HDFS Reader在讀取TextFile數據時，需要指定字段分割符，如果不指定默認為逗號（,）。HDFS Reader在讀取ORCFile時，您無需指定字段分割符，Hive本身的默認分隔符為\u0001。

否

,

encoding

讀取文件的編碼配置。

否

utf-8

nullFormat

文本文件中無法使用標準字符串定義null（空指針），數據集成提供nullFormat定義哪些字符串可以表示為null。

例如您配置nullFormat:"null"，如果源頭數據是null，數據集成會將其視作null字段。

否

無

compress

當fileType（文件類型）為csv下的文件壓縮方式，目前僅支持gzip、bz2、zip、lzo、lzo_deflate、hadoop-snappy和framing-snappy壓縮。

否

無

parquetSchema

否

無

csvReaderConfig

讀取CSV類型文件參數配置，Map類型。讀取CSV類型文件使用的CsvReader進行讀取，會有很多配置，不配置則使用默認值。

常見配置如下所示。

"csvReaderConfig":{
  "safetySwitch": false,
  "skipEmptyRecords": false,
  "useTextQualifier": false
}

所有配置項及默認值，配置時csvReaderConfig的map中請嚴格按照以下字段名字進行配置。

boolean caseSensitive = true;
char textQualifier = 34;
boolean trimWhitespace = true;
boolean useTextQualifier = true;//是否使用csv轉義字符。
char delimiter = 44;//分隔符
char recordDelimiter = 0;
char comment = 35;
boolean useComments = false;
int escapeMode = 1;
boolean safetySwitch = true;//單列長度是否限制100,000字符。
boolean skipEmptyRecords = true;//是否跳過空行。
boolean captureRawRecord = true;

否

無

hadoopConfig

hadoopConfig中可以配置與Hadoop相關的一些高級參數，例如HA的配置。公共資源組不支持Hadoop高級參數HA的配置。

"hadoopConfig":{
"dfs.nameservices": "testDfs",
"dfs.ha.namenodes.testDfs": "namenode1,namenode2",
"dfs.namenode.rpc-address.youkuDfs.namenode1": "",
"dfs.namenode.rpc-address.youkuDfs.namenode2": "",
"dfs.client.failover.proxy.provider.testDfs": "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider",
"dfs.data.transfer.protection": "integrity",
"dfs.datanode.use.datanode.hostname" :"true",
"dfs.client.use.datanode.hostname":"true"
}

"hadoopConfig":{ "dfs.data.transfer.protection": "integrity", "dfs.datanode.use.datanode.hostname" :"true", "dfs.client.use.datanode.hostname":"true" }

否

無

haveKerberos

是否有Kerberos認證，默認為false。例如用戶配置為true，則配置項kerberosKeytabFilePath和kerberosPrincipal為必填。

否

false

kerberosKeytabFilePath

Kerberos認證keytab文件的絕對路徑。如果haveKerberos為true，則必選。

否

無

kerberosPrincipal

Kerberos認證Principal名，如****/hadoopclient@**.*** 。如果haveKerberos為true，則必選。

"haveKerberos":true,
"kerberosKeytabFilePath":"/opt/datax/**.keytab",
"kerberosPrincipal":"**/hadoopclient@**.**"

否

無

參數

描述

是否必選

默認值

defaultFS

Hadoop HDFS文件系統namenode節點地址，例如hdfs://127.0.0.1:9000。公共資源組不支持Hadoop高級參數HA的配置，請新增和使用自定義數據集成資源組。

是

無

fileType

文件的類型，目前僅支持您配置為text、orc和parquet：

• text：表示Hive中的存儲表，TextFile文件格式。

• orc：表示Hive中的壓縮表，ORCFile文件格式。

• parquet：表示普通Parquet File文件格式。

是

無

path

存儲到Hadoop HDFS文件系統的路徑信息，HDFS Writer會根據并發配置在path目錄下寫入多個文件。

為了與Hive表關聯，請填寫Hive表在HDFS上的存儲路徑。例如Hive上設置的數據倉庫的存儲路徑為/user/hive/warehouse/，已建立數據庫test表hello，則對應的存儲路徑為/user/hive/warehouse/test.db/hello。

是

無

fileName

HDFS Writer寫入時的文件名，實際執行時會在該文件名后添加隨機的后綴作為每個線程寫入實際文件名。

是

無

column

寫入數據的字段，不支持對部分列寫入。

為了與Hive中的表關聯，需要指定表中所有字段名和字段類型，其中name指定字段名，type指定字段類型。

您可以指定column字段信息，配置如下。

"column": 
[
    {
        "name": "userName",
        "type": "string"
    },
    {
        "name": "age",
        "type": "long"
    }
]

是（如果filetype為parquet，此項無需填寫）

無

writeMode

HDFS Writer寫入前數據清理處理模式：

• append：寫入前不做任何處理，數據集成HDFS Writer直接使用filename寫入，并保證文件名不沖突。

• nonConflict：如果目錄下有fileName前綴的文件，直接報錯。

• truncate：寫入前清理fileName名稱前綴匹配的所有文件。例如，"fileName": "abc"，將清理對應目錄所有abc開頭的文件。

是

無

fieldDelimiter

HDFS Writer寫入時的字段分隔符，需要您保證與創建的Hive表的字段分隔符一致，否則無法在Hive表中查到數據。

是（如果filetype為parquet，此項無需填寫）

無

compress

HDFS文件壓縮類型，默認不填寫，則表示沒有壓縮。

其中text類型文件支持gzip和bzip2壓縮類型。

否

無

encoding

寫文件的編碼配置。

否

無壓縮

parquetSchema

寫Parquet格式文件時的必填項，用來描述目標文件的結構，所以此項當且僅當fileType為parquet時生效，格式如下。

message MessageType名 {
是否必填, 數據類型, 列名;
......................;
}

配置項說明如下：

• MessageType名：填寫名稱。

• 是否必填：required表示非空，optional表示可為空。推薦全填optional。

• 數據類型：Parquet文件支持BOOLEAN、INT32、INT64、INT96、FLOAT、DOUBLE、BINARY（如果是字符串類型，請填BINARY）和FIXED_LEN_BYTE_ARRAY等類型。

示例如下。

message m {
optional int64 id;
optional int64 date_id;
optional binary datetimestring;
optional int32 dspId;
optional int32 advertiserId;
optional int32 status;
optional int64 bidding_req_num;
optional int64 imp;
optional int64 click_num;
}

否

無

hadoopConfig

hadoopConfig中可以配置與Hadoop相關的一些高級參數，例如HA的配置。公共資源組不支持Hadoop高級參數HA的配置，請新增和使用自定義數據集成資源組。

"hadoopConfig":{
"dfs.nameservices": "testDfs",
"dfs.ha.namenodes.testDfs": "namenode1,namenode2",
"dfs.namenode.rpc-address.youkuDfs.namenode1": "",
"dfs.namenode.rpc-address.youkuDfs.namenode2": "",
"dfs.client.failover.proxy.provider.testDfs": "org.apache.hadoop.hdfs.server.namenode.ha.ConfiguredFailoverProxyProvider"
}

否

無

dataxParquetMode

針對Parquet文件進行同步的模式。使用fields支持array、map和struct等復雜類型。可選值包括fields和columns。

配置dataxParquetMode為fields時，支持hdfs over oss，即HDFS的存儲為OSS，OSS的數據存儲格式為parquet。此時您可以在hadoopConfig中增加OSS相關的參數，詳情如下：

• fs.oss.accessKeyId：訪問OSS的AccessKeyID。

• fs.oss.accessKeySecret：訪問OSS的AccessKeySecret。

• fs.oss.endpoint：訪問OSS的endpoint。

訪問OSS的示例如下所示。

```json
    "writer": {
    "name": "hdfswriter",
    "parameter": {
        "defaultFS": "oss://test-bucket",
        "fileType": "parquet",
        "path": "/datasets/oss_demo/kpt",
        "fileName": "test",
        "writeMode": "truncate",
        "encoding": "UTF-8",
        "hadoopConfig": {
            "fs.oss.accessKeyId": "the-access-id",
            "fs.oss.accessKeySecret": "the-access-key",
            "fs.oss.endpoint": "oss-cn-hangzhou.aliyuncs.com"
            },
            "parquetSchema": "message test {\n    required int64 id;\n    optional binary name (UTF8);\n    optional int64 gmt_create;\n    required group map_col (MAP) {\n        repeated group key_value {\n            required binary key (UTF8);\n            required binary value (UTF8);\n        }\n    }\n    required group array_col (LIST) {\n        repeated group list {\n            required binary element (UTF8);\n        }\n    }\n    required group struct_col {\n        required int64 id;\n        required binary name (UTF8);\n    }    \n}",
            "dataxParquetMode": "fields"
            }
        }
    ```

否

columns

haveKerberos

是否有Kerberos認證，默認為false。如果您配置為true，則配置項kerberosKeytabFilePath和kerberosPrincipal為必填。

否

false

kerberosKeytabFilePath

Kerberos認證keytab文件的絕對路徑。

如果haveKerberos為true，則必選。

無

kerberosPrincipal

Kerberos認證Principal名，如****/hadoopclient@**.*** 。如果haveKerberos為true，則必選。

由于Kerberos需要配置keytab認證文件的絕對路徑，您需要在自定義資源組上使用此功能。配置示例如下。

"haveKerberos":true,
"kerberosKeytabFilePath":"/opt/datax/**.keytab",
"kerberosPrincipal":"**/hadoopclient@**.**"

否

無