HDFS数据源

类型分类

数据集成column配置类型

Hive数据类型

整数类

long

tinyint、smallint、int和bigint

浮点类

double

float和double

字符串类

string

string、char、varchar、struct、map、array、union和binary

日期时间类

date

date和timestamp

布尔类

boolean

boolean

类型分类

数据库数据类型

整数类

TINYINT、SMALLINT、INT和BIGINT

浮点类

FLOAT和DOUBLE

字符串类

CHAR、VARCHAR和STRING

布尔类

BOOLEAN

日期时间类

DATE和TIMESTAMP

参数

描述

是否必选

默认值

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@**.**"

否

无