4.7.联机算法

4.7.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，查找一个顶点的梭形相似点
• Adamic-Adar API，查找两顶点间的紧密度系数, 会忽略超级顶点的权值影响
• Resource Allocation API，查找两顶点间的紧密度系数, 会算入超级顶点的权值影响
• Same Neighbors Batch

PS: Vertices API & Edges API 移动至 Vertex 与 Edge 页面中

4.7.2.traverser API详解

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

数据导入程序如下：

public class Loader {
    public static void main(String[] args) {
        HugeClient client = new HugeClient("http://127.0.0.1:8080", "hugegraph");
        SchemaManager schema = client.schema();
        schema.propertyKey("name").asText().ifNotExist().create();
        schema.propertyKey("age").asInt().ifNotExist().create();
        schema.propertyKey("city").asText().ifNotExist().create();
        schema.propertyKey("weight").asDouble().ifNotExist().create();
        schema.propertyKey("lang").asText().ifNotExist().create();
        schema.propertyKey("date").asText().ifNotExist().create();
        schema.propertyKey("price").asInt().ifNotExist().create();

        schema.vertexLabel("person")
              .properties("name", "age", "city")
              .primaryKeys("name")
              .nullableKeys("age")
              .ifNotExist()
              .create();

        schema.vertexLabel("software")
              .properties("name", "lang", "price")
              .primaryKeys("name")
              .nullableKeys("price")
              .ifNotExist()
              .create();

        schema.indexLabel("personByCity")
              .onV("person")
              .by("city")
              .secondary()
              .ifNotExist()
              .create();

        schema.indexLabel("personByAgeAndCity")
              .onV("person")
              .by("age", "city")
              .secondary()
              .ifNotExist()
              .create();

        schema.indexLabel("softwareByPrice")
              .onV("software")
              .by("price")
              .range()
              .ifNotExist()
              .create();

        schema.edgeLabel("knows")
              .multiTimes()
              .sourceLabel("person")
              .targetLabel("person")
              .properties("date", "weight")
              .sortKeys("date")
              .nullableKeys("weight")
              .ifNotExist()
              .create();

        schema.edgeLabel("created")
              .sourceLabel("person").targetLabel("software")
              .properties("date", "weight")
              .nullableKeys("weight")
              .ifNotExist()
              .create();

        schema.indexLabel("createdByDate")
              .onE("created")
              .by("date")
              .secondary()
              .ifNotExist()
              .create();

        schema.indexLabel("createdByWeight")
              .onE("created")
              .by("weight")
              .range()
              .ifNotExist()
              .create();

        schema.indexLabel("knowsByWeight")
              .onE("knows")
              .by("weight")
              .range()
              .ifNotExist()
              .create();

        GraphManager graph = client.graph();
        Vertex marko = graph.addVertex(T.label, "person", "name", "marko",
                                       "age", 29, "city", "Beijing");
        Vertex vadas = graph.addVertex(T.label, "person", "name", "vadas",
                                       "age", 27, "city", "Hongkong");
        Vertex lop = graph.addVertex(T.label, "software", "name", "lop",
                                     "lang", "java", "price", 328);
        Vertex josh = graph.addVertex(T.label, "person", "name", "josh",
                                      "age", 32, "city", "Beijing");
        Vertex ripple = graph.addVertex(T.label, "software", "name", "ripple",
                                        "lang", "java", "price", 199);
        Vertex peter = graph.addVertex(T.label, "person", "name", "peter",
                                       "age", 35, "city", "Shanghai");

        marko.addEdge("knows", vadas, "date", "20160110", "weight", 0.5);
        marko.addEdge("knows", josh, "date", "20130220", "weight", 1.0);
        marko.addEdge("created", lop, "date", "20171210", "weight", 0.4);
        josh.addEdge("created", lop, "date", "20091111", "weight", 0.4);
        josh.addEdge("created", ripple, "date", "20171210", "weight", 1.0);
        peter.addEdge("created", lop, "date", "20170324", "weight", 0.2);
    }
}

顶点ID为：

"2:ripple",
"1:vadas",
"1:peter",
"1:josh",
"1:marko",
"2:lop"

边ID为：

"S1:peter>2>>S2:lop",
"S1:josh>2>>S2:lop",
"S1:josh>2>>S2:ripple",
"S1:marko>1>20130220>S1:josh",
"S1:marko>1>20160110>S1:vadas",
"S1:marko>2>>S2:lop"

4.7.2.1.K-out API（GET，基础版）

功能介绍

根据起始顶点、方向、边的类型（可选）和深度depth，查找从起始顶点出发恰好depth步可达的顶点

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/kout

URI参数

Body参数

无

Response

表1

使用示例

Method & Url

