文档

OSS-HDFS数据源

更新时间:

OSS-HDFS服务(JindoFS服务)是一款云原生数据湖存储产品,OSS-HDFS数据源为您提供读取和写入OSS-HDFS的双向通道,本文为您介绍DataWorks的OSS-HDFS数据同步的能力支持情况。

使用限制

离线读

  • 使用OSS-HDFS Reader时,请注意以下事项:

    由于连通资源组到OSS-HDFS的网络链路比较复杂,建议您使用独享数据集成资源组完成数据同步任务。您需要确保您的独享数据集成资源组具备OSS-HDFS的网络访问能力。

  • OSS-HDFS Reader支持以下功能:

    • 支持text、csv、orc和parquet格式的文件,且要求文件内容存放的是一张逻辑意义上的二维表。

    • 支持多种类型数据读取,支持列常量。

    • 支持递归读取、支持通配符*?

    • 多个File可以支持并发读取。

重要

OSS-HDFS Reader暂不支持单个File多线程并发读取,此处涉及到单个File内部切分算法。

离线写

使用OSS-HDFS Writer时,请注意以下事项:

  • 目前OSS-HDFS Writer仅支持text、orc和parquet三种格式的文件,且文件内容存放的必须是一张逻辑意义上的二维表。

  • 对于text类型,需要保证写入OSS-HDFS文件的分隔符与在Hive上创建表时的分隔符一致,从而实现写入OSS-HDFS数据与Hive表字段关联。

实时写

  • 支持实时写入的能力。

  • 支持实时写入Hudi格式版本:0.14.x。

实现过程

OSS-HDFS Writer的实现过程如下所示:

  1. 根据您指定的path,创建一个OSS-HDFS文件系统上不存在的临时目录。

    创建规则:path_随机

  2. 将读取的文件写入这个临时目录。

  3. 全部写入后,将临时目录下的文件移动到您指定的目录(在创建文件时保证文件名不重复)。

  4. 删除临时目录。如果在此过程中,发生网络中断等情况造成无法与OSS-HDFS建立连接,需要您手动删除已经写入的文件和临时目录。

支持的字段类型

离线读

ParquetFile、ORCFile、TextFile、CsvFile中的类型,会默认转为数据集成支持的内部类型,如下表所示。

类型分类

OSS-HDFS数据类型

整数类

TINYINT、SMALLINT、INT、BIGINT

浮点类

FLOAT、DOUBLE、DECIMAL

字符串类

STRING、CHAR、VARCHAR

日期时间类

DATE、TIMESTAMP

布尔类

BOOLEAN

说明
  • LONG:OSS-HDFS文件中的整型类型数据,例如123456789

  • DOUBLE:OSS-HDFS文件中的浮点类型数据,例如3.1415

  • BOOLEAN:OSS-HDFS文件中的布尔类型数据,例如truefalse,不区分大小写。

  • DATE:OSS-HDFS文件中的时间类型数据,例如2014-12-31 00:00:00

离线写

OSS-HDFS Writer提供向OSS-HDFS文件系统指定路径中写入TextFile文件、 ORCFile文件以及ParquetFile格式文件。

OSS-HDFS支持的数据类型,如下表所示。

类型分类

OSS-HDFS数据类型

整数类

TINYINT、SMALLINT、INT和BIGINT

浮点类

FLOAT和DOUBLE

字符串类

CHAR、VARCHAR和STRING

布尔类

BOOLEAN

日期时间类

DATE和TIMESTAMP

数据同步任务开发

OSS-HDFS数据同步任务的配置入口和通用配置流程指导可参见下文的配置指导,详细的配置参数解释可在配置界面查看对应参数的文案提示。

创建数据源

在进行数据同步任务开发时,您需要在DataWorks上创建OSS-HDFS数据源,操作流程请参见创建并管理数据源

单表离线同步任务配置指导

单表实时同步任务配置指导

操作流程请参见配置单表增量数据实时同步DataStudio侧实时同步任务配置

整库(实时)全增量同步配置指导

操作流程请参见数据集成侧同步任务配置

附录:OSS-HDFS脚本Demo与参数说明

附录:离线任务脚本配置方式

