GUIDES on Apache HugeGraph

HugeGraph Architecture Overview

Mon, 01 Jan 0001 00:00:00 +0000

1 概述

作为一款通用的图数据库产品，HugeGraph需具备图数据的基本功能，如下图所示。HugeGraph包括三个层次的功能，分别是存储层、计算层和用户接口层。 HugeGraph支持OLTP和OLAP两种图计算类型，其中OLTP实现了Apache TinkerPop3框架，并支持Gremlin查询语言。 OLAP计算是基于SparkGraphX实现。

2 组件

HugeGraph的主要功能分为HugeCore、ApiServer、HugeGraph-Client、HugeGraph-Loader和HugeGraph-Studio等组件构成，各组件之间的通信关系如下图所示。

HugeCore ：HugeGraph的核心模块，TinkerPop的接口主要在该模块中实现。HugeCore的功能涵盖包括OLTP和OLAP两个部分。
ApiServer ：提供RESTFul Api接口，对外提供Graph Api、Schema Api和Gremlin Api等接口服务。
HugeGraph-Client：基于Java客户端驱动程序。HugeGraph-Client是Java版本客户端驱动程序，后续可根据需要提供Python、Go、C++等多语言支持。
HugeGraph-Loader：数据导入模块。HugeGraph-Loader可以扫描并分析现有数据，自动生成Graph Schema创建语言，通过批量方式快速导入数据。
HugeGraph-Studio：基于Web的可视化IDE环境。以Notebook方式记录Gremlin查询，可视化展示Graph的关联关系。HugeGraph-Studio也是本系统推荐的工具。
HugeGraph-Computer：HugeGraph-Computer是一个分布式图处理系统 (OLAP)。

HugeGraph Design Concepts

Mon, 01 Jan 0001 00:00:00 +0000

1. Property Graph

常见的图数据表示模型有两种，分别是RDF（Resource Description Framework）模型和属性图（Property Graph）模型。 RDF和Property Graph都是最基础、最有名的图表示模式，都能够表示各种图的实体关系建模。 RDF是W3C标准，而Property Graph是工业标准，受到广大图数据库厂商的广泛支持。HugeGraph目前采用Property Graph。

HugeGraph对应的存储概念模型也是参考Property Graph而设计的，具体示例详见下图：（此图为旧版设计已过时，请忽略它，后续更新）

在HugeGraph内部，每个顶点 / 边由唯一的 VertexId / EdgeId 标识，属性存储在对应点 / 边内部。而顶点与顶点之间的关系 / 映射则是通过边来存储的。

顶点属性值通过边指针方式存储时，如果要更新一个顶点特定的属性值直接通过覆盖写入即可，其弊端是冗余存储了VertexId；如果要更新关系的属性需要通过read-and-modify方式，先读取所有属性，修改部分属性，然后再写入存储系统，更新效率较低。从经验来看顶点属性的修改需求较多，而边的属性修改需求较少，例如PageRank和Graph Cluster等计算都需要频繁修改顶点的属性值。

2. 图分区方案

对于分布式图数据库而言，图的分区存储方式有两种：分别是边分割存储（Edge Cut）和点分割存储（Vertex Cut），如下图所示。使用Edge Cut方式存储图时，任何一个顶点只会出现在一台机器上，而边可能分布在不同机器上，这种存储方式有可能导致边多次存储。使用Vertex Cut方式存储图时，任何一条边只会出现在一台机器上，而每相同的一个点可能分布到不同机器上，这种存储方式可能会导致顶点多次存储。

采用EdgeCut分区方案可以支持高性能的插入和更新操作，而VertexCut分区方案更适合静态图查询分析，因此EdgeCut适合OLTP图查询，VertexCut更适合OLAP的图查询。 HugeGraph目前采用EdgeCut的分区方案。

3. VertexId 策略

HugeGraph的Vertex支持三种ID策略，在同一个图数据库中不同的VertexLabel可以使用不同的Id策略，目前HugeGraph支持的Id策略分别是：

自动生成（AUTOMATIC）：使用Snowflake算法自动生成全局唯一Id，Long类型；
主键（PRIMARY_KEY）：通过VertexLabel+PrimaryKeyValues生成Id，String类型；
自定义（CUSTOMIZE_STRING|CUSTOMIZE_NUMBER）：用户自定义Id，分为String和Long类型两种，需自己保证Id的唯一性；

