本文适用于 Go 版本的 Ultipa Transporter 客户端工具。
概述
Ultipa Transporter 是命令行下的快速导入导出工具,可以对 Ultipa 图数据库进行远程数据批量导入和导出。
一个命令行可以导入(或导出)多个 点schema 和/或多个 边schema 的文件。
远程操作(需在 yml 文件的 server
中进行相关声明)是针对远程数据库中某个图集的点/边信息进行的数据导入、导出操作,需设置远程主机的 ip 及端口 host
、用户名 username
、密码 password
,支持使用 ssl 协议 crt
。
点/边文件
导入、导出所涉及的点/边数据文件存放于本地,每个文件代表一个 点schema 或一个 边schema;文件内每行数据(除表头)代表一个点/边,每列数据代表点/边的一个属性;导入文件支持 csv、tsv、txt 等格式,支持 ,
、\t
、|
、;
分隔符;导出文件为 csv 格式,以 ,
为分隔符。
文件内的元数据类型(点或边)通过 nodeConfig
和 edgeConfig
来声明。每次导入、导出的多个文件需为同一种格式(及同一种分隔符),需分别声明每个文件内的属性。
导入声明
为所有文件统一指定(需在 yml 文件的 settings
中进行相关声明):文件分隔符 separator
、导入的线程数 threads
、批大小 batchSize
、日志路径 logPath
、导入方式 importMode
等诸多细节参数;导入 csv 或 tsv 时有无表头均可(有表头时列名为 <属性名>
或 <属性名>:<类型>
)。
为每个文件分别指定(需在 yml 文件的 nodeConfig
、edgeConfig
中进行相关声明):该文件的本地存储路径 file
、元数据模式 - schema
、要导入的属性 properties
或 types
、开始导入的位置 skip
、导入条数 limit
。
导入的 csv 或 tsv 文件:
- 无表头时,在
properties
下依次为各列:- 通过
- name
及type
声明属性名称及数据类型; - 通过
- name
无type
声明属性名称及 string 类型; - name
个数小于列数时,小多少就舍弃末尾的多少列;
- 通过
- 有表头时,在
types
下为某些列(顺序不限):- 通过
- name
及type
声明或修改数据类型; - 通过
- name
无type
声明或修改为 string 类型; - name
没出现的列,若列名为<属性名>
则声明为 string 类型,若列名为<属性名>:<类型>
则使用列名中的<类型>
。
- 通过
有效的数据类型 type
包括:
_id
、_uuid
、_from
、_to
、_from_uuid
、_to_uuid
(用来声明系统属性);string
、float
、double
、int32
、uint32
、int64
、uint64
、datetime
、timestamp
;_ignore
(用来忽略该列,不导入)
用户需保证声明的数据类型和实际导入的数据类型一致;如果不一致,例如声明为整数但实际导入了字符串,系统会报错。
导出声明
为所有文件统一指定(需在 yml 文件的 settings
中进行相关声明):导出的 csv 文件的本地存储路径 outPath
;是否生成表头 writeHeder
(生成表头时列名为 <属性名>:<类型>
);导出时程序自动分批,无需设置批大小。
为每个文件分别指定(需在 yml 文件的 nodeConfig
、edgeConfig
中进行相关声明):该文件的元数据模式 - schema
、在 properties
下指定要导出的普通属性 - name
;Ultipa 系统属性将默认导出,无需指定。
点、边基本知识
唯一标识符
点数据有两种唯一标识符:_id
为 32bit 以内的字符串,_uuid
为 uint64 以内的整数;因此,边起点相应的有_from
和 _from_uuid
两种,边终点也相应的有 _to
和 _to_uuid
两种。边数据只有 _uuid
一种唯一标识符。这六个属性为 Ultipa 系统属性,也是声明属性时有效的数据类型。
导入方式
当导入方式 importMode
为 upsert
或 overwrite
时,如果导入的点、边数据在图集中已存在(数据文件中含有唯一标识符,且唯一标志符在目标图集中已存在),则相应执行插入更新或插入覆盖操作;否则(唯一标志符不存在,或数据文件中不含唯一标志符)数据将被视为新的点、边,执行插入操作。
当导入方式 importMode
为 insert
时,仅导入新的点、边数据(不含唯一标识符、或唯一标志符不存在点、边);如果校验发现待导入的点、边已存在则报错。
所有插入操作都会自动生成文件中未包含的唯一标识符。
边的要求及处理
边文件中必须包含边起点、边终点两列数据。
边成功导入的前提是边的起点、终点已经存在;如果不存在,则导入会失败,可以将参数 createNodeIfNotExist
设置为真,让系统新增该点再导入边。
Transporter 如何判断边的起点、终点是否存在?远程导入时,Transporter 会同时在当前图集以及随边文件一同导入的点文件中按照唯一标识符进行查找。
当边文件中没有同时提供起点、终点的四个系统属性,即只提供了 _from
和 _to
或只提供了 _from_uuid
和 _to_uuid
时会怎样?远程导入时,Transporter 会自动转化出另外两个缺失的系统属性。
报错
导入前报错
导入前报错是指在检查配置文件、创建图集或 schema 时发生错误。可能的错误类型有:
- 配置文件的内容不符合 yml 规范;
- 参数配置错误,例如属性名称、数据类型不符合 UQL 规范;
- 创建图集、schema 失败;
导入时报错
导入时报错是指在导入数据的过程中发生错误。可能的错误类型有:
- 服务器返回的错误;
- 网络错误;
- 数据格式错误(表头及数据列不一致);
- 导入数据重复(
insert
时有重复的点、边);
在默认情况下,系统会跳过错误的数据批块,继续导入后面的数据批块;也支持出错即终止的模式(参数 stopWhenError
设置为真),即首个出错的数据批块及其后所有数据都会被跳过。出错时系统会返回错误类型、被跳过数据的起始位置和数据条数;据此,可以在修复数据文件后用参数 skip
声明起始位置,用参数 limit
声明数据条数,重新导入之前被跳过的数据。
上述第 3 种错误类型的常见情况有:
- 对于无表头的文件,在
properties
下声明的- name
个数与文件中的数据列数不一致; - 对于有表头的文件,个别数据列没有列名,或末尾的列名之下没有数据占位;
对于上述情况,如果将参数 fitToHeader
设置为真,可强制以配置文件中的声明(无表头时)、或待导入文件中的列名(有表头时)为准,对数据列进行忽略或补空、补零,此时不会触发第 3 种错误。
命令参数
Ultipa Transporter 分为导入和导出两个工具,即 ultipa-importer
和 ultipa-exporter
。两个工具均有以下命令参数:
参数 | 描述 |
---|---|
--help | 帮助信息 |
--config <config_file_path> | 配置文件路径 |
导入示例:
/opt/ultipa-transporter/ultipa-importer --config ./in.yml
导出示例:
/opt/ultipa-transporter/ultipa-exporter --config ./out.yml
帮助示例:
/opt/ultipa-transporter/ultipa-exporter --help
配置文件
导入、导出的配置文件为 yml 格式,具体配置内容分为以下四部分:
- server
- nodeConfig
- edgeConfig
- settings
server
参数 |
规范 | 描述 |
---|---|---|
host | <ip>:<port> | 远程数据库的主机 ip 及端口 |
username | string | 远程登录的用户名 |
password | string | 远程登录的密码 |
crt | <file_path> | 用于远程通信的 ssl 证书文件的绝对路径,仅在双方均为 ssl 模式时有效 |
graphset | string | 目标图集的名称,如不使用此参数,则为默认图集 'default';如果图集名不存在则会失败,也可让 Transporter 自动创建图集,详见 settings 的 yes 参数 |
nodeConfig | edgeConfig
参数 |
规范 | 操作类型 |
描述 |
---|---|---|---|
- schema | string | 导入 导出 |
点/边的 schema,必须填写;如果 schema 不存在则会失败;导入时可以让 Transporter 自动创建 schema,详见 settings 的 yes 参数;导出时可以用 '*' 表示所有 schema 的所有属性 |
file | <file_path> | 导入 | 导入时点/边文件的绝对路径和文件名,如 '/opt/ultipa-server/import/amz/node.csv' |
skip | int | 导入 | 从第一条数据开始要跳过(即不导入)的数据条数,如不使用此参数,则不跳过任何数据 |
limit | int | 导入 | 要导入的数据条数,如不使用此参数,则一直导入至文件末尾 |
properties 或 types |
导入 导出 |
提示接下来将声明文件中的各列。导入无表头文件或导出文件时用 properties ,导入有表头文件时用 types ;一个 - schema 下 properties 和 types 不能同时出现 |
|
- name | string | 导入 导出 |
某列属性的名称,如果属性不存在则会失败;导入时可以让 Transporter 自动创建属性,详见 settings 的 yes 参数 |
type | string | 导入 | 某列属性的数据类型,支持用 string int32 int64 uint32 uint64 float double datetime timestamp 声明普通属性,支持用 _id _uuid _from _to _from_uuid _to_uuid 声明系统属性,支持用 _ignore 声明忽略该列数据;如不使用此参数,则为 string;目标图集中已存在的属性仍需声明数据类型,且需保持类型一致 |
注意:带有短线的参数(- schema 和 - name)及其子参数可出现多次。
settings
参数 |
规范 | 操作类型 |
描述 |
---|---|---|---|
logPath | <path> | 导入 | 导入时的日志文件的路径,如 '/opt/ultipa-server/log';如不使用此参数,则默认写至 './log/' |
separator | string | 导入 | 导入文件中数据列的分隔符,支持 ','、'\t'、'|'、';',如不使用此参数,则为 ',' |
threads | int | 导入 | 导入时的最大线程数(>=2,整数),如不使用此参数,则为运行 Transporter 的机器的 CPU 数量,建议使用 32 |
batchSize | int | 导入 | 每批导入的条数,设置范围为 500-10000,推荐设置为 100000/属性个数,如不使用此参数,则为 10000 |
importMode | string | 导入 | 导入的类型,支持 'insert'、'upsert'、'overwrite',如不使用此参数则为 'insert' |
createNodeIfNotExist | bool | 导入 | 是否在边的起点/终点不存在时自动创建点;如不使用此参数,则不创建,并会导致相关边导入失败 |
stopWhenError | bool | 导入 | 导入出错时,是否即刻终止导入操作,如不使用此参数,则会跳过出错的数据块并从下一个数据块继续导入 |
yes | bool | 导入 | 是否自动创建不存在的图集、schema、属性;如不使用此参数,则默认为 false |
fitToHeader | bool | 导入 | 是否以文件中的表头或手动声明的表头为准,对文件中的数据列进行忽略、补空、补零等;如不使用此参数,则系统会在属性表头与数据列不一致时报错 |
writeHeader | bool | 导出 | 是否在导出的文件(csv 或 tsv)中写入表头,如不使用此参数则写入表头,且列名为 <属性名>:<类型> |
outPath | <path> | 导出 | 导出文件的路径,如 '/opt/ultipa-server/import/amz',如不使用此参数,则默认写至 './export' |
注意:导出的数据文件由 Transporter 自动命名,命名方式为 <schema>.node.<file_type> 及 <schema>.edge.<file_type>,例如:default.node.csv
yml 文件示例
远程导入
示例:将以下 3 个文件导入至远程数据库
点文件(txt)@student,注意文件表头中 age 属性的数据类型有误,导入时请修改为 uint32:
stuNo:_id,name:string,age:string,gender:string
20215865,Alice,24,f
20215925,Jack,25,m
20215973,John,28,m
20215990,Grace,25,f
点文件(txt)@course,导入时请额外创建一个任课老师 professor 的属性:
crsNo,title,credit
CS202104,计算机原理,4
SH202127,影视创作论,2.5
MS202104,微积分,3
边文件(csv)@enroll,第一列为学号,第二列为课程号,导入时请忽略最后一列数据:
20215865,SH202127,84.5
20215925,MS202104,77.5
20215973,CS202104,86
20215990,SH202127,64.5
命令行:
./ultipa-importer --config ./in.yml
in.yml:
server:
host: "192.168.35.151:60024"
username: employee533
password: joaedSSGsdf
crt: ""
graphset: test_graph
nodeConfig:
- schema: student
file: ./student.txt
types:
- name: age
type: uint32
- schema: course
file: ./course.txt
types:
- name: title
- name: professor
- name: crsNo
type: _id
- name: credit
type: float
edgeConfig:
- schema: enroll
file: ./enroll.csv
properties:
- name: _from
type: _from
- name: _to
type: _to
settings:
separator: ","
yes: true
fitToHeader: true
远程导出
示例:从远程数据库中导出点 @student 的全部属性,@course 的 _id 和 title 属性,以及所有 边schema 的所有属性
命令行:
./ultipa-exporter --config ./out.yml
out.yml:
server:
host: "192.168.35.151:60024"
username: employee533
password: joaedSSGsdf
crt: ""
graphset: test_graph
nodeConfig:
- schema: student
- schema: course
properties:
- name: _id
- name: title
edgeConfig:
- schema: *
settings:
writeHeader: false
outPath: ./export/temp
FAQ
Q: Go 版 Transporter 在什么环境下运行?
A: Go 版 Transporter 支持在 MacOS、Windows、Linux 环境下运行,使用时需将待导入的点边文件、yml 文件、importer 或 exporter 放在同一目录下,并通过命令行工具运行 importer 或 exporter。