修改密码

请输入密码
请输入密码 请输入8-64长度密码 和 email 地址不相同 至少包括数字、大写字母、小写字母、半角符号中的 3 个
请输入密码
提交

修改昵称

当前昵称:
提交

搜索
v4.0
    v4.0

    Transporter

    本文适用于 Go 版本的 Ultipa Transporter 客户端工具。

    概述

    Ultipa Transporter 是命令行下的快速导入导出工具,可以对 Ultipa 图数据库进行远程数据批量导入和导出。

    一个命令行可以导入(或导出)多个 点schema 和/或多个 边schema 的文件。

    远程操作(需在 yml 文件的 server 中进行相关声明)是针对远程数据库中某个图集的点/边信息进行的数据导入、导出操作,需设置远程主机的 ip 及端口 host、用户名 username、密码 password,支持使用 ssl 协议 crt

    点/边文件

    导入、导出所涉及的点/边数据文件存放于本地,每个文件代表一个 点schema 或一个 边schema;文件内每行数据(除表头)代表一个点/边,每列数据代表点/边的一个属性;导入文件支持 csv、tsv、txt 等格式,支持 ,\t|; 分隔符;导出文件为 csv 格式,以 , 为分隔符。

    文件内的元数据类型(点或边)通过 nodeConfigedgeConfig 来声明。每次导入、导出的多个文件需为同一种格式(及同一种分隔符),需分别声明每个文件内的属性。

    导入声明

    为所有文件统一指定(需在 yml 文件的 settings 中进行相关声明):文件分隔符 separator、导入的线程数 threads、批大小 batchSize、日志路径 logPath、导入方式 importMode 等诸多细节参数;导入 csv 或 tsv 时有无表头均可(有表头时列名为 <属性名><属性名>:<类型>)。

    为每个文件分别指定(需在 yml 文件的 nodeConfigedgeConfig 中进行相关声明):该文件的本地存储路径 file、元数据模式 - schema 、要导入的属性 propertiestypes、开始导入的位置 skip、导入条数 limit

    导入的 csv 或 tsv 文件:

    • 无表头时,在 properties 下依次为各列:
      • 通过 - nametype 声明属性名称及数据类型;
      • 通过 - nametype 声明属性名称及 string 类型;
      • - name 个数小于列数时,小多少就舍弃末尾的多少列;
    • 有表头时,在 types 下为某些列(顺序不限):
      • 通过 - nametype 声明或修改数据类型;
      • 通过 - nametype 声明或修改为 string 类型;
      • - name 没出现的列,若列名为 <属性名> 则声明为 string 类型,若列名为 <属性名>:<类型> 则使用列名中的<类型>

    有效的数据类型 type 包括:

    • _id_uuid_from_to_from_uuid_to_uuid(用来声明系统属性);
    • stringfloatdoubleint32uint32int64uint64datetimetimestamp
    • _ignore(用来忽略该列,不导入)

    用户需保证声明的数据类型和实际导入的数据类型一致;如果不一致,例如声明为整数但实际导入了字符串,系统会报错。

    导出声明

    为所有文件统一指定(需在 yml 文件的 settings 中进行相关声明):导出的 csv 文件的本地存储路径 outPath;是否生成表头 writeHeder(生成表头时列名为 <属性名>:<类型>);导出时程序自动分批,无需设置批大小。

    为每个文件分别指定(需在 yml 文件的 nodeConfigedgeConfig 中进行相关声明):该文件的元数据模式 - schema 、在 properties 下指定要导出的普通属性 - name;Ultipa 系统属性将默认导出,无需指定。

    点、边基本知识

    唯一标识符

    点数据有两种唯一标识符:_id 为 32bit 以内的字符串,_uuid 为 uint64 以内的整数;因此,边起点相应的有_from_from_uuid 两种,边终点也相应的有 _to_to_uuid 两种。边数据只有 _uuid 一种唯一标识符。这六个属性为 Ultipa 系统属性,也是声明属性时有效的数据类型。

    导入方式

    当导入方式 importModeupsertoverwrite 时,如果导入的点、边数据在图集中已存在(数据文件中含有唯一标识符,且唯一标志符在目标图集中已存在),则相应执行插入更新或插入覆盖操作;否则(唯一标志符不存在,或数据文件中不含唯一标志符)数据将被视为新的点、边,执行插入操作。

    当导入方式 importModeinsert 时,仅导入新的点、边数据(不含唯一标识符、或唯一标志符不存在点、边);如果校验发现待导入的点、边已存在则报错。

    所有插入操作都会自动生成文件中未包含的唯一标识符。

    边的要求及处理

    边文件中必须包含边起点、边终点两列数据。

    边成功导入的前提是边的起点、终点已经存在;如果不存在,则导入会失败,可以将参数 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-importerultipa-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 自动创建图集,详见 settingsyes 参数

    nodeConfig | edgeConfig

    参数

    规范

    操作类型

    描述
    - schema string 导入
    导出
    点/边的 schema,必须填写;如果 schema 不存在则会失败;导入时可以让 Transporter 自动创建 schema,详见 settingsyes 参数;导出时可以用 '*' 表示所有 schema 的所有属性
    file <file_path> 导入 导入时点/边文件的绝对路径和文件名,如 '/opt/ultipa-server/import/amz/node.csv'
    skip int 导入 从第一条数据开始要跳过(即不导入)的数据条数,如不使用此参数,则不跳过任何数据
    limit int 导入 要导入的数据条数,如不使用此参数,则一直导入至文件末尾
    properties

    types
    导入
    导出
    提示接下来将声明文件中的各列。导入无表头文件或导出文件时用 properties,导入有表头文件时用 types;一个 - schemapropertiestypes 不能同时出现
    - name string 导入
    导出
    某列属性的名称,如果属性不存在则会失败;导入时可以让 Transporter 自动创建属性,详见 settingsyes 参数
    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。

    请完成以下信息后可下载此书
    *
    公司名称不能为空
    *
    公司邮箱必须填写
    *
    你的名字必须填写
    *
    你的电话必须填写
    *
    你的电话必须填写