HugeGraph RESTful API on Apache HugeGraph

Graphspace API

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

2.0 Graphspace

在 HugeGraph 中，多租户是通过图空间（graph space）来实现的，资源的分配和隔离可以通过图空间进行。

重要前置条件：

Schema API

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

1.1 Schema

HugeGraph 提供单一接口获取某个图的全部 Schema 信息，包括：PropertyKey、VertexLabel、EdgeLabel 和 IndexLabel。

PropertyKey API

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

1.2 PropertyKey

Params 说明：

name：属性类型名称，必填
data_type：属性类型数据类型，包括：bool、byte、int、long、float、double、text、date、uuid、blob，默认 text 类型 (代表 string 字符串类型)
cardinality：属性类型基数，包括：single、list、set，默认 single (代表单属性值)

请求体字段说明：

VertexLabel API

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

1.3 VertexLabel

假设已经创建好了 1.1.3 中列出来的 PropertyKeys

Params 说明

id：顶点类型 id 值
name：顶点类型名称，必填
id_strategy: 顶点类型的 ID 策略，主键 ID、自动生成、自定义字符串、自定义数字、自定义 UUID，默认主键 ID
properties: 顶点类型关联的属性类型
primary_keys: 主键属性，当 ID 策略为 PRIMARY_KEY 时必须有值，其他 ID 策略时必须为空；
enable_label_index：是否开启类型索引，默认关闭
index_names：顶点类型创建的索引，详情见 3.4
nullable_keys：可为空的属性
user_data：设置顶点类型的通用信息，作用同属性类型

1.3.1 创建一个 VertexLabel

Method & Url

POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels

Request Body

{
 "name": "person",
 "id_strategy": "DEFAULT",
 "properties": [
 "name",
 "age"
 ],
 "primary_keys": [
 "name"
 ],
 "nullable_keys": [],
 "enable_label_index": true
}

Response Status

Response Body

{
 "id": 1,
 "primary_keys": [
 "name"
 ],
 "id_strategy": "PRIMARY_KEY",
 "name": "person2",
 "index_names": [
 ],
 "properties": [
 "name",
 "age"
 ],
 "nullable_keys": [
 ],
 "enable_label_index": true,
 "user_data": {}
}

从 hugegraph-server v0.11.2 版本开始支持顶点的 TTL 功能。顶点的 TTL 是通过 VertexLabel 来设置的。比如希望 person 类型的顶点存活时间为一天，需要在创建 person VertexLabel 的时候将 TTL 字段设置为 86400000，即单位为毫秒。

EdgeLabel API

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

1.4 EdgeLabel

假设已经创建好了 1.2.3 中的 PropertyKeys 和 1.3.3 中的 VertexLabels

Params 说明

name：顶点类型名称，必填
source_label: 源顶点类型的名称，必填
target_label: 目标顶点类型的名称，必填
frequency：两个点之间是否可以有多条边，可以取值 SINGLE 和 MULTIPLE，非必填，默认值 SINGLE
properties: 边类型关联的属性类型，选填
sort_keys: 当允许关联多次时，指定区分键属性列表
nullable_keys：可为空的属性，选填，默认可为空
enable_label_index：是否开启类型索引，默认关闭

1.4.1 创建一个 EdgeLabel

Method & Url

POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/edgelabels

Request Body

{
 "name": "created",
 "source_label": "person",
 "target_label": "software",
 "frequency": "SINGLE",
 "properties": [
 "date"
 ],
 "sort_keys": [],
 "nullable_keys": [],
 "enable_label_index": true
}

Response Status

Response Body

{
 "id": 1,
 "sort_keys": [
 ],
 "source_label": "person",
 "name": "created",
 "index_names": [
 ],
 "properties": [
 "date"
 ],
 "target_label": "software",
 "frequency": "SINGLE",
 "nullable_keys": [
 ],
 "enable_label_index": true,
 "user_data": {}
}

从 hugegraph-server v0.11.2 版本开始支持边的 TTL 功能。边的 TTL 是通过 EdgeLabel 来设置的。比如希望 knows 类型的边存活时间为一天，需要在创建 knows EdgeLabel 的时候将 TTL 字段设置为 86400000，即单位为毫秒。

IndexLabel API

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

1.5 IndexLabel

