HugeGraph RESTful API on Apache HugeGraph

Schema API

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

1.1 Schema

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

Method & Url

GET http://localhost:8080/graphs/hugegraph/schema

Response Status

Response Body

{
 "propertykeys": [
 {
 "id": 7,
 "name": "price",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.741"
 }
 },
 {
 "id": 6,
 "name": "date",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.729"
 }
 },
 {
 "id": 3,
 "name": "city",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.691"
 }
 },
 {
 "id": 2,
 "name": "age",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.678"
 }
 },
 {
 "id": 5,
 "name": "lang",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.718"
 }
 },
 {
 "id": 4,
 "name": "weight",
 "data_type": "DOUBLE",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.707"
 }
 },
 {
 "id": 1,
 "name": "name",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.609"
 }
 }
 ],
 "vertexlabels": [
 {
 "id": 1,
 "name": "person",
 "id_strategy": "PRIMARY_KEY",
 "primary_keys": [
 "name"
 ],
 "nullable_keys": [
 "age"
 ],
 "index_labels": [
 "personByCity",
 "personByAgeAndCity"
 ],
 "properties": [
 "name",
 "age",
 "city"
 ],
 "status": "CREATED",
 "ttl": 0,
 "enable_label_index": true,
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.783"
 }
 },
 {
 "id": 2,
 "name": "software",
 "id_strategy": "PRIMARY_KEY",
 "primary_keys": [
 "name"
 ],
 "nullable_keys": [
 "price"
 ],
 "index_labels": [
 "softwareByPrice"
 ],
 "properties": [
 "name",
 "lang",
 "price"
 ],
 "status": "CREATED",
 "ttl": 0,
 "enable_label_index": true,
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.840"
 }
 }
 ],
 "edgelabels": [
 {
 "id": 1,
 "name": "knows",
 "source_label": "person",
 "target_label": "person",
 "frequency": "MULTIPLE",
 "sort_keys": [
 "date"
 ],
 "nullable_keys": [
 "weight"
 ],
 "index_labels": [
 "knowsByWeight"
 ],
 "properties": [
 "weight",
 "date"
 ],
 "status": "CREATED",
 "ttl": 0,
 "enable_label_index": true,
 "user_data": {
 "~create_time": "2021-09-03 15:13:41.840"
 }
 },
 {
 "id": 2,
 "name": "created",
 "source_label": "person",
 "target_label": "software",
 "frequency": "SINGLE",
 "sort_keys": [
 ],
 "nullable_keys": [
 "weight"
 ],
 "index_labels": [
 "createdByDate",
 "createdByWeight"
 ],
 "properties": [
 "weight",
 "date"
 ],
 "status": "CREATED",
 "ttl": 0,
 "enable_label_index": true,
 "user_data": {
 "~create_time": "2021-09-03 15:13:41.868"
 }
 }
 ],
 "indexlabels": [
 {
 "id": 1,
 "name": "personByCity",
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "index_type": "SECONDARY",
 "fields": [
 "city"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:40.886"
 }
 },
 {
 "id": 4,
 "name": "createdByDate",
 "base_type": "EDGE_LABEL",
 "base_value": "created",
 "index_type": "SECONDARY",
 "fields": [
 "date"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:41.878"
 }
 },
 {
 "id": 5,
 "name": "createdByWeight",
 "base_type": "EDGE_LABEL",
 "base_value": "created",
 "index_type": "RANGE_DOUBLE",
 "fields": [
 "weight"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:42.117"
 }
 },
 {
 "id": 2,
 "name": "personByAgeAndCity",
 "base_type": "VERTEX_LABEL",
 "base_value": "person",
 "index_type": "SECONDARY",
 "fields": [
 "age",
 "city"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:41.351"
 }
 },
 {
 "id": 3,
 "name": "softwareByPrice",
 "base_type": "VERTEX_LABEL",
 "base_value": "software",
 "index_type": "RANGE_INT",
 "fields": [
 "price"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:41.587"
 }
 },
 {
 "id": 6,
 "name": "knowsByWeight",
 "base_type": "EDGE_LABEL",
 "base_value": "knows",
 "index_type": "RANGE_DOUBLE",
 "fields": [
 "weight"
 ],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2021-09-03 15:13:42.376"
 }
 }
 ]
}

PropertyKey API

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

1.2 PropertyKey

Params说明：

name：属性类型名称，必填
data_type：属性类型数据类型，包括：bool、byte、int、long、float、double、string、date、uuid、blob，默认string类型
cardinality：属性类型基数，包括：single、list、set，默认single

请求体字段说明：