GET http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/kout?source="1:marko"&max_depth=2

Response Status

200

Response Body

{
    "vertices":[
        "2:ripple",
        "1:peter"
    ],
    "measure": {
        "cost": 423133,
        "vertice_iters": 562243,
        "edge_iters": 223748444
    }
}

适用场景

查找恰好N步关系可达的顶点。两个例子：

• 家族关系中，查找一个人的所有孙子，person A通过连续的两条“儿子”边到达的顶点集合。
• 社交关系中发现潜在好友，例如：与目标用户相隔两层朋友关系的用户，可以通过连续两条“朋友”边到达的顶点。

4.7.2.2.K-out API（POST，高级版）

功能介绍

根据起始顶点、步骤（包括方向、边类型和过滤属性）和深度depth，查找从起始顶点出发恰好depth步可达的顶点。

与K-out基础版的不同在于：

• 支持只统计邻居数量
• 支持边属性过滤
• 支持返回到达邻居的最短路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/kout

URI参数

Body参数

表1 Steps 对象

表2 点边Step

Response

表1

使用示例

Method & Url

POST http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/kout

Request Body

{
    "source": "1:marko", 
    "steps": {
        "direction": "BOTH",
        "edge_steps": [
            {
                "label": "knows"
            },
            {
                "label": "created",
                "properties": {}
            }
        ],
        "vertex_steps": [
            {
                "label": "person",
                "properties": {
                    "age": "P.gt(25)"
                }
            },
            {
                "label": "software",
                "properties": {}
            }
        ],
        "max_degree": 10000,
        "skip_degree": 100000
    },
    "max_depth": 1,
    "nearest": true,
    "limit": 10000,
    "with_vertex": true,
    "with_path": true
}

Response Status

200

Response Body

{
    "size": 3,
    "kout": [
        "1:josh",
        "1:vadas",
        "2:lop"
    ],
    "paths": [
        {
            "objects": [
                "1:marko",
                "1:josh"
            ]
        },
        {
            "objects": [
                "1:marko",
                "1:vadas"
            ]
        },
        {
            "objects": [
                "1:marko",
                "2:lop"
            ]
        }
    ],
    "vertices": [
        {
            "id": "1:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "1:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "1:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "2:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "lop",
                "lang": "java",
                "price": 328
            }
        }
    ],
    "measure": {
        "cost": 423133,
        "vertice_iters": 562243,
        "edge_iters": 223748444
    }
}

适用场景

参见 4.7.2.1. kout

4.7.2.3.K-neighbor（GET，基础版）

功能介绍

根据起始顶点、方向、边的类型（可选）和深度depth，查找包括起始顶点在内、depth步之内可达的所有顶点

相当于：起始顶点、K-out(1)、K-out(2)、... 、K-out(max_depth)的并集

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/kneighbor

URI参数

Body参数

无

Response

表1

使用示例

Method & Url

GET http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/kneighbor?source="1:marko"&max_depth=2

Response Status

200

Response Body

{
    "vertices":[
        "2:ripple",
        "1:marko",
        "1:josh",
        "1:vadas",
        "1:peter",
        "2:lop"
    ],
    "measure": {
        "cost": 423133,
        "vertice_iters": 562243,
        "edge_iters": 223748444
    }
}

适用场景

查找N步以内可达的所有顶点，例如：

• 家族关系中，查找一个人五服以内所有子孙，person A通过连续的5条“亲子”边到达的顶点集合。
• 社交关系中发现好友圈子，例如目标用户通过1条、2条、3条“朋友”边可到达的用户可以组成目标用户的朋友圈子

4.7.2.4.K-neighbor API（POST，高级版）

功能介绍

根据起始顶点、步骤（包括方向、边类型和过滤属性）和深度depth，查找从起始顶点出发depth步内可达的所有顶点。

与K-neighbor基础版的不同在于：

• 支持只统计邻居数量
• 支持边属性过滤
• 支持返回到达邻居的最短路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/kneighbor

URI参数

Body参数

表1 Steps 对象

表2 点边Steps

Response

表1

使用示例

Method & Url

POST http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/kneighbor

Request Body

{
    "source": "1:marko",
    "steps": {
        "direction": "BOTH",
        "edge_steps": [
            {
                "label": "knows"
            },
            {
                "label": "created",
                "properties": {}
            }
        ],
        "vertex_steps": [
            {
                "label": "person",
                "properties": {
                    "age": "P.gt(25)"
                }
            },
            {
                "label": "software",
                "properties": {}
            }
        ],
        "max_degree": 10000,
        "skip_degree": 100000
    },
    "max_depth": 3,
    "limit": 10000,
    "with_vertex": true,
    "with_path": true
}

Response Status

200

Response Body