假设已经创建好了 1.1.3 中的 PropertyKeys、1.2.3 中的 VertexLabels 以及 1.3.3 中的 EdgeLabels

1.5.1 创建一个 IndexLabel

Method & Url

POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexlabels

Request Body

{
 "name": "personByCity",
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "index_type": "SECONDARY",
 "fields": [
 "city"
 ]
}

Response Status

Response Body

{
 "index_label": {
 "id": 1,
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "name": "personByCity",
 "fields": [
 "city"
 ],
 "index_type": "SECONDARY"
 },
 "task_id": 2
}

1.5.2 获取所有的 IndexLabel

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexlabels

Response Status

Response Body

{
 "indexlabels": [
 {
 "id": 3,
 "base_type": "VERTEX_LABEL",
 "base_value": "software",
 "name": "softwareByPrice",
 "fields": [
 "price"
 ],
 "index_type": "RANGE"
 },
 {
 "id": 4,
 "base_type": "EDGE_LABEL",
 "base_value": "created",
 "name": "createdByDate",
 "fields": [
 "date"
 ],
 "index_type": "SECONDARY"
 },
 {
 "id": 1,
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "name": "personByCity",
 "fields": [
 "city"
 ],
 "index_type": "SECONDARY"
 },
 {
 "id": 3,
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "name": "personByAgeAndCity",
 "fields": [
 "age",
 "city"
 ],
 "index_type": "SECONDARY"
 }
 ]
}

1.5.3 根据 name 获取 IndexLabel

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/indexlabels/personByCity

Response Status

Response Body

{
 "id": 1,
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "name": "personByCity",
 "fields": [
 "city"
 ],
 "index_type": "SECONDARY"
}

1.5.4 根据 name 删除 IndexLabel

删除 IndexLabel 会导致删除相关的索引数据，会产生一个异步任务

Rebuild API

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

1.6 Rebuild

1.6.1 重建 IndexLabel

Method & Url

PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/rebuild/indexlabels/personByCity

Response Status

Response Body

{
 "task_id": 1
}

注：

Vertex API

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

2.1 Vertex

顶点类型中的 Id 策略决定了顶点的 Id 类型，其对应的 id 类型如下：

Id_Strategy	id type
AUTOMATIC	number
PRIMARY_KEY	string
CUSTOMIZE_STRING	string
CUSTOMIZE_NUMBER	number
CUSTOMIZE_UUID	uuid

顶点的 GET/PUT/DELETE API 中 url 的 id 部分应该传入带有类型信息的 id 值，这个类型信息通过 json 串是否带引号来表示，也就是说：

Edge API

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

2.2 Edge

顶点 id 格式的修改也影响到了边的 id 以及源顶点和目标顶点 id 的格式

EdgeId 是由 src-vertex-id + direction + label + sort-values + tgt-vertex-id 拼接而成，但是这里的顶点 id 类型不是通过引号区分的，而是根据前缀区分：

Traverser API

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

3.1 traverser API 概述

HugeGraphServer 为 HugeGraph 图数据库提供了 RESTful API 接口。除了顶点和边的 CRUD 基本操作以外，还提供了一些遍历（traverser）方法，我们称为traverser API。这些遍历方法实现了一些复杂的图算法，方便用户对图进行分析和挖掘。

Rank API

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

4.1 rank API 概述

HugeGraphServer 除了上一节提到的遍历（traverser）方法，还提供了一类专门做推荐的方法，我们称为rank API，可在图中为一个点推荐与其关系密切的其它点。

Variable API

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

5.1 Variables

Variables 可以用来存储有关整个图的数据，数据按照键值对的方式存取

5.1.1 创建或者更新某个键值对

Method & Url

PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/variables/name

Request Body

{
 "data": "tom"
}

Response Status

Response Body

{
 "name": "tom"
}

5.1.2 列出全部键值对

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/variables

Response Status

Response Body

{
 "name": "tom"
}

5.1.3 列出某个键值对

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/variables/name

Response Status

Response Body

{
 "name": "tom"
}

5.1.4 删除某个键值对

Method & Url

DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/variables/name

Response Status

Graphs API

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

6.1 Graphs

重要提醒：1.7.0 及之后，动态创建图必须开启鉴权模式。非鉴权模式请参考图配置文件，通过配置文件静态创建图。

