本文适用于 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 时发生错误。可能的错误类型有：

1. 配置文件的内容不符合 yml 规范；
2. 参数配置错误，例如属性名称、数据类型不符合 UQL 规范；
3. 创建图集、schema 失败；

导入时报错

导入时报错是指在导入数据的过程中发生错误。可能的错误类型有：

1. 服务器返回的错误；
2. 网络错误；
3. 数据格式错误（表头及数据列不一致）；
4. 导入数据重复（insert 时有重复的点、边）；

在默认情况下，系统会跳过错误的数据批块，继续导入后面的数据批块；也支持出错即终止的模式（参数 stopWhenError 设置为真），即首个出错的数据批块及其后所有数据都会被跳过。出错时系统会返回错误类型、被跳过数据的起始位置和数据条数；据此，可以在修复数据文件后用参数 skip 声明起始位置，用参数 limit 声明数据条数，重新导入之前被跳过的数据。

上述第 3 种错误类型的常见情况有：

• 对于无表头的文件，在 properties 下声明的 - name 个数与文件中的数据列数不一致；
• 对于有表头的文件，个别数据列没有列名，或末尾的列名之下没有数据占位；

对于上述情况，如果将参数 fitToHeader 设置为真，可强制以配置文件中的声明（无表头时）、或待导入文件中的列名（有表头时）为准，对数据列进行忽略或补空、补零，此时不会触发第 3 种错误。

命令参数

Ultipa Transporter 分为导入和导出两个工具，即 ultipa-importer 和 ultipa-exporter。两个工具均有以下命令参数：

导入示例：

/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

nodeConfig | edgeConfig

注意：带有短线的参数（- schema 和 - name）及其子参数可出现多次。

settings

注意：导出的数据文件由 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。