{
    "size": 6,
    "kneighbor": [
        "2:ripple",
        "1:marko",
        "1:josh",
        "1:vadas",
        "1:peter",
        "2:lop"
    ],
    "paths": [
        {
            "objects": [
                "1:marko",
                "1:josh",
                "2:ripple"
            ]
        },
        {
            "objects": [
                "1:marko"
            ]
        },
        {
            "objects": [
                "1:marko",
                "1:josh"
            ]
        },
        {
            "objects": [
                "1:marko",
                "1:vadas"
            ]
        },
        {
            "objects": [
                "1:marko",
                "2:lop",
                "1:peter"
            ]
        },
        {
            "objects": [
                "1:marko",
                "2:lop"
            ]
        }
    ],
    "vertices": [
        {
            "id": "2:ripple",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "ripple",
                "lang": "java",
                "price": 199
            }
        },
        {
            "id": "1:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "1:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "1:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "1:peter",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "peter",
                "age": 35,
                "city": "Shanghai"
            }
        },
        {
            "id": "2:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "lop",
                "lang": "java",
                "price": 328
            }
        }
    ],
    "measure": {
        "cost": 423133,
        "vertice_iters": 562243,
        "edge_iters": 223748444
    }
}

适用场景

参见K-neighbor

4.7.2.5.Same Neighbors

功能介绍

查询两个点的共同邻居

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/sameneighbors

URI参数

Body参数

无

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/sameneighbors?vertex="1:marko"&other="1:josh"

Response Status

200

Response Body

{
    "same_neighbors":[
        "2:lop"
    ]
}

适用场景

查找两个顶点的共同邻居：

• 社交关系中发现两个用户的共同粉丝或者共同关注用户

4.7.2.6.Jaccard Similarity（GET）

功能介绍

计算两个顶点的jaccard similarity（两个顶点邻居的交集比上两个顶点邻居的并集）

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/jaccardsimilarity

URI参数

Body参数

无

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/jaccardsimilarity?vertex="1:marko"&other="1:josh"

Response Status

200

Response Body

{
    "jaccard_similarity": 0.2
}

适用场景

用于评估两个点的相似性或者紧密度

4.7.2.7.Jaccard Similarity（POST）

功能介绍

计算与指定顶点的jaccard similarity最大的N个点

jaccard similarity的计算方式为：两个顶点邻居的交集比上两个顶点邻居的并集

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/kneighbor

URI参数

Body参数

表1 Steps 对象

表2 点边Steps

Response

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/jaccardsimilarity

Request Body

{
  "vertex": "1:marko",
  "step": {
    "direction": "BOTH",
    "labels": [],
    "max_degree": 10000,
    "skip_degree": 100000
  },
  "top": 3
}

Response Status

200

Response Body

{
    "2:ripple": 0.3333333333333333,
    "1:peter": 0.3333333333333333,
    "1:josh": 0.2
}

适用场景

用于在图中找出与指定顶点相似性最高的顶点

4.7.2.8.Shortest Path

功能介绍

根据起始顶点、目的顶点、方向、边的类型（可选）和最大深度，查找一条最短路径

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/shortestpath

URI参数

Body参数

无

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/graphspace/graphs/graph/traversers/shortestpath?source="1:marko"&target="2:ripple"&max_depth=3

Response Status

200

Response Body

{
    "path":[
        "1:marko",
        "1:josh",
        "2:ripple"
    ]
}

适用场景

查找两个顶点间的最短路径，例如：

• 社交关系网中，查找两个用户有关系的最短路径，即最近的朋友关系链
• 设备关联网络中，查找两个设备最短的关联关系

4.7.2.9.查找最短路径

功能介绍

根据起始顶点、目的顶点、方向、边的类型（可选）和最大深度，查找两点间所有的最短路径

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/allshortestpaths

URI参数

Body参数

Response

表1 paths对象

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/allshortestpaths?source="A"&target="Z"&max_depth=10

Response Status

200

Response Body

{
    "paths":[
        {
            "objects": [
                "A",
                "B",
                "C",
                "Z"
            ]
        },
        {
            "objects": [
                "A",
                "M",
                "N",
                "Z"
            ]
        }
    ]
}

适用场景

查找两个顶点间的所有最短路径，例如：

• 社交关系网中，查找两个用户有关系的全部最短路径，即最近的朋友关系链
• 设备关联网络中，查找两个设备全部的最短关联关系

4.7.2.10.查找带权重的最短路径

功能介绍

根据起始顶点、目的顶点、方向、边的类型（可选）和最大深度，查找一条带权最短路径

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/weightedshortestpath

URI参数

Body参数

Response

表1 path对象

表2 vertex对象

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/weightedshortestpath?source="1:marko"&target="2:ripple"&weight="weight"&with_vertex=true

