Gelly簡介

Gelly是Flink的圖API庫，它包含了一組旨在簡化Flink中圖形分析應用程序開發(fā)的方法和實用程序。在Gelly中，可以使用類似于批處理API提供的高級函數(shù)來轉換和修改圖。Gelly提供了創(chuàng)建、轉換和修改圖的方法，以及圖算法庫。

使用Gelly

在項目中為了能方便地使用Gelly，可以在pom.xml中引入以下依賴：

<dependency>
    <groupId>org.apache.flink</groupId>
    <artifactId>flink-gelly_2.11</artifactId>
    <version>1.7.0</version>
</dependency>

在運行Gelly程序之前，Gelly庫jar在opt目錄下的Flink發(fā)行版中提供(對于超過Flink 1.2的版本，可以從Maven Central手動下載)。要運行Gelly示例，必須將Flink - Gelly(用于Java)或Flink - gely - Scala(用于Scala) jar復制到Flink的lib目錄

cp opt/flink-gelly_*.jar lib/
cp opt/flink-gelly-scala_*.jar lib/

圖API

Graph Representation

在Gelly中，一個圖（Graph）由頂點的數(shù)據(jù)集（DataSet）和邊的數(shù)據(jù)集（DataSet）組成。圖中的頂點由Vertex類型來表示，一個Vertex由唯一的ID和一個值來表示。其中Vertex的ID必須是全局唯一的值，且實現(xiàn)了Comparable接口。如果節(jié)點不需要由任何值，則該值類型可以聲明成NullValue類型。

// create a new vertex with a Long ID and a String value
Vertex<Long, String> v = new Vertex<Long, String>(1L, "foo");

// create a new vertex with a Long ID and no value
Vertex<Long, NullValue> v = new Vertex<Long, NullValue>(1L, NullValue.getInstance());

圖中的邊由Edge類型來表示，一個Edge通常由源頂點的ID，目標頂點的ID以及一個可選的值來表示。其中源頂點和目標頂點的類型必須與Vertex的ID類型相同。同樣的，如果邊不需要由任何值，則該值類型可以聲明成NullValue類型。

Edge<Long, Double> e = new Edge<Long, Double>(1L, 2L, 0.5);

// reverse the source and target of this edge
Edge<Long, Double> reversed = e.reverse();

Double weight = e.getValue(); // weight = 0.5

在Gelly中，一個Edge總是從源頂點指向目標頂點。如果圖中每條邊都能匹配一個從目標頂點到源頂點的Edge，那么這個圖可能是個無向圖。同樣地，無向圖可以用這個方式來表示。

Graph Creation

我們可以通過以下幾種方式創(chuàng)建一個Graph:

• 從一個Edge數(shù)據(jù)集合和一個Vertex數(shù)據(jù)集合中創(chuàng)建圖。

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();

DataSet<Vertex<String, Long>> vertices = ...
DataSet<Edge<String, Double>> edges = ...

Graph<String, Long, Double> graph = Graph.fromDataSet(vertices, edges, env);

• 從一個表示邊的Tuple2數(shù)據(jù)集合中創(chuàng)建圖。Gelly會將每個Tuple2轉換成一個'Edge'，其中第一個元素表示源頂點的ID，第二個元素表示目標頂點的ID，圖中的頂點和邊的value值均被設置為NullValue。

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();

DataSet<Tuple2<String, String>> edges = ...

Graph<String, NullValue, NullValue> graph = Graph.fromTuple2DataSet(edges, env);

• 從一個Tuple3數(shù)據(jù)集和一個可選的Tuple2數(shù)據(jù)集中生成圖。在這種情況下，Gelly會將每個Tuple3轉換成Edge，其中第一個元素域是源頂點ID，第二個域是目標頂點ID，第三個域是邊的值。同樣的，每個Tuple2會轉換成一個頂點Vertex，其中第一個域是頂點的ID，第二個域是頂點的value。

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();

DataSet<Tuple2<String, Long>> vertexTuples = env.readCsvFile("path/to/vertex/input").types(String.class, Long.class);

DataSet<Tuple3<String, String, Double>> edgeTuples = env.readCsvFile("path/to/edge/input").types(String.class, String.class, Double.class);

Graph<String, Long, Double> graph = Graph.fromTupleDataSet(vertexTuples, edgeTuples, env);

