本文以上一篇中搭建好的零售场景的图模型为基础,阐述如何使用 Ultipa Manager、Ultipa Transporter-Importer 两种工具将图数据批量导入到 Ultipa 图数据库服务器中。
准备数据文件
把图数据以文件的形式导入到 Ultipa 图集的过程即为入图。每个图数据文件代表一个 schema;文件内每行数据(除表头)代表一个点或边,每列数据代表一个属性;支持列分隔符 ,
、\t
、|
以及 ;
。
以下是与 schema customer
、merchant
和 transfer
对应的表数据 CUSTOMER、MERCHANT 和 TRANSACTION 的文件内容:
下载三个表数据的 CSV 文件:CUSTOMER.csv,MERCHANT.csv,TRANSACTION.csv
这三个文件均使用英文逗号 ,
作为列分隔符,且均有表头。观察表头中的列名可以发现,点系统属性 _id
和边系统属性 _from
、_to
所在数据列的列名仍然为 cust_no
或 merchant_no
,需要将它们修改为相应的系统属性名称,可以直接在文件内修改,也可以在入图时修改。
使用 Manager 入图
使用 Manager 进行入图的主要优势是形象直观,操作简单。
准备图集、Schema
使用 Ultipa Manager 进行入图前要确保图集和图模型(点、边 schema)已经创建。
- 创建图集
在 Manager 顶部的 CLI 中运行以下的 UQL 语句创建图集:
// 创建图集 'retail_test'
create().graph("retail_test")
或者通过 UI 界面创建图集:
注意,创建图集后要切换至刚创建好的图集。
- 创建 schema
在 Manager 顶部的 CLI 中运行以下的 UQL 语句创建 schema:
// 创建点schema 'customer'、'merchant',边schema 'transfer'
create()
.node_schema("customer")
.node_schema("merchant")
.edge_schema("transfer")
或者通过 UI 界面创建 schema:
导入点文件
导入边数据时必须提供
_from
、_to
这两个属性值,且它们所代表的点必须已经存在于图集中,因此需要先导入点数据,再导入边数据。
以导入 CUSTOMER.csv 为例,导入分为以下四个步骤:
- 上传文件
点击 Manager 左侧栏中的“文件”,在弹出的窗口中找到“导入”并点击其右侧的加号“+”,选择“+点”并上传本地的 CUSTOMER.csv 文件:
- 声明分隔符、表头
这关系到文件中的数据列及表头能否被正确识别。CUSTOMER.csv 文件的列分隔符为 ,
,且包含表头,可以点击“数据预览”查看数据的分列是否正确、表头是否被成功识别(而不是被当作一行点数据):
- 声明 schema 和属性数据类型
这关系到文件中的数据列能否被正确识别(或创建)为其所代表的属性。CUSTOMER.csv 文件对应着点 schema customer
,因此首先将 Schema 选择为 customer
。之后,有些列名左侧出现了红三角标志,表示这些属性尚未在 customer
中创建。将列名 cust_no
改为 _id
后,其左侧红三角消失,表示该列已被识别为系统属性 _id
;其余各列需要被创建为自定义属性,依次修改它们的数据类型,然后点击窗口底部的加号,此时所有红三角消失,表示所有属性已被创建:
- 执行导入
导入时可以选择插入更新(upsert)或插入覆盖(overwrite)两种模式。我们现在要新增点数据,两种模式皆可:
导入 MERCHANT.csv 文件的过程与上面类似。
导入边文件
CUSTOMER.csv 和 MERCHANT.csv 这两个文件导入完成后,就可以导入 TRANSACTION.csv 了。上传文件时选择“+边”并选择本地的 TRANSACTION.csv 文件,选择schema为 transfer
后,将 cust_no
和 merchant_no
的列名分别改为 _from
和 _to
:
入图验证
快速验证入图后的结果。点击 Manager 左侧栏中的“Schema”,在弹出的面板中查看 schema 的树状结构,并校验点、边的数量。在展开的树中,还可以看到 schema 的自定义属性及数据类型:
使用 Transporter 入图
相比于 Manager,使用 Transporter 入图的主要优势为导入速度快,可以同时导入多个文件。
准备 YAML 文件
使用 Ultipa Transporter 的导入工具 Importer 进行入图时,不用事先创建图集和 schema,但需要准备一个 Yaml 配置文件,该文件包含服务器的连接信息、目标图集的名称、每个数据文件的 schema、每个数据列的属性类型等,还声明了数据列分隔符、导入模式、如何分批等细节方面的信息。
Yaml 配置文件有四部分内容:
- 第一部分 服务器信息
server:
host: "192.168.100.100:60010"
username: "root"
password: "root"
graphset: "retail_test"
crt: ""
服务器连接信息 host
、username
、password
由数据库管理员提供;graphset
可以是一个尚未创建的图集;未使用 TLS 通讯时可以不填写 crt
。
- 第二部分 点文件信息
nodeConfig:
# 关于 CUSTOMER.csv 文件
- schema: "customer"
file: "./CUSTOMER.csv"
types:
- name: cust_no
type: _id
- name: risk_level
type: int32
- name: card_level
type: int32
- name: balance
type: float
# 关于 MERCHANT.csv 文件
- schema: "merchant"
file: "./MERCHANT.csv"
types:
- name: merchant_no
type: _id
数据列 cust_no
、merchant_no
被声明为系统属性 _id
,此两列数据将自动读取为 string;risk_level
、card_level
、balance
将分别读取为 int32、int32、float;CUSTOMER.csv 中的数据列 cust_name
、MERCHANT.csv 中的数据列 merchant_name
、type
并未提及,默认读取为 string。
- 第三部分 边文件信息
edgeConfig:
# 关于 TRANSACTION.csv 文件
- schema: "transfer"
file: "./TRANSACTION.csv"
types:
- name: cust_no
type: _from
- name: merchant_no
type: _to
- name: tran_date
type: timestamp
- name: tran_amount
type: float
- name: tran_type
type: int32
数据列 cust_no
、merchant_no
被声明为系统属性 _from
、_to
,此两列数据将自动读取为 string;tran_date
、tran_amount
、tran_type
将分别读取为 timestamp、float、int32;数据列 result
并未提及,默认读取为 string。
- 第四部分 全局信息
settings:
separator: ","
importMode: insert
yes: true
batchSize: 10000
threads: 8
列分隔符为英文逗号 ,
;由于是新增点、边,以 insert、overwrite 或 upsert 模式导入均可;yes
为 true 表示如果文件中指定的图集、schema、属性不存在则自动创建;batchSize
和 threads
是分批导入时的批大小以及导入时的并发数,适用于导入数据量很大的情况。
在 Yaml 文件中换行缩进时,每一级缩进是两次空格键,而非一次 tab 键。
将以上四部分内容保存至配置文件 import_retail.yml 中(点击文件名下载)。
导入点、边文件
将 Transporter 的导入工具 ultipa-importer、点边数据文件 CUSTOMER.csv、MERCHANT.csv、TRANSACTION.csv、配置文件 import_retail.yml 放在同一个目录下,在该目录下打开命令行工具(以右键 Powershell 为例)执行以下命令:
./ultipa-importer --config ./import_retail.yml
执行命令行时如果提示
bash: ./ultipa-importer: Permission denied
则表示没有相关的执行权限,可以先执行chmod 777 ultipa-importer
获得权限后再执行 ultipa-importer 的命令。
使用 ultipa-importer 导入日期类型的数据列时,需要先规范其数据格式为
yyyy-mm-dd hh:mm:ss
,例如,需要将2022/3/2 22:12:56
修改为2022-03-02 22:12:56
才能成功导入。