id：属性类型id值
properties：属性的属性，对于属性而言，此项为空
user_data：设置属性类型的通用信息，比如可设置age属性的取值范围，最小为0，最大为100；目前此项不做任何校验，只为后期拓展提供预留入口

1.2.1 创建一个 PropertyKey

Method & Url

POST http://localhost:8080/graphs/hugegraph/schema/propertykeys

Request Body

{
 "name": "age",
 "data_type": "INT",
 "cardinality": "SINGLE"
}

Response Status

Response Body

{
 "property_key": {
 "id": 1,
 "name": "age",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [],
 "status": "CREATED",
 "user_data": {
 "~create_time": "2022-05-13 13:47:23.745"
 }
 },
 "task_id": 0
}

1.2.2 为已存在的 PropertyKey 添加或移除 userdata

Params

action: 表示当前行为是添加还是移除，取值为append（添加）和eliminate（移除）

Method & Url

PUT http://localhost:8080/graphs/hugegraph/schema/propertykeys/age?action=append

Request Body

{
 "name": "age",
 "user_data": {
 "min": 0,
 "max": 100
 }
}

Response Status

Response Body

{
 "property_key": {
 "id": 1,
 "name": "age",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "aggregate_type": "NONE",
 "write_type": "OLTP",
 "properties": [],
 "status": "CREATED",
 "user_data": {
 "min": 0,
 "max": 100,
 "~create_time": "2022-05-13 13:47:23.745"
 }
 },
 "task_id": 0
}

1.2.3 获取所有的 PropertyKey

Method & Url

GET http://localhost:8080/graphs/hugegraph/schema/propertykeys

Response Status

Response Body