Response Status

200

Response Body

{
    "path": {
        "weight": 2.0,
        "vertices": [
            "1:marko",
            "1:josh",
            "2:ripple"
        ]
    },
    "vertices": [
        {
            "id": "1:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "1:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "2:ripple",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "ripple",
                "lang": "java",
                "price": 199
            }
        }
    ]
}

适用场景

查找两个顶点间的带权最短路径，例如：

• 交通线路中查找从A城市到B城市花钱最少的交通方式

4.7.2.11.(从一个顶点出发)查找最短路径

功能介绍

从一个顶点出发，查找该点到图中其他顶点的最短路径（可选是否带权重）

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/singlesourceshortestpath

URI参数

Body参数

Response

表1 path对象

表2 vertex对象

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/singlesourceshortestpath?source="1:marko"&with_vertex=true

Response Status

200

Response Body

{
    "paths": {
        "2:ripple": {
            "weight": 2.0,
            "vertices": [
                "1:marko",
                "1:josh",
                "2:ripple"
            ]
        },
        "1:josh": {
            "weight": 1.0,
            "vertices": [
                "1:marko",
                "1:josh"
            ]
        },
        "1:vadas": {
            "weight": 1.0,
            "vertices": [
                "1:marko",
                "1:vadas"
            ]
        },
        "1:peter": {
            "weight": 2.0,
            "vertices": [
                "1:marko",
                "2:lop",
                "1:peter"
            ]
        },
        "2:lop": {
            "weight": 1.0,
            "vertices": [
                "1:marko",
                "2:lop"
            ]
        }
    },
    "vertices": [
        {
            "id": "2:ripple",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "ripple",
                "lang": "java",
                "price": 199
            }
        },
        {
            "id": "1:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "1:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "1:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "1:peter",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "peter",
                "age": 35,
                "city": "Shanghai"
            }
        },
        {
            "id": "2:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "lop",
                "lang": "java",
                "price": 328
            }
        }
    ]
}

适用场景

查找从一个点出发到其他顶点的带权最短路径，比如：

• 查找从北京出发到全国其他所有城市的耗时最短的乘车方案

4.7.2.12.(指定顶点集)查找最短路径

功能介绍

查找指定顶点集两两之间的最短路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/multinodeshortestpath

URI参数

Body参数

表1 vertices对象

表2 step对象

Response

表1 path对象

表2 vertex对象

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/multinodeshortestpath

Request Body

{
    "vertices": {
        "ids": ["382:marko", "382:josh", "382:vadas", "382:peter", "383:lop", "383:ripple"]
    },
    "step": {
        "direction": "BOTH",
        "properties": {
        }
    },
    "max_depth": 10,
    "capacity": 100000000,
    "with_vertex": true
}

Response Status

200

Response Body

{
    "paths": [
        {
            "objects": [
                "382:peter",
                "383:lop"
            ]
        },
        {
            "objects": [
                "382:peter",
                "383:lop",
                "382:marko"
            ]
        },
        {
            "objects": [
                "382:peter",
                "383:lop",
                "382:josh"
            ]
        },
        {
            "objects": [
                "382:peter",
                "383:lop",
                "382:marko",
                "382:vadas"
            ]
        },
        {
            "objects": [
                "383:lop",
                "382:marko"
            ]
        },
        {
            "objects": [
                "383:lop",
                "382:josh"
            ]
        },
        {
            "objects": [
                "383:lop",
                "382:marko",
                "382:vadas"
            ]
        },
        {
            "objects": [
                "382:peter",
                "383:lop",
                "382:josh",
                "383:ripple"
            ]
        },
        {
            "objects": [
                "382:marko",
                "382:josh"
            ]
        },
        {
            "objects": [
                "383:lop",
                "382:josh",
                "383:ripple"
            ]
        },
        {
            "objects": [
                "382:marko",
                "382:vadas"
            ]
        },
        {
            "objects": [
                "382:marko",
                "382:josh",
                "383:ripple"
            ]
        },
        {
            "objects": [
                "382:josh",
                "383:ripple"
            ]
        },
        {
            "objects": [
                "382:josh",
                "382:marko",
                "382:vadas"
            ]
        },
        {
            "objects": [
                "382:vadas",
                "382:marko",
                "382:josh",
                "383:ripple"
            ]
        }
    ],
    "vertices": [
        {
            "id": "382:peter",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "peter",
                "age": 29,
                "city": "Shanghai"
            }
        },
        {
            "id": "383:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "lop",
                "lang": "java",
                "price": 328
            }
        },
        {
            "id": "382:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "382:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "382:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "383:ripple",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "ripple",
                "lang": "java",
                "price": 199
            }
        }
    ]
}