如果您配置离线任务时使用脚本模式的方式进行配置,您需要在任务脚本中按照脚本的统一格式要求编写脚本中的reader参数和writer参数,脚本模式的统一要求请参见通过脚本模式配置离线同步任务,以下为您介绍脚本模式下的数据源的Reader参数和Writer参数的指导详情。

Reader脚本Demo

{
    "type": "job",
    "version": "2.0",
    "steps": [
        {
            "stepType": "oss_hdfs",//插件名
            "parameter": {
                "path": "",//要读取的文件路径
                "datasource": "",//数据源
                "column": [
                    {
                        "index": 0,//序列号,index从0开始(下标索引从0开始计数),表示从本地文本文件第一列开始读取数据。
                        "type": "string"//字段类型
                    },
                    {
                        "index": 1,
                        "type": "long"
                    },
                    {
                        "index": 2,
                        "type": "double"
                    },
                    {
                        "index": 3,
                        "type": "boolean"
                    },
                    {
                        "format": "yyyy-MM-dd HH:mm:ss", //日期格式
                        "index": 4,
                        "type": "date"
                    }
                ],
                "fieldDelimiter": ",",//列分隔符
                "encoding": "UTF-8",//编码格式
                "fileFormat": ""//文本类型
            },
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "stream",
            "parameter": {},
            "name": "Writer",
            "category": "writer"
        }
    ],
    "setting": {
        "errorLimit": {
            "record": ""//错误记录数
        },
        "speed": {
            "concurrent": 3,//作业并发数
            "throttle": true //当throttle值为false时,mbps参数不生效,表示不限流;当throttle值为true时,表示限流。
            "mbps":"12"//限流,此处1mbps = 1MB/s。
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Reader脚本参数

参数

描述

是否必选

默认值

path

要读取的文件路径。

  • 当指定单个OSS-HDFS文件时,OSS-HDFS Reader暂时只能使用单线程进行数据抽取。

  • 当指定多个OSS-HDFS文件时,OSS-HDFS Reader支持使用多线程进行数据抽取,线程并发数通过作业并发数concurrent指定。 如果要读取多个文件,可以使用简单正则表达式匹配,例如/hadoop/data_201704*。如果文件以时间命名且较为规律,则可以结合调度参数使用,调度参数将根据业务时间动态替换,详情请参见调度参数支持的格式

    说明

    实际启动的并发数是您的OSS-HDFS待读取文件数量和您配置作业并发数两者中的小者。

  • 当指定通配符,OSS-HDFS Reader尝试遍历出多个文件信息。例如指定/代表读取/目录下所有的文件,指定/oss-hdfs/代表读取oss-hdfs目录下游所有的文件。OSS-HDFS Reader目前只支持*?作为文件通配符,语法类似于通常的Linux命令行文件通配符。

重要
  • 数据集成会将一个同步作业所有待读取文件视作同一张数据表。您必须自己保证所有的File能够适配同一套schema信息。

  • 您需要在配置OSS-HDFS数据源时填写的AK具有对应OSS-HDFS的读取权限。

fileFormat

文件的类型,目前仅支持您配置为textorcparquet

OSS-HDFS Reader能够自动识别文件的类型,并使用对应文件类型的读取策略。OSS-HDFS Reader在做数据同步前,会检查您配置的路径下所有需要同步的文件格式是否和fileFormat一致,如果不一致任务会失败。

fileFormat可以配置的参数值列表如下所示:

  • text:表示TEXT文件格式。

  • orc:表示ORC文件格式。

  • csv:表示普通OSS-HDFS文件格式(逻辑二维表)。

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

column

要读取的字段列表。默认情况下,您可以全部按照STRING类型读取数据,配置为"column": ["*"]

您也可以指定column字段信息,配置如下。其中:

  • type:指定源数据的类型。

  • index:指定当前列来自于文本第几列(以0开始)。

  • value:指定当前类型为常量,不从源头文件读取数据,而是根据value值自动生成对应的列。

说明

文件数据列(index)和常量列(value)配置二选一。

{
  "type": "long",
  "index": 0
  //从本地文件文本第一列(下标索引从0开始计数)获取LONG字段,index表示从数据文件中获取列数据。
},
{
  "type": "string",
  "value": "alibaba"
  //HDFS Reader内部生成alibaba的字符串字段作为当前字段,value表示常量列。
}

fieldDelimiter

读取的字段分隔符,OSS-HDFS Reader在读取TextFile数据时,需要指定字段分割符,如果不指定默认为逗号(,)。OSS-HDFS Reader在读取ORC/PARQUET时,您无需指定字段分割符。

,

encoding

读取文件的编码配置。

utf-8

nullFormat

文本文件中无法使用标准字符串定义null(空指针),数据集成提供nullFormat定义哪些字符串可以表示为null。

例如您配置nullFormat:"null",如果源头数据是null,数据集成会将其视作null字段。

compress

目前仅支持gzip、bzip2和snappy压缩。

Writer脚本Demo

{
    "type": "job",
    "version": "2.0",//版本号。
    "steps": [
        {
            "stepType": "stream",
            "parameter": {},
            "name": "Reader",
            "category": "reader"
        },
        {
            "stepType": "oss_hdfs",//插件名。
            "parameter": {
                "path": "",//存储到OSS-HDFS文件系统的路径信息。
                "fileName": "",//OSS-HDFS Writer写入时的文件名。
                "compress": "",//OSS-HDFS文件压缩类型。
                "datasource": "",//数据源。
                "column": [
                    {
                        "name": "col1",//字段名。
                        "type": "string"//字段类型。
                    },
                    {
                        "name": "col2",
                        "type": "int"
                    },
                    {
                        "name": "col3",
                        "type": "double"
                    },
                    {
                        "name": "col4",
                        "type": "boolean"
                    },
                    {
                        "name": "col5",
                        "type": "date"
                    }
                ],
                "writeMode": "",//写入模式。
                "fieldDelimiter": ",",//列分隔符。
                "encoding": "",//编码格式。
                "fileFormat": "text"//文本类型。
            },
            "name": "Writer",
            "category": "writer"
        }
    ],
    "setting": {
        "errorLimit": {
            "record": ""//错误记录数。
        },
        "speed": {
            "concurrent": 3,//作业并发数。
            "throttle": false //false代表不限流,下面的限流的速度不生效;true代表限流。
        }
    },
    "order": {
        "hops": [
            {
                "from": "Reader",
                "to": "Writer"
            }
        ]
    }
}

Writer脚本参数

参数

描述

是否必选

默认值

fileFormat

文件的类型,目前仅支持您配置为textorcparquet

  • text:表示文件写入类型为text文件格式。

  • orc:表示文件写入类型为orc文件格式。

  • parquet:表示文件写入类型为parquet文件格式。

path

存储到OSS-HDFS文件系统的路径信息,OSS-HDFS Writer会根据并发配置在path目录下写入多个文件。

与Hive表关联时,请填写Hive表在OSS-HDFS上的存储路径。例如Hive上设置的数据仓库的存储路径。

fileName

OSS-HDFS Writer写入时的文件名,实际执行时会在该文件名后添加随机的后缀作为每个线程写入实际文件名。

column

写入数据的字段,不支持对部分列写入。

与Hive中的表关联时,需要指定表中所有字段名和字段类型,其中name指定字段名,type指定字段类型。

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

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

是(如果fileFormat为parquet,此项无需填写)

writeMode

OSS-HDFS Writer写入前数据清理处理模式:

  • append:写入前不做任何处理,数据集成OSS-HDFS Writer直接使用filename写入,并保证文件名不冲突。

  • nonConflict:如果目录下有fileName前缀的文件,直接报错。

  • truncate:写入前清理fileName名称前缀匹配的所有文件。例如,"fileName": "abc",将清理对应目录所有abc开头的文件。

fieldDelimiter

OSS-HDFS Writer写入时的字段分隔符。

说明

仅支持单字符分隔符,如果输入多字符将导致运行时报错。

是(如果fileFormat为parquet,此项无需填写)

compress

OSS-HDFS文件压缩类型,默认不填写,则表示没有压缩。

其中text类型文件支持gzip和bzip2压缩类型。

encoding

写文件的编码配置。

utf-8

parquetSchema

写Parquet格式文件时的必填项,用来描述目标文件的结构,所以此项当且仅当fileFormatparquet时生效,格式如下。

message Message名 {
是否必填 数据类型 列名;
.....................;
}

配置项说明如下:

  • Message名:输入名称。

  • 是否必填: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;
}