{
 "propertykeys": [
 {
 "id": 3,
 "name": "city",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 2,
 "name": "age",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 5,
 "name": "lang",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 4,
 "name": "weight",
 "data_type": "DOUBLE",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 6,
 "name": "date",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 1,
 "name": "name",
 "data_type": "TEXT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 },
 {
 "id": 7,
 "name": "price",
 "data_type": "INT",
 "cardinality": "SINGLE",
 "properties": [],
 "user_data": {}
 }
 ]
}

1.2.4 根据name获取PropertyKey

Method & Url

GET http://localhost:8080/graphs/hugegraph/schema/propertykeys/age

其中，age为要获取的PropertyKey的名字

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/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/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/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/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/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 Rebuild IndexLabel

Method & Url

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

Response Status

Response Body

{
 "task_id": 1
}

Note:

You can get the asynchronous job status by GET http://localhost:8080/graphs/hugegraph/tasks/${task_id} (the task_id here should be 1). See More AsyncJob RESTfull API

Vertex API

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

2.1 Vertex

顶点类型中的 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 串是否带引号表示，也就是说：

当 id 类型为 number 时，url 中的 id 不带引号，形如 xxx/vertices/123456
当 id 类型为 string 时，url 中的 id 带引号，形如 xxx/vertices/“123456”

接下来的示例均假设已经创建好了前述的各种 schema 信息

2.1.1 创建一个顶点

Method & Url

POST http://localhost:8080/graphs/hugegraph/graph/vertices

Request Body

{
 "label": "person",
 "properties": {
 "name": "marko",
 "age": 29
 }
}

Response Status

Response Body

{
 "id": "1:marko",
 "label": "person",
 "type": "vertex",
 "properties": {
 "name": [
 {
 "id": "1:marko>name",
 "value": "marko"
 }
 ],
 "age": [
 {
 "id": "1:marko>age",
 "value": 29
 }
 ]
 }
}

2.1.2 创建多个顶点

Method & Url

POST http://localhost:8080/graphs/hugegraph/graph/vertices/batch

Request Body

[
 {
 "label": "person",
 "properties": {
 "name": "marko",
 "age": 29
 }
 },
 {
 "label": "software",
 "properties": {
 "name": "ripple",
 "lang": "java",
 "price": 199
 }
 }
]

Response Status

Response Body

[
 "1:marko",
 "2:ripple"
]

2.1.3 更新顶点属性

Method & Url

PUT http://127.0.0.1:8080/graphs/hugegraph/graph/vertices/"1:marko"?action=append

Request Body

{
 "label": "person",
 "properties": {
 "age": 30,
 "city": "Beijing"
 }
}

注意：属性的取值是有三种类别的，分别是single、set和list。如果是single，表示增加或更新属性值；如果是set或list，则表示追加属性值。

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类型不是通过引号区分的，而是根据前缀区分：

当 id 类型为 number 时，EdgeId 的顶点 id 前有一个前缀L ，形如 “L123456>1»L987654”
当 id 类型为 string 时，EdgeId 的顶点 id 前有一个前缀S ，形如 “S1:peter>1»S2:lop”

接下来的示例均假设已经创建好了前述的各种schema和vertex信息

2.2.1 创建一条边

Params说明

label：边类型名称，必填
outV：源顶点id，必填
inV：目标顶点id，必填
outVLabel：源顶点类型。必填
inVLabel：目标顶点类型。必填
properties: 边关联的属性，对象内部结构为：
1. name：属性名称
2. value：属性值

Method & Url

POST http://localhost:8080/graphs/hugegraph/graph/edges

Request Body

{
 "label": "created",
 "outV": "1:peter",
 "inV": "2:lop",
 "outVLabel": "person",
 "inVLabel": "software",
 "properties": {
 "date": "2017-5-18",
 "weight": 0.2
 }
}

Response Status

Response Body

{
 "id": "S1:peter>1>>S2:lop",
 "label": "created",
 "type": "edge",
 "inVLabel": "software",
 "outVLabel": "person",
 "inV": "2:lop",
 "outV": "1:peter",
 "properties": {
 "date": "2017-5-18",
 "weight": 0.2
 }
}

2.2.2 创建多条边

Params

check_vertex: 是否检查顶点存在(true | false)，当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错。

Method & Url

POST http://localhost:8080/graphs/hugegraph/graph/edges/batch

Request Body

[
 {
 "label": "created",
 "outV": "1:peter",
 "inV": "2:lop",
 "outVLabel": "person",
 "inVLabel": "software",
 "properties": {
 "date": "2017-5-18",
 "weight": 0.2
 }
 },
 {
 "label": "knows",
 "outV": "1:marko",
 "inV": "1:vadas",
 "outVLabel": "person",
 "inVLabel": "person",
 "properties": {
 "date": "2016-01-10",
 "weight": 0.5
 }
 }
]

Response Status

Response Body

[
 "S1:peter>1>>S2:lop",
 "S1:marko>2>>S1:vadas"
]

2.2.3 更新边属性

Method & Url

PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action=append

Request Body

{
 "properties": {
 "weight": 1.0
 }
}

注意：属性的取值是有三种类别的，分别是single、set和list。如果是single，表示增加或更新属性值；如果是set或list，则表示追加属性值。

Traverser API

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

3.1 traverser API概述

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

HugeGraph支持的Traverser API包括：

K-out API，根据起始顶点，查找恰好N步可达的邻居，分为基础版和高级版：
- 基础版使用GET方法，根据起始顶点，查找恰好N步可达的邻居
- 高级版使用POST方法，根据起始顶点，查找恰好N步可达的邻居，与基础版的不同在于：
  - 支持只统计邻居数量
  - 支持边属性过滤
  - 支持返回到达邻居的最短路径
K-neighbor API，根据起始顶点，查找N步以内可达的所有邻居，分为基础版和高级版：
- 基础版使用GET方法，根据起始顶点，查找N步以内可达的所有邻居
- 高级版使用POST方法，根据起始顶点，查找N步以内可达的所有邻居，与基础版的不同在于：
  - 支持只统计邻居数量
  - 支持边属性过滤
  - 支持返回到达邻居的最短路径
Same Neighbors, 查询两个顶点的共同邻居
Jaccard Similarity API，计算jaccard相似度，包括两种：
- 一种是使用GET方法，计算两个顶点的邻居的相似度（交并比）
- 一种是使用POST方法，在全图中查找与起点的jaccard similarity最高的N个点
Shortest Path API，查找两个顶点之间的最短路径
All Shortest Paths，查找两个顶点间的全部最短路径
Weighted Shortest Path，查找起点到目标点的带权最短路径
Single Source Shortest Path，查找一个点到其他各个点的加权最短路径
Multi Node Shortest Path，查找指定顶点集之间两两最短路径
Paths API，查找两个顶点间的全部路径，分为基础版和高级版：
- 基础版使用GET方法，根据起点和终点，查找两个顶点间的全部路径
- 高级版使用POST方法，根据一组起点和一组终点，查找两个集合间符合条件的全部路径
Customized Paths API，从一批顶点出发，按（一种）模式遍历经过的全部路径
Template Path API，指定起点和终点以及起点和终点间路径信息，查找符合的路径
Crosspoints API，查找两个顶点的交点（共同祖先或者共同子孙）
Customized Crosspoints API，从一批顶点出发，按多种模式遍历，最后一步到达的顶点的交点
Rings API，从起始顶点出发，可到达的环路路径
Rays API，从起始顶点出发，可到达边界的路径（即无环路径）
Fusiform Similarity API，查找一个顶点的梭形相似点
Vertices API
- 按ID批量查询顶点；
- 获取顶点的分区；
- 按分区查询顶点；
Edges API
- 按ID批量查询边；
- 获取边的分区；
- 按分区查询边；

3.2. traverser API详解

使用方法中的例子，都是基于TinkerPop官网给出的图：

Rank API

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

4.1 Rank API overview

Not only the Graph iteration （traverser) method, HugeGraph-Server also provide Rank API for recommendation purpose. You can use it to recommend some vertexes much closer to a vertex.