默认的Id策略是AUTOMATIC，如果用户调用primaryKeys()方法并设置了正确的PrimaryKeys，则自动启用PRIMARY_KEY策略。启用PRIMARY_KEY策略后HugeGraph能根据PrimaryKeys实现数据去重。

AUTOMATIC ID策略

schema.vertexLabel("person")
 .useAutomaticId()
 .properties("name", "age", "city")
 .create();
graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

PRIMARY_KEY ID策略

schema.vertexLabel("person")
 .usePrimaryKeyId()
 .properties("name", "age", "city")
 .primaryKeys("name", "age")
 .create();
graph.addVertex(T.label, "person","name", "marko", "age", 18, "city", "Beijing");

CUSTOMIZE_STRING ID策略

schema.vertexLabel("person")
 .useCustomizeStringId()
 .properties("name", "age", "city")
 .create();
graph.addVertex(T.label, "person", T.id, "123456", "name", "marko","age", 18, "city", "Beijing");

CUSTOMIZE_NUMBER ID策略

schema.vertexLabel("person")
 .useCustomizeNumberId()
 .properties("name", "age", "city")
 .create();
graph.addVertex(T.label, "person", T.id, 123456, "name", "marko","age", 18, "city", "Beijing");

如果用户需要Vertex去重，有三种方案分别是：

HugeGraph Plugin机制及插件扩展流程

Mon, 01 Jan 0001 00:00:00 +0000

背景

HugeGraph不仅开源开放，而且要做到简单易用，一般用户无需更改源码也能轻松增加插件扩展功能。
HugeGraph支持多种内置存储后端，也允许用户无需更改现有源码的情况下扩展自定义后端。
HugeGraph支持全文检索，全文检索功能涉及到各语言分词，目前已内置8种中文分词器，也允许用户无需更改现有源码的情况下扩展自定义分词器。

可扩展维度

目前插件方式提供如下几个维度的扩展项：

后端存储
序列化器
自定义配置项
分词器

插件实现机制

HugeGraph提供插件接口HugeGraphPlugin，通过Java SPI机制支持插件化
HugeGraph提供了4个扩展项注册函数：registerOptions()、registerBackend()、registerSerializer()、registerAnalyzer()
插件实现者实现相应的Options、Backend、Serializer或Analyzer的接口
插件实现者实现HugeGraphPlugin接口的register()方法，在该方法中注册上述第3点所列的具体实现类，并打成jar包
插件使用者将jar包放在HugeGraph Server安装目录的plugins目录下，修改相关配置项为插件自定义值，重启即可生效

插件实现流程实例

1 新建一个maven项目

1.1 项目名称取名：hugegraph-plugin-demo

1.2 添加`hugegraph-core` Jar包依赖

maven pom.xml详细内容如下：

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

 <modelVersion>4.0.0</modelVersion>
 <groupId>com.baidu.hugegraph</groupId>
 <artifactId>hugegraph-plugin-demo</artifactId>
 <version>1.0.0</version>
 <packaging>jar</packaging>

 <name>hugegraph-plugin-demo</name>

 <dependencies>
 <dependency>
 <groupId>com.baidu.hugegraph</groupId>
 <artifactId>hugegraph-core</artifactId>
 <version>${project.version}</version>
 </dependency>
 </dependencies>
</project>

2 实现扩展功能

2.1 扩展自定义后端

2.1.1 实现接口BackendStoreProvider

可实现接口：com.baidu.hugegraph.backend.store.BackendStoreProvider
或者继承抽象类：com.baidu.hugegraph.backend.store.AbstractBackendStoreProvider

以RocksDB后端RocksDBStoreProvider为例：

Backup Restore

Mon, 01 Jan 0001 00:00:00 +0000

描述

Backup 和 Restore 是备份图和恢复图的功能。备份和恢复的数据包括元数据（schema）和图数据（vertex 和 edge）。

Backup

将 HugeGraph 系统中的一张图的元数据和图数据以 JSON 格式导出。

Restore

将 Backup 导出的JSON格式的数据，重新导入到 HugeGraph 系统中的一个图中。

Restore 有两种模式：