6.1.1 列出图空间中全部的图

Params

路径参数说明：

Task API

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

7.1 Task

7.1.1 列出某个图中全部的异步任务

Params

status: 异步任务的状态
limit：返回异步任务数目上限

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks?status=success

Response Status

Response Body

{
	"tasks": [{
		"task_name": "hugegraph.traversal().V()",
		"task_progress": 0,
		"task_create": 1532943976585,
		"task_status": "success",
		"task_update": 1532943976736,
		"task_result": "0",
		"task_retries": 0,
		"id": 2,
		"task_type": "gremlin",
		"task_callable": "org.apache.hugegraph.api.job.GremlinAPI$GremlinJob",
		"task_input": "{\"gremlin\":\"hugegraph.traversal().V()\",\"bindings\":{},\"language\":\"gremlin-groovy\",\"aliases\":{\"hugegraph\":\"graph\"}}"
	}]
}

7.1.2 查看某个异步任务的信息

Method & Url

GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2

Response Status

Response Body

{
	"task_name": "hugegraph.traversal().V()",
	"task_progress": 0,
	"task_create": 1532943976585,
	"task_status": "success",
	"task_update": 1532943976736,
	"task_result": "0",
	"task_retries": 0,
	"id": 2,
	"task_type": "gremlin",
	"task_callable": "org.apache.hugegraph.api.job.GremlinAPI$GremlinJob",
	"task_input": "{\"gremlin\":\"hugegraph.traversal().V()\",\"bindings\":{},\"language\":\"gremlin-groovy\",\"aliases\":{\"hugegraph\":\"graph\"}}"
}

7.1.3 删除某个异步任务信息，不删除异步任务本身

Method & Url

DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2

Response Status

7.1.4 取消某个异步任务，该异步任务必须具有处理中断的能力

假设已经通过Gremlin API创建了一个异步任务如下：

Gremlin API

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

8.1 Gremlin

8.1.1 向 HugeGraphServer 发送 gremlin 语句（GET），同步执行

Params

gremlin: 要发送给HugeGraphServer执行的gremlin语句
bindings: 用来绑定参数，key 是字符串，value 是绑定的值（只能是字符串或者数字），功能类似于 MySQL 的 Prepared Statement，用于加速语句执行
language: 发送语句的语言类型，默认为gremlin-groovy
aliases: 为存在于图空间的已有变量添加别名

查询顶点

Cypher API

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

9.1 Cypher

9.1.1 向 HugeGraphServer 发送 Cypher 语句（GET），同步执行

Method & Url

GET /graphspaces/{graphspace}/graphs/{graph}/cypher?cypher={cypher}

Params

路径参数说明：

Authentication API

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

10.1 用户认证与权限控制

开启权限及相关配置请先参考权限配置文档

用户认证与权限控制概述：

HugeGraph 支持多用户认证、以及细粒度的权限访问控制，采用基于“用户 - 用户组 - 操作 - 资源”的 4 层设计，灵活控制用户角色与权限。资源描述了图数据库中的数据，比如符合某一类条件的顶点，每一个资源包括 type、label、properties 三个要素，共有 18 种 type、任意 label、任意 properties 的组合形成的资源，一个资源的内部条件是且关系，多个资源之间的条件是或关系。用户可以属于一个或多个用户组，每个用户组可以拥有对任意个资源的操作权限，操作类型包括：读、写、删除、执行等种类。HugeGraph 支持动态创建用户、用户组、资源，支持动态分配或取消权限。初始化数据库时超级管理员用户被创建，后续可通过超级管理员创建各类角色用户，新创建的用户如果被分配足够权限后，可以由其创建或管理更多的用户。

Metrics API

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

HugeGraph 提供了获取监控信息的 Metrics 接口，比如各个 Gremlin 执行时间的统计、缓存的占用大小等。Metrics 接口包括如下几类：基础指标、统计指标、系统指标、后端存储指标。

Other API

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

11.1 Other

11.1.1 查看HugeGraph的版本信息

Method & Url

GET http://localhost:8080/versions

Response Status

Response Body

{
 "versions": {
 "version": "v1",
 "core": "0.4.5.1",
 "gremlin": "3.2.5",
 "api": "0.13.2.0"
 }
}