• 從一個表示邊數(shù)據(jù)的CSV文件和一個可選的表示節(jié)點的CSV文件中生成圖。在這種情況下，Gelly會將表示邊的CSV文件中的每一行轉換成一個Edge，其中第一個域表示源頂點ID，第二個域表示目標頂點ID，第三個域表示邊的值。同樣的，表示節(jié)點的CSV中的每一行都被轉換成一個Vertex，其中第一個域表示頂點的ID，第二個域表示頂點的值。為了通過GraphCsvReader生成圖，需要指定每個域的類型，可以使用下列之一的方法：
• types(Class<K> vertexKey, Class<VV> vertexValue,Class<EV> edgeValue): both vertex and edge values are present.
• edgeTypes(Class<K> vertexKey, Class<EV> edgeValue): the Graph has edge values, but no vertex values.
• vertexTypes(Class<K> vertexKey, Class<VV> vertexValue): the Graph has vertex values, but no edge values.
• keyType(Class<K> vertexKey): the Graph has no vertex values and no edge values.

// create a Graph with String Vertex IDs, Long Vertex values and Double Edge values
Graph<String, Long, Double> graph = Graph.fromCsvReader("path/to/vertex/input", "path/to/edge/input", env)
                    .types(String.class, Long.class, Double.class);


// create a Graph with neither Vertex nor Edge values
Graph<Long, NullValue, NullValue> simpleGraph = Graph.fromCsvReader("path/to/edge/input", env).keyType(Long.class);

• 從一個邊的集合和一個可選的頂點的集合中生成圖。如果在圖創(chuàng)建的時候頂點的集合沒有傳入，Gelly會依據(jù)數(shù)據(jù)的邊數(shù)據(jù)集合自動地生成一個Vertex集合。這種情況下，創(chuàng)建的節(jié)點是沒有值的?；蛘撸覀円部梢韵裣旅嬉粯?，在創(chuàng)建圖的時候提供一個MapFunction方法來初始化節(jié)點的值。

List<Vertex<Long, Long>> vertexList = new ArrayList...

List<Edge<Long, String>> edgeList = new ArrayList...

Graph<Long, Long, String> graph = Graph.fromCollection(vertexList, edgeList, env);

// initialize the vertex value to be equal to the vertex ID
Graph<Long, Long, String> graph = Graph.fromCollection(edgeList,
                new MapFunction<Long, Long>() {
                    public Long map(Long value) {
                        return value;
                    }
                }, env);

Graph Properties

Gelly提供了下列方法來查詢圖的屬性和指標：

// get the Vertex DataSet
DataSet<Vertex<K, VV>> getVertices()

// get the Edge DataSet
DataSet<Edge<K, EV>> getEdges()

// get the IDs of the vertices as a DataSet
DataSet<K> getVertexIds()

// get the source-target pairs of the edge IDs as a DataSet
DataSet<Tuple2<K, K>> getEdgeIds()

// get a DataSet of <vertex ID, in-degree> pairs for all vertices
DataSet<Tuple2<K, LongValue>> inDegrees()

// get a DataSet of <vertex ID, out-degree> pairs for all vertices
DataSet<Tuple2<K, LongValue>> outDegrees()

// get a DataSet of <vertex ID, degree> pairs for all vertices, where degree is the sum of in- and out- degrees
DataSet<Tuple2<K, LongValue>> getDegrees()

// get the number of vertices
long numberOfVertices()

// get the number of edges
long numberOfEdges()

// get a DataSet of Triplets<srcVertex, trgVertex, edge>
DataSet<Triplet<K, VV, EV>> getTriplets()

Graph Transformations

• Map：Gelly提供了專門的用于轉換頂點值和邊值的方法。mapVertices和mapEdges會返回一個新圖，圖中的每個頂點和邊的ID不會改變，但是頂點和邊的值會根據(jù)用戶自定義的映射方法進行修改。這些映射方法同時也可以修改頂點和邊的值的類型。示例如下：

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();
Graph<Long, Long, Long> graph = Graph.fromDataSet(vertices, edges, env);

// increment each vertex value by one
Graph<Long, Long, Long> updatedGraph = graph.mapVertices(
                new MapFunction<Vertex<Long, Long>, Long>() {
                    public Long map(Vertex<Long, Long> value) {
                        return value.getValue() + 1;
                    }
                });

• Translate：Gelly還提供了專門用于根據(jù)用戶定義的函數(shù)轉換頂點和邊的ID和值的值及類型的方法（translateGraphIDs/translateVertexValues/translateEdgeValues），是Map功能的升級版，因為Map操作不支持修訂頂點和邊的ID。示例如下：

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();
Graph<Long, Long, Long> graph = Graph.fromDataSet(vertices, edges, env);

// translate each vertex and edge ID to a String
Graph<String, Long, Long> updatedGraph = graph.translateGraphIds(
                new MapFunction<Long, String>() {
                    public String map(Long id) {
                        return id.toString();
                    }
                });

// translate vertex IDs, edge IDs, vertex values, and edge values to LongValue
Graph<LongValue, LongValue, LongValue> updatedGraph = graph
                .translateGraphIds(new LongToLongValue())
                .translateVertexValues(new LongToLongValue())
                .translateEdgeValues(new LongToLongValue())