适用场景

查找多个点之间的最短路径，比如：

• 查找多个公司和法人之间的最短路径

4.7.2.13.查找所有路径（GET，基础版）

功能介绍

根据起始顶点、目的顶点、方向、边的类型（可选）和最大深度等条件查找所有路径

URI

GET /graphspaces/${graphspace}/graphs/${graph}/traversers/paths

URI参数

Body参数

Response

表1 paths对象

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/paths?source="1:marko"&target="1:josh"&max_depth=5

Response Status

200

Response Body

{
    "paths":[
        {
            "objects":[
                "1:marko",
                "1:josh"
            ]
        },
        {
            "objects":[
                "1:marko",
                "2:lop",
                "1:josh"
            ]
        }
    ]
}

适用场景

查找两个顶点间的所有路径，例如：

• 社交网络中，查找两个用户所有可能的关系路径
• 设备关联网络中，查找两个设备之间所有的关联路径

4.7.2.14.查找所有路径（POST，高级版）

功能介绍

根据起始顶点、目的顶点、步骤（step）和最大深度等条件查找所有路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/paths

URI参数

Body参数

表1 vertices对象

表2 step对象

Response

表1 paths对象

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/paths

Request Body

{
"sources": {
  "ids": ["1:marko"]
},
"targets": {
  "ids": ["1:peter"]
},
"step": {
"direction": "BOTH",
  "properties": {
    "weight": "P.gt(0.01)"
  }
},
"max_depth": 10,
"capacity": 100000000,
"limit": 10000000,
"with_vertex": false
}

Response Status

200

Response Body

{
    "paths": [
        {
            "objects": [
                "1:marko",
                "1:josh",
                "2:lop",
                "1:peter"
            ]
        },
        {
            "objects": [
                "1:marko",
                "2:lop",
                "1:peter"
            ]
        }
    ]
}

适用场景

查找两个顶点间的所有路径，例如：

• 社交网络中，查找两个用户所有可能的关系路径
• 设备关联网络中，查找两个设备之间所有的关联路径

4.7.2.15.自定义路径查询

功能介绍

根据一批起始顶点、边规则（包括方向、边的类型和属性过滤）和最大深度等条件查找符合条件的所有的路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/customizedpaths

URI参数

Body参数

表1 vertices对象

表2 step对象

Response

表1 paths对象

表2 vertex对象

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/customizedpaths

Request Body

{
    "sources":{
        "ids":[

        ],
        "label":"person",
        "properties":{
            "name":"marko"
        }
    },
    "steps":[
        {
            "direction":"OUT",
            "labels":[
                "knows"
            ],
            "weight_by":"weight",
            "max_degree":-1
        },
        {
            "direction":"OUT",
            "labels":[
                "created"
            ],
            "default_weight":8,
            "max_degree":-1,
            "sample":1
        }
    ],
    "sort_by":"INCR",
    "with_vertex":true,
    "capacity":-1,
    "limit":-1
}

Response Status

200

Response Body

{
    "paths":[
        {
            "objects":[
                "1:marko",
                "1:josh",
                "2:lop"
            ]
        }
    ],
    "vertices":[
        {
            "id":"1:marko",
            "label":"person",
            "type":"vertex",
            "properties":{
                "city": "Beijing",
                "name": "marko",
                "age": 29
            }
        },
        {
            "id":"1:josh",
            "label":"person",
            "type":"vertex",
            "properties":{
                "city": "Beijing",
                "name": "josh",
                "age": 32
            }
        },
        {
            "id":"2:lop",
            "label":"software",
            "type":"vertex",
            "properties":{
                "price": 328,
                "name": "lop",
                "lang": "java"
            }
        }
    ]
}

适用场景

适合查找各种复杂的路径集合，例如：

• 社交网络中，查找看过张艺谋所导演的电影的用户关注的大V的路径（张艺谋--->电影---->用户--->大V）
• 风控网络中，查找多个高风险用户的直系亲属的朋友的路径（高风险用户--->直系亲属--->朋友）

4.7.2.16.模版路径查询

功能介绍

根据一批起始顶点、边规则（包括方向、边的类型和属性过滤）和最大深度等条件查找符合条件的所有的路径

URI

POST /graphspaces/${graphspace}/graphs/${graph}/traversers/templatepaths

URI参数

Body参数

表1 vertices对象

表2 step对象

Response

表1 paths对象

表2 vertex对象

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/templatepaths

Request Body