Restoring 模式，将 Backup 导出的元数据和图数据原封不动的恢复到 HugeGraph 系统中。可用于图的备份和恢复，一般目标图是新图（没有元数据和图数据）。比如：
- 系统升级，先备份图，然后升级系统，最后将图恢复到新的系统中
- 图迁移，从一个 HugeGraph 系统中，使用 Backup 功能将图导出，然后使用 Restore 功能将图导入另一个 HugeGraph 系统中
Merging 模式，将 Backup 导出的元数据和图数据导入到另一个已经存在元数据或者图数据的图中，过程中元数据的 ID 可能发生改变，顶点和边的 ID 也会发生相应变化。
- 可用于合并图

使用方法

可以使用hugegraph-tools进行图的备份和恢复。

Backup

bin/hugegraph backup -t all -d data

该命令将 http://127.0.0.1 的 hugegraph 图的全部元数据和图数据备份到data目录下。

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

如何选择后端存储? 选 RocksDB 还是 Cassandra 还是 Hbase 还是 Mysql?

根据你的具体需要来判断, 一般单机或数据量 < 100 亿推荐 RocksDB, 其他推荐使用分布式存储的后端集群
启动服务时提示：xxx (core dumped) xxx

请检查JDK版本是否为1.8
启动服务成功了，但是操作图时有类似于"无法连接到后端或连接未打开"的提示

第一次启动服务前，需要先使用init-store初始化后端，后续版本会将提示得更清晰直接。
所有的后端在使用前都需要执行init-store吗，序列化的选择可以随意填写么?

除了memory不需要，其他后端均需要，如：cassandra、hbase和rocksdb等，序列化需一一对应不可随意填写。
执行init-store报错：Exception in thread "main" java.lang.UnsatisfiedLinkError: /tmp/librocksdbjni3226083071221514754.so: /usr/lib64/libstdc++.so.6: version `GLIBCXX_3.4.10' not found (required by /tmp/librocksdbjni3226083071221514754.so)

RocksDB需要 gcc 4.3.0 (GLIBCXX_3.4.10) 及以上版本
执行init-store.sh时报错：NoHostAvailableException

NoHostAvailableException 是指无法连接到Cassandra服务，如果确定是要使用cassandra后端，请先安装并启动这个服务。至于这个提示本身可能不够直白，我们会更新到文档进行说明的。
bin目录下包含start-hugegraph.sh、start-restserver.sh和start-gremlinserver.sh三个似乎与启动有关的脚本，到底该使用哪个

自0.3.3版本以来，已经把 GremlinServer 和 RestServer 合并为 HugeGraphServer 了，使用start-hugegraph.sh启动即可，后两个在后续版本会被删掉。
配置了两个图，名字是hugegraph和hugegraph1，而启动服务的命令是start-hugegraph.sh，是只打开了hugegraph这个图吗

start-hugegraph.sh会打开所有gremlin-server.yaml的graphs下的图，这二者并无名字上的直接关系
服务启动成功后，使用curl查询所有顶点时返回乱码

服务端返回的批量顶点/边是压缩（gzip）过的，可以使用管道重定向至 gunzip 进行解压（curl http://example | gunzip），也可以用Firefox的postman或者Chrome浏览器的restlet插件发请求，会自动解压缩响应数据。
使用顶点Id通过RESTful API查询顶点时返回空，但是顶点确实是存在的

检查顶点Id的类型，如果是字符串类型，API的url中的id部分需要加上双引号，数字类型则不用加。
已经根据需要给顶点Id加上了双引号，但是通过RESTful API查询顶点时仍然返回空

检查顶点id中是否包含+、空格、/、?、%、&和=这些URL的保留字符，如果存在则需要进行编码。下表给出了编码值：

GUIDES on Apache HugeGraph

HugeGraph Architecture Overview

1 概述

2 组件

HugeGraph Design Concepts

1. Property Graph

2. 图分区方案

3. VertexId 策略

HugeGraph Plugin机制及插件扩展流程

背景

可扩展维度

插件实现机制

插件实现流程实例

1 新建一个maven项目

1.1 项目名称取名：hugegraph-plugin-demo

1.2 添加hugegraph-core Jar包依赖

2 实现扩展功能

2.1 扩展自定义后端

2.1.1 实现接口BackendStoreProvider

Backup Restore

描述

Backup

Restore

使用方法

Backup

FAQ

1.2 添加`hugegraph-core` Jar包依赖