• Filter：Gelly支持在圖中的頂點上或邊上執(zhí)行一個用戶指定的filter轉換。filterOnEdges會根據(jù)提供的在邊上的斷言在原圖的基礎上生成一個新的子圖，注意，頂點的數(shù)據(jù)不會被修改。同樣的filterOnVertices在原圖的頂點上進行filter轉換，不滿足斷言條件的源節(jié)點或目標節(jié)點會在新的子圖中移除。該子圖方法支持同時對頂點和邊應用filter函數(shù)。示例如下：

Graph<Long, Long, Long> graph = ...

graph.subgraph(
        new FilterFunction<Vertex<Long, Long>>() {
                public boolean filter(Vertex<Long, Long> vertex) {
                    // keep only vertices with positive values
                    return (vertex.getValue() > 0);
               }
           },
        new FilterFunction<Edge<Long, Long>>() {
                public boolean filter(Edge<Long, Long> edge) {
                    // keep only edges with negative values
                    return (edge.getValue() < 0);
                }
        })

Filter

• Join：Gelly提供了專門的方法用于將節(jié)點和邊的數(shù)據(jù)集合與其他的輸入數(shù)據(jù)集進行連接。joinWithVertices用于連接節(jié)點和一個輸入的Tuple2數(shù)據(jù)集，連接操作通過使用節(jié)點的ID和輸入的Tuple2數(shù)據(jù)集的第一個域作為連接的Key值。該方法會根據(jù)用戶定義的轉換方法返回一個新圖。類似的，一個數(shù)據(jù)集合也可以通過邊進行連接，通過邊進行連接有三種方式：joinWithEdges的輸入是一個Tuple3數(shù)據(jù)集，并將邊的源頂點ID和目標頂點ID作為一個聯(lián)合的Key用于連接。joinWithEdgesOnSource和joinWithEdgesOnTarget均用于連接一個Tuple2數(shù)據(jù)集，其中joinWithEdgesOnSource針對Tuple2的第一個域進行連接，而joinWithEdgesOnTarget針對Tuple2的第二個域進行連接。值得注意的是，如果數(shù)據(jù)集中同一個Key出現(xiàn)多次，Gelly中所有的Join方法僅針對第一個相同Key值得數(shù)據(jù)進行連接操作。示例如下：

Graph<Long, Double, Double> network = ...

DataSet<Tuple2<Long, LongValue>> vertexOutDegrees = network.outDegrees();

// assign the transition probabilities as the edge weights
Graph<Long, Double, Double> networkWithWeights = network.joinWithEdgesOnSource(vertexOutDegrees,
                new VertexJoinFunction<Double, LongValue>() {
                    public Double vertexJoin(Double vertexValue, LongValue inputValue) {
                        return vertexValue / inputValue.getValue();
                    }
                });

• Reverse：Gelly中得reverse()方法用于在原圖的基礎上，生成一個所有邊方向與原圖相反的新圖。

• Undirected：在前面的內(nèi)容中，我們提到過，Gelly中的圖通常都是有向的，而無向圖可以通過對所有邊添加反向的邊來實現(xiàn)，出于這個目的，Gelly提供了getUndirected()方法，用于獲取原圖的無向圖。

• Union：Gelly的union()操作用于聯(lián)合當前圖和指定的輸入圖，并生成一個新圖，在輸出的新圖中，相同的節(jié)點只保留一份，但是重復的邊會保留。如下圖所示：
  

  Union

• Difference：Gelly提供了difference()方法用于發(fā)現(xiàn)當前圖與指定的輸入圖之間的差異。

• Intersect：Gelly提供了intersect()方法用于發(fā)現(xiàn)兩個圖中共同存在的邊，并將相同的邊以新圖的方式返回。相同的邊指的是具有相同的源頂點，相同的目標頂點和相同的邊值。返回的新圖中，所有的節(jié)點沒有任何值，如果需要節(jié)點值，可以使用joinWithVertices()方法去任何一個輸入圖中檢索。示例如下：

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();

// create first graph from edges {(1, 3, 12) (1, 3, 13), (1, 3, 13)}
List<Edge<Long, Long>> edges1 = ...
Graph<Long, NullValue, Long> graph1 = Graph.fromCollection(edges1, env);

// create second graph from edges {(1, 3, 13)}
List<Edge<Long, Long>> edges2 = ...
Graph<Long, NullValue, Long> graph2 = Graph.fromCollection(edges2, env);

// Using distinct = true results in {(1,3,13)}
Graph<Long, NullValue, Long> intersect1 = graph1.intersect(graph2, true);