{
  "sources": {
    "ids": [],
    "label": "person",
    "properties": {
      "name": "vadas"
    }
  },
  "targets": {
    "ids": [],
    "label": "software",
    "properties": {
      "name": "ripple"
    }
  },
  "steps": [
    {
      "direction": "IN",
      "labels": ["knows"],
      "properties": {
      },
      "max_degree": 10000,
      "skip_degree": 100000
    },
    {
      "direction": "OUT",
      "labels": ["created"],
      "properties": {
      },
      "max_degree": 10000,
      "skip_degree": 100000
    },
    {
      "direction": "IN",
      "labels": ["created"],
      "properties": {
      },
      "max_degree": 10000,
      "skip_degree": 100000
    },
    {
      "direction": "OUT",
      "labels": ["created"],
      "properties": {
      },
      "max_degree": 10000,
      "skip_degree": 100000
    }
  ],
  "capacity": 10000,
  "limit": 10,
  "with_vertex": true
}

Response Status

200

Response Body

{
    "paths": [
        {
            "objects": [
                "1:vadas",
                "1:marko",
                "2:lop",
                "1:josh",
                "2:ripple"
            ]
        }
    ],
    "vertices": [
        {
            "id": "2:ripple",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "ripple",
                "lang": "java",
                "price": 199
            }
        },
        {
            "id": "1:marko",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "marko",
                "age": 29,
                "city": "Beijing"
            }
        },
        {
            "id": "1:josh",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "josh",
                "age": 32,
                "city": "Beijing"
            }
        },
        {
            "id": "1:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "2:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "name": "lop",
                "lang": "java",
                "price": 328
            }
        }
    ]
}

适用场景

适合查找各种复杂的模板路径，比如personA -(朋友)-> personB -(同学)-> personC，其中"朋友"和"同学"边可以分别是最多3层和4层的情况

4.7.2.17.Crosspoints

功能介绍

根据起始顶点、目的顶点、方向、边的类型（可选）和最大深度等条件查找相交点

URI

GET graphspaces/${graphspace}/graphs/${graph}/traversers/crosspoints

URI参数

Body参数

无

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/crosspoints?source="2:lop"&target="2:ripple"&max_depth=5&direction=IN

Response Body

{
    "crosspoints":[
        {
            "crosspoint":"1:josh",
            "objects":[
                "2:lop",
                "1:josh",
                "2:ripple"
            ]
        }
    ]
}

Response Status

200

适用场景

查找两个顶点的交点及其路径，例如：

• 社交网络中，查找两个用户共同关注的话题或者大V
• 家族关系中，查找共同的祖先

4.7.2.18.Customized Crosspoints

功能介绍

根据一批起始顶点、多种边规则（包括方向、边的类型和属性过滤）和最大深度等条件查找符合条件的所有的路径终点的交集

URI

POST graphspaces/${graphspace}/graphs/${graph}/traversers/customizedcrosspoints

URI参数

无

Body参数

表1 vertices对象

Response

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/customizedcrosspoints

Request Body

{
    "sources":{
        "ids":[
            "2:lop",
            "2:ripple"
        ]
    },
    "path_patterns":[
        {
            "steps":[
                {
                    "direction":"IN",
                    "labels":[
                        "created"
                    ],
                    "max_degree":-1
                }
            ]
        }
    ],
    "with_path":true,
    "with_vertex":true,
    "capacity":-1,
    "limit":-1
}

Response Status

200

Response Body

{
    "crosspoints":[
        "1:josh"
    ],
    "paths":[
        {
            "objects":[
                "2:ripple",
                "1:josh"
            ]
        },
        {
            "objects":[
                "2:lop",
                "1:josh"
            ]
        }
    ],
    "vertices":[
        {
            "id":"2:ripple",
            "label":"software",
            "type":"vertex",
            "properties":{
                "price":[
                    {
                        "id":"2:ripple>price",
                        "value":199
                    }
                ],
                "name":[
                    {
                        "id":"2:ripple>name",
                        "value":"ripple"
                    }
                ],
                "lang":[
                    {
                        "id":"2:ripple>lang",
                        "value":"java"
                    }
                ]
            }
        },
        {
            "id":"1:josh",
            "label":"person",
            "type":"vertex",
            "properties":{
                "city":[
                    {
                        "id":"1:josh>city",
                        "value":"Beijing"
                    }
                ],
                "name":[
                    {
                        "id":"1:josh>name",
                        "value":"josh"
                    }
                ],
                "age":[
                    {
                        "id":"1:josh>age",
                        "value":32
                    }
                ]
            }
        },
        {
            "id":"2:lop",
            "label":"software",
            "type":"vertex",
            "properties":{
                "price":[
                    {
                        "id":"2:lop>price",
                        "value":328
                    }
                ],
                "name":[
                    {
                        "id":"2:lop>name",
                        "value":"lop"
                    }
                ],
                "lang":[
                    {
                        "id":"2:lop>lang",
                        "value":"java"
                    }
                ]
            }
        }
    ]
}