4.2 Details of Rank API

4.2.1 Personal Rank API

A typical scenario for Personal Rank algorithm is in recommendation application. According to the out edges of a vertex, recommend some other vertices that having the same or similar edges.

Variable API

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

5.1 Variables

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

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

Method & Url

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

Request Body

{
 "data": "tom"
}

Response Status

Response Body

{
 "name": "tom"
}

5.1.2 列出全部键值对

Method & Url

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

Response Status

Response Body

{
 "name": "tom"
}

5.1.3 列出某个键值对

Method & Url

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

Response Status

Response Body

{
 "name": "tom"
}

5.1.4 删除某个键值对

Method & Url

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

Response Status

Graphs API

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

6.1 Graphs

6.1.1 List all graphs

Method & Url

GET http://localhost:8080/graphs

Response Status

Response Body

{
 "graphs": [
 "hugegraph",
 "hugegraph1"
 ]
}

6.1.2 Get details of the graph

Method & Url

GET http://localhost:8080/graphs/hugegraph

Response Status

Response Body

{
 "name": "hugegraph",
 "backend": "cassandra"
}

6.1.3 Clear all data of a graph，include: schema、vertex、edge and index .etc，This operation requires administrator privileges

Params

Since emptying the graph is a dangerous operation, we have added parameters for confirmation to the API to avoid false calls by users：

Task API

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

7.1 Task

7.1.1 List all async tasks in graph

Params

status: the status of asyncTasks
limit：the max number of tasks to return

Method & Url

GET http://localhost:8080/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": "com.baidu.hugegraph.api.job.GremlinAPI$GremlinJob",
		"task_input": "{\"gremlin\":\"hugegraph.traversal().V()\",\"bindings\":{},\"language\":\"gremlin-groovy\",\"aliases\":{\"hugegraph\":\"graph\"}}"
	}]
}

7.1.2 View the details of an async task

Method & Url

GET http://localhost:8080/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": "com.baidu.hugegraph.api.job.GremlinAPI$GremlinJob",
	"task_input": "{\"gremlin\":\"hugegraph.traversal().V()\",\"bindings\":{},\"language\":\"gremlin-groovy\",\"aliases\":{\"hugegraph\":\"graph\"}}"
}

7.1.3 Delete task information of an async task，won’t delete the task itself

Method & Url

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

Response Status

7.1.4 Cancel an async task, the task should be able to be canceled

If you already created an async task via Gremlin API as follows：

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: 为存在于图空间的已有变量添加别名

查询顶点

Method & Url

GET http://127.0.0.1:8080/gremlin?gremlin=hugegraph.traversal().V('1:marko')

Response Status

Response Body

{
	"requestId": "c6ef47a8-b634-4b07-9d38-6b3b69a3a556",
	"status": {
		"message": "",
		"code": 200,
		"attributes": {}
	},
	"result": {
		"data": [{
			"id": "1:marko",
			"label": "person",
			"type": "vertex",
			"properties": {
				"city": [{
					"id": "1:marko>city",
					"value": "Beijing"
				}],
				"name": [{
					"id": "1:marko>name",
					"value": "marko"
				}],
				"age": [{
					"id": "1:marko>age",
					"value": 29
				}]
			}
		}],
		"meta": {}
	}
}

8.1.2 向HugeGraphServer发送gremlin语句（POST），同步执行

Method & Url

POST http://localhost:8080/gremlin

查询顶点

Authentication API

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

9.1 用户认证与权限控制

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

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

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

举例说明：

user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, resource={label: person, city: Beijing})
描述：用户’boss’拥有对’graph1’图中北京人的读权限。

接口说明：

用户认证与权限控制接口包括5类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。

9.2 用户（User）API

用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。

9.2.1 创建用户

Params

user_name: 用户名称
user_password: 用户密码
user_phone: 用户手机号
user_email: 用户邮箱

其中 user_name 和 user_password 为必填。

Other API

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

10.1 Other

10.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"
 }
}