// Using distinct = false results in {(1,3,13),(1,3,13)} as there is one edge pair
Graph<Long, NullValue, Long> intersect2 = graph1.intersect(graph2, false);

Graph Mutations

Gelly內(nèi)置下列方法以支持對一個圖進行節(jié)點和邊的增加/移除操作：

// adds a Vertex to the Graph. 
//If the Vertex already exists, it will not be added again.
Graph<K, VV, EV> addVertex(final Vertex<K, VV> vertex)

// adds a list of vertices to the Graph. 
//If the vertices already exist in the graph, they will not be added once more.
Graph<K, VV, EV> addVertices(List<Vertex<K, VV>> verticesToAdd)

// adds an Edge to the Graph. 
//If the source and target vertices do not exist in the graph, they will also be added.
Graph<K, VV, EV> addEdge(Vertex<K, VV> source, Vertex<K, VV> target, EV edgeValue)

// adds a list of edges to the Graph.
// When adding an edge for a non-existing set of vertices, 
//the edge is considered invalid and ignored.
Graph<K, VV, EV> addEdges(List<Edge<K, EV>> newEdges)

// removes the given Vertex and its edges from the Graph.
Graph<K, VV, EV> removeVertex(Vertex<K, VV> vertex)

// removes the given list of vertices and their edges from the Graph
Graph<K, VV, EV> removeVertices(List<Vertex<K, VV>> verticesToBeRemoved)

// removes *all* edges that match the given Edge from the Graph.
Graph<K, VV, EV> removeEdge(Edge<K, EV> edge)

// removes *all* edges that match the edges in the given list
Graph<K, VV, EV> removeEdges(List<Edge<K, EV>> edgesToBeRemoved)

Neighborhood Methods

鄰接方法允許每個頂點針對其所有的鄰接頂點或邊執(zhí)行某個集合操作。reduceOnEdges()可以用于計算頂點所有鄰接邊的值的集合。reduceOnNeighbors()可以用于計算鄰接頂點的值的集合。這些方法采用聯(lián)合和交換集合，并在內(nèi)部利用組合器，顯著提高了性能。鄰接的范圍由EdgeDirection來確定，它有三個枚舉值，分別是：IN / OUT / ALL，其中IN只考慮所有入的鄰接邊和頂點，OUT只考慮所有出的鄰接邊和頂點，而ALL考慮所有的鄰接邊和頂點。舉個例子，如下圖所示，假設我們想要知道圖中出度最小的邊權重。

Neighborhood Methods

Graph<Long, Long, Double> graph = ...

DataSet<Tuple2<Long, Double>> minWeights = graph.reduceOnEdges(new SelectMinWeight(), 
EdgeDirection.OUT);

// user-defined function to select the minimum weight
static final class SelectMinWeight implements ReduceEdgesFunction<Double> {

        @Override
        public Double reduceEdges(Double firstEdgeValue, Double secondEdgeValue) {
            return Math.min(firstEdgeValue, secondEdgeValue);
        }
}

結果入下圖所示：

result

同樣的，假設我們需要知道每個頂點的所有鄰接邊上的權重的值之和，不考慮方向。可以用下面的代碼來實現(xiàn)：

Graph<Long, Long, Double> graph = ...

DataSet<Tuple2<Long, Long>> verticesWithSum = graph.reduceOnNeighbors(new SumValues(), 
EdgeDirection.IN);

// user-defined function to sum the neighbor values
static final class SumValues implements ReduceNeighborsFunction<Long> {

            @Override
            public Long reduceNeighbors(Long firstNeighbor, Long secondNeighbor) {
                return firstNeighbor + secondNeighbor;
        }
}

結果如下圖所示

result

Graph Validation

Gelly提供了一個簡單的工具用于對輸入的圖進行校驗操作。由于應用程序上下文的不同，根據(jù)某些標準，有些圖可能有效，也可能無效。例如用戶需要校驗圖中是否包含重復的邊。為了校驗一個圖，可以定義一個定制的GraphValidator并實現(xiàn)它的validate()方法。InvalidVertexIdsValidator是Gelly預定義的一個校驗器，用來校驗邊上所有的頂點ID是否有效，即邊上的頂點ID在頂點集合中存在。示例如下：

ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();

// create a list of vertices with IDs = {1, 2, 3, 4, 5}
List<Vertex<Long, Long>> vertices = ...

// create a list of edges with IDs = {(1, 2) (1, 3), (2, 4), (5, 6)}
List<Edge<Long, Long>> edges = ...

Graph<Long, Long, Long> graph = Graph.fromCollection(vertices, edges, env);

// will return false: 6 is an invalid ID
graph.validate(new InvalidVertexIdsValidator<Long, Long, Long>());