适用场景

查询一组顶点通过多种路径在终点有交集的情况。例如：

• 在商品图谱中，多款手机、学习机、游戏机通过不同的低级别的类目路径，最终都属于一级类目的电子设备

4.7.2.19.Rings

功能介绍

根据起始顶点、方向、边的类型（可选）和最大深度等条件查找可达的环路

例如：1 -> 25 -> 775 -> 14690 -> 25, 其中环路为 25 -> 775 -> 14690 -> 25

URI

GET graphspaces/${graphspace}/graphs/${graph}/traversers/rings

URI参数

Body参数

无

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/rings?source="1:marko"&max_depth=3

Response Status

200

Response Body

{
    "rings":[
        {
            "objects":[
                "1:marko",
                "1:josh",
                "2:lop",
                "1:marko"
            ]
        }
    ]
}

适用场景

查询起始顶点可达的环路，例如：

• 风控项目中，查询一个用户可达的循环担保的人或者设备
• 设备关联网络中，发现一个设备周围的循环引用的设备

4.7.2.20.Rays

功能介绍

根据起始顶点、方向、边的类型（可选）和最大深度等条件查找发散到边界顶点的路径

例如：1 -> 25 -> 775 -> 14690 -> 2289 -> 18379, 其中 18379 为边界顶点，即没有从 18379 发出的边

URI

GET graphspaces/${graphspace}/graphs/${graph}/traversers/rays

URI参数

Body参数

无

Response

使用示例

Method & Url

GET graphspaces/${graphspace}/graphs/${graph}/traversers/rays?source="1:marko"&max_depth=2&direction=OUT

Response Status

200

Response Body

{
    "rays":[
        {
            "objects":[
                "1:marko",
                "1:vadas"
            ]
        },
        {
            "objects":[
                "1:marko",
                "2:lop"
            ]
        },
        {
            "objects":[
                "1:marko",
                "1:josh",
                "2:ripple"
            ]
        },
        {
            "objects":[
                "1:marko",
                "1:josh",
                "2:lop"
            ]
        }
    ]
}

适用场景

查找起始顶点到某种关系的边界顶点的路径，例如：

• 家族关系中，查找一个人到所有还没有孩子的子孙的路径
• 设备关联网络中，找到某个设备到终端设备的路径

4.7.2.21.Fusiform Similarity

功能介绍

按照条件查询一批顶点对应的"梭形相似点"。当两个顶点跟很多共同的顶点之间有某种关系的时候，我们认为这两个点为"梭形相似点"。举个例子说明"梭形相似点"："读者A"读了100本书，可以定义读过这100本书中的80本以上的读者，是"读者A"的"梭形相似点"

URI

POST graphspaces/${graphspace}/graphs/${graph}/traversers/fusiformsimilarity

URI参数

无

Body参数

表1 vertices对象

Response

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/hugegraph/traversers/fusiformsimilarity

Request Body

{
    "sources":{
        "ids":[],
        "label": "person",
        "properties": {
            "name":"p1"
        }
    },
    "label":"read",
    "direction":"OUT",
    "min_neighbors":8,
    "alpha":0.75,
    "min_similars":1,
    "top":0,
    "group_property":"city",
    "min_groups":2,
    "max_degree": 10000,
    "capacity": -1,
    "limit": -1,
    "with_intermediary": false,
    "with_vertex":true
}

Response Status

200

Response Body

{
    "similars": {
        "3:p1": [
            {
                "id": "3:p2",
                "score": 0.8888888888888888,
                "intermediaries": [
                ]
            },
            {
                "id": "3:p3",
                "score": 0.7777777777777778,
                "intermediaries": [
                ]
            }
        ]
    },
    "vertices": [
        {
            "id": "3:p1",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "p1",
                "city": "Beijing"
            }
        },
        {
            "id": "3:p2",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "p2",
                "city": "Shanghai"
            }
        },
        {
            "id": "3:p3",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "p3",
                "city": "Beijing"
            }
        }
    ]
}

适用场景

查询一组顶点相似度很高的顶点。例如：

• 跟一个读者有类似书单的读者
• 跟一个玩家玩类似游戏的玩家

4.7.2.22.Adamic Adar

AdamicAdar, 一般简称 AA 算法

功能介绍

主要用于社交网络中判断两点紧密度的算法, 用来求两点间共同邻居密集度的一个系数表示 (>0)

URI

GET graphspaces/${graphspace}/graphs/${graph}/traversers/adamicadar

URI参数

Body参数

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/adamicadar?vertex="1:marko"&other="1:josh"

Response Status

200

Response Body

{
  "adamic_adar": 0.3
}

适用场景

判断两个银行账户的关系紧密程度, 是共同邻居的改进系数版, 并且可以减少超级顶点在其中的权重影响

4.7.2.23.Resource Allocation

ResourceAllocation(RA), 一般称为资源分配算法

功能介绍

主要用于社交网络中判断两点紧密度的算法, 用来求两点间共同邻居密集度的一个系数表示 (>0), 与 AA 算法比较类似

URI

GET graphspaces/${graphspace}/graphs/${graph}/traversers/resourceallocation

URI参数

Body参数

Response

使用示例

Method & Url

GET http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/resourceallocation?vertex="1:marko"&other="1:josh"

Request Body

可选

Response Status

200

Response Body

{
  "resource_allocation": 2.0
}

适用场景

判断两个银行账户的关系紧密程度, 是共同邻居的改进系数版, 和 AA 算法不同的是, 它不忽略超级顶点在其中的权重影响

4.7.2.24.Same Neighbors Batch

功能介绍

批量查询两个点的共同邻居

URI

POST graphspaces/${graphspace}/graphs/${graph}/traversers/sameneighborsbatch

URI参数

Body参数

Response

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/sameneighborsbatch

Request Body

{
    "vertex_list": [["0000000001","0000376440"],["0000000001","0001822679"]],
    "direction": "OUT"
}

Response Status

200

Response Body

{
    "same_neighbors": [
        [
            "0001222009"
        ],
        [
            "0001397143"
        ]
    ]
}

适用场景

查找一批顶点对的共同邻居：

• 社交关系中发现两个用户的共同粉丝或者共同关注用户

4.7.2.25.Egonet

功能介绍

查找一批顶点的 K 层邻居, 并支持针对不同点 / 边 Label 的过滤条件, 结果中会包含起始顶点 (原单点 Kneighbor-API 不包含)

URI

POST graphspaces/${graphspace}/graphs/${graph}/traversers/egonet

URI参数

Body参数

表1 Steps 对象

表2 点边Step

以下是当前可支持的过滤条件及其写法:

1. P.eq() 代表过滤出数值相等的元素
2. P.neq() 代表过滤出数值不相等的元素
3. P.lt() 代表过滤出数值小于 (<) 某数的元素
4. P.lte() 代表过滤出数值小于相等 (≤) 某数的元素
5. P.gt() 代表过滤出数值大于 (>) 某数的元素
6. P.gte() 代表过滤出数值大于相等 (≥) 的元素
7. P.between(a, b) 代表过滤出数值在(a, b)范围内的元素
8. P.textcontains(str) 代表过滤出包含 str 子串的元素
9. P.contains(str) 代表从集合中过滤出包含 str 字符串的元素
10. P.within(a, b, c) 代表过滤出包含给定集合中任一子元素的元素

Response

表1 vertex对象

表2 path对象

使用示例

Method & Url

POST http://localhost:8080/graphspaces/${graphspace}/graphs/${graph}/traversers/egonet

Request Body

{
    "sources": ["1:marko", "1:vadas"],
    "steps": {
        "direction": "BOTH",
        "edge_steps": [
            {
                "label": "knows"
            },
            {
                "label": "created",
                "properties": {}
            }
        ],
        "vertex_steps": [
            {
                "label": "person",
                "properties": {
                    "age": "P.lt(35)"
                }
            },
            {
                "label": "software",
                "properties": {}
            }
        ],
        "max_degree": 100,
        "skip_degree": 1000
    },
    "max_depth": 3,
    "limit": 1000,
    "with_vertex": true
}

Response Status

200

Response Body

{
    "egonet": [
        "1:marko",
        "1:vadas",
        "2:lop"
    ],
    "size": 3,
    "paths": [
    ],
    "vertices": [
        {
            "id": "1:vadas",
            "label": "person",
            "type": "vertex",
            "properties": {
                "name": "vadas",
                "age": 27,
                "city": "Hongkong"
            }
        },
        {
            "id": "2:lop",
            "label": "software",
            "type": "vertex",
            "properties": {
                "lang": "java",
                "price": 328,
                "name": "lop"
            }
        }
    ],
    "edges": [
    ]
}

4.7.2.26.标签统计

功能介绍

Label count 算法暂存于此, 后续有更合适的位置再进行迁移, 它仅有一句 gremlin 查询即可实现点 / 边的所有 label 的数目统计, 不过要注意的是耗时可能较高, 需要异步任务提交, 建议使用 hubble 直接发送异步任务, 效果如下图: (注意数据量必须提交异步任务)

Gremlin 语句: g.V().groupCount().by(label); (如果统计边, 就把 g.V() 换成 g.E(), 其他不用变) 也可以直接发送 HTTP 请求, 使用异步执行 Gremlin 的接口, 可以参考异步 Gremlin 任务的文档