0
# Graph Creation and Transformation
1

2
Core functionality for creating graphs from various data sources and transforming graph structure and data. Gelly provides flexible graph construction methods and comprehensive transformation operations for both structure and data modification.
3

4
## Capabilities
5

6
### Graph Construction from Collections
7

8
Create graphs from in-memory Java collections of vertices and edges.
9

10
```java { .api }
11
public static <K, VV, EV> Graph<K, VV, EV> fromCollection(
12
    Collection<Vertex<K, VV>> vertices,
13
    Collection<Edge<K, EV>> edges,
14
    ExecutionEnvironment context)
15

16
public static <K, EV> Graph<K, NullValue, EV> fromCollection(
17
    Collection<Edge<K, EV>> edges,
18
    ExecutionEnvironment context)
19

20
public static <K, VV, EV> Graph<K, VV, EV> fromCollection(
21
    Collection<Edge<K, EV>> edges,
22
    MapFunction<K, VV> vertexValueInitializer,
23
    ExecutionEnvironment context)
24
```
25

26
**Usage Example:**
27

28
```java
29
ExecutionEnvironment env = ExecutionEnvironment.getExecutionEnvironment();
30

31
// Create vertices
32
List<Vertex<Long, String>> vertices = Arrays.asList(
33
    new Vertex<>(1L, "Alice"),
34
    new Vertex<>(2L, "Bob"),
35
    new Vertex<>(3L, "Charlie")
36
);
37

38
// Create edges
39
List<Edge<Long, Double>> edges = Arrays.asList(
40
    new Edge<>(1L, 2L, 0.8),
41
    new Edge<>(2L, 3L, 0.6),
42
    new Edge<>(3L, 1L, 0.9)
43
);
44

45
// Create graph from collections
46
Graph<Long, String, Double> graph = Graph.fromCollection(vertices, edges, env);
47

48
// Create graph from edges only (vertices auto-generated with NullValue)
49
Graph<Long, NullValue, Double> simpleGraph = Graph.fromCollection(edges, env);
50

51
// Create graph with vertex initializer
52
Graph<Long, Long, Double> idGraph = Graph.fromCollection(
53
    edges,
54
    id -> id * 100L, // Initialize vertex value as ID * 100
55
    env
56
);
57
```
58

59
### Graph Construction from DataSets
60

61
Create graphs from Flink DataSets for distributed graph processing.
62

63
```java { .api }
64
public static <K, VV, EV> Graph<K, VV, EV> fromDataSet(
65
    DataSet<Vertex<K, VV>> vertices,
66
    DataSet<Edge<K, EV>> edges,
67
    ExecutionEnvironment context)
68

69
public static <K, EV> Graph<K, NullValue, EV> fromDataSet(
70
    DataSet<Edge<K, EV>> edges,
71
    ExecutionEnvironment context)
72

73
public static <K, VV, EV> Graph<K, VV, EV> fromDataSet(
74
    DataSet<Edge<K, EV>> edges,
75
    MapFunction<K, VV> vertexValueInitializer,
76
    ExecutionEnvironment context)
77
```
78

79
### Graph Construction from Tuples
80

81
Create graphs from tuple DataSets using standard Flink tuple types.
82

83
```java { .api }
84
public static <K, VV, EV> Graph<K, VV, EV> fromTupleDataSet(
85
    DataSet<Tuple2<K, VV>> vertices,
86
    DataSet<Tuple3<K, K, EV>> edges,
87
    ExecutionEnvironment context)
88

89
public static <K, EV> Graph<K, NullValue, EV> fromTupleDataSet(
90
    DataSet<Tuple3<K, K, EV>> edges,
91
    ExecutionEnvironment context)
92

93
public static <K, VV, EV> Graph<K, VV, EV> fromTupleDataSet(
94
    DataSet<Tuple3<K, K, EV>> edges,
95
    MapFunction<K, VV> vertexValueInitializer,
96
    ExecutionEnvironment context)
97
```
98

99
**Usage Example:**
100

101
```java
102
// Create vertex tuples (ID, Value)
103
DataSet<Tuple2<Long, String>> vertexTuples = env.fromElements(
104
    new Tuple2<>(1L, "Alice"),
105
    new Tuple2<>(2L, "Bob"),
106
    new Tuple2<>(3L, "Charlie")
107
);
108

109
// Create edge tuples (Source, Target, Value)
110
DataSet<Tuple3<Long, Long, Double>> edgeTuples = env.fromElements(
111
    new Tuple3<>(1L, 2L, 0.8),
112
    new Tuple3<>(2L, 3L, 0.6),
113
    new Tuple3<>(3L, 1L, 0.9)
114
);
115

116
// Create graph from tuples
117
Graph<Long, String, Double> graph = Graph.fromTupleDataSet(vertexTuples, edgeTuples, env);
118
```
119

120
### CSV File Input
121

122
Create graphs from CSV files using Flink's CSV reader capabilities.
123

124
```java { .api }
125
public static GraphCsvReader fromCsvReader(String filePath, ExecutionEnvironment context)
126

127
// GraphCsvReader methods
128
public GraphCsvReader vertices(String filePath)
129
public GraphCsvReader edges(String filePath)
130
public <K, VV, EV> Graph<K, VV, EV> types(Class<K> keyClass, Class<VV> vertexValueClass, Class<EV> edgeValueClass)
131
```
132

133
### Vertex Transformation
134

135
Transform vertex values while preserving graph structure.
136

137
```java { .api }
138
public <NV> Graph<K, NV, EV> mapVertices(MapFunction<Vertex<K, VV>, NV> mapper)
139
```
140

141
**Usage Example:**
142

143
```java
144
// Transform vertex values to uppercase
145
Graph<Long, String, Double> upperGraph = graph.mapVertices(
146
    vertex -> vertex.getValue().toUpperCase()
147
);
148

149
// Convert vertex values to their length
150
Graph<Long, Integer, Double> lengthGraph = graph.mapVertices(
151
    vertex -> vertex.getValue().length()
152
);
153
```
154

155
### Edge Transformation
156

157
Transform edge values while preserving graph structure.
158

159
```java { .api }
160
public <NE> Graph<K, VV, NE> mapEdges(MapFunction<Edge<K, EV>, NE> mapper)
161
```
162

163
**Usage Example:**
164

165
```java
166
// Square all edge weights
167
Graph<Long, String, Double> squaredGraph = graph.mapEdges(
168
    edge -> edge.getValue() * edge.getValue()
169
);
170

171
// Convert edge weights to strings
172
Graph<Long, String, String> stringGraph = graph.mapEdges(
173
    edge -> "weight:" + edge.getValue()
174
);
175
```
176

177
### ID and Value Translation
178

179
Translate graph IDs and values using the ASM translation framework.
180

181
```java { .api }
182
public <NK> Graph<NK, VV, EV> translateGraphIds(TranslateFunction<K, NK> translator)
183
public <NVV> Graph<K, NVV, EV> translateVertexValues(TranslateFunction<VV, NVV> translator)
184
public <NEV> Graph<K, VV, NEV> translateEdgeValues(TranslateFunction<EV, NEV> translator)
185
```
186

187
**Usage Example:**
188

189
```java
190
// Translate Long IDs to String IDs
191
Graph<String, String, Double> stringIdGraph = graph.translateGraphIds(
192
    new LongValueToStringValue()
193
);
194

195
// Add offset to all vertex IDs
196
Graph<Long, String, Double> offsetGraph = graph.translateGraphIds(
197
    new LongValueAddOffset(1000L)
198
);
199
```
200

201
### Graph Filtering
202

203
Filter vertices and edges based on predicates.
204

205
```java { .api }
206
public Graph<K, VV, EV> filterOnVertices(FilterFunction<Vertex<K, VV>> vertexFilter)
207
public Graph<K, VV, EV> filterOnEdges(FilterFunction<Edge<K, EV>> edgeFilter)
208
public Graph<K, VV, EV> subgraph(
209
    FilterFunction<Vertex<K, VV>> vertexFilter,
210
    FilterFunction<Edge<K, EV>> edgeFilter)
211
```
212

213
**Usage Example:**
214

215
```java
216
// Filter vertices by value
217
Graph<Long, String, Double> filteredVertices = graph.filterOnVertices(
218
    vertex -> vertex.getValue().length() > 3
219
);
220

221
// Filter edges by weight
222
Graph<Long, String, Double> filteredEdges = graph.filterOnEdges(
223
    edge -> edge.getValue() > 0.7
224
);
225

226
// Create subgraph with both filters
227
Graph<Long, String, Double> subgraph = graph.subgraph(
228
    vertex -> vertex.getValue().startsWith("A"),
229
    edge -> edge.getValue() > 0.5
230
);
231
```
232

233
### Graph Set Operations
234

235
Perform set operations between graphs.
236

237
```java { .api }
238
public Graph<K, VV, EV> union(Graph<K, VV, EV> other)
239
public Graph<K, VV, EV> difference(Graph<K, VV, EV> other)
240
public Graph<K, VV, EV> intersect(Graph<K, VV, EV> other)
241
```
242

243
**Usage Example:**
244

245
```java
246
Graph<Long, String, Double> graph1 = /* ... */;
247
Graph<Long, String, Double> graph2 = /* ... */;
248

249
// Union of two graphs
250
Graph<Long, String, Double> unionGraph = graph1.union(graph2);
251

252
// Difference (edges in graph1 but not in graph2)
253
Graph<Long, String, Double> diffGraph = graph1.difference(graph2);
254

255
// Intersection (common edges)
256
Graph<Long, String, Double> intersectGraph = graph1.intersect(graph2);
257
```
258

259
### Graph Structure Modification
260

261
Modify graph structure and directionality.
262

263
```java { .api }
264
public Graph<K, VV, EV> reverse()
265
public Graph<K, VV, EV> getUndirected()
266
```
267

268
**Usage Example:**
269

270
```java
271
// Reverse all edge directions
272
Graph<Long, String, Double> reversedGraph = graph.reverse();
273

274
// Convert to undirected graph (adds reverse edges)
275
Graph<Long, String, Double> undirectedGraph = graph.getUndirected();
276
```
277

278
## Core Data Types
279

280
### Vertex<K, V>
281

282
Represents a graph vertex with ID and value.
283

284
```java { .api }
285
public class Vertex<K, V> extends Tuple2<K, V> {
286
    public Vertex() {}
287
    public Vertex(K id, V value) {}
288
    
289
    public K getId() { return f0; }
290
    public V getValue() { return f1; }
291
    public void setId(K id) { f0 = id; }
292
    public void setValue(V value) { f1 = value; }
293
}
294
```
295

296
### Edge<K, V>
297

298
Represents a graph edge with source, target, and value.
299

300
```java { .api }
301
public class Edge<K, V> extends Tuple3<K, K, V> {
302
    public Edge() {}
303
    public Edge(K source, K target, V value) {}
304
    
305
    public K getSource() { return f0; }
306
    public K getTarget() { return f1; }
307
    public V getValue() { return f2; }
308
    public void setSource(K source) { f0 = source; }
309
    public void setTarget(K target) { f1 = target; }
310
    public void setValue(V value) { f2 = value; }
311
    public Edge<K, V> reverse() { return new Edge<>(f1, f0, f2); }
312
}
313
```
314

315
### Triplet<K, VV, EV>
316

317
Represents an edge with its source and target vertex values.
318

319
```java { .api }
320
public class Triplet<K, VV, EV> extends Tuple5<K, K, VV, VV, EV> {
321
    public Vertex<K, VV> getSrcVertex() { return new Vertex<>(f0, f2); }
322
    public Vertex<K, VV> getTrgVertex() { return new Vertex<>(f1, f3); }
323
    public Edge<K, EV> getEdge() { return new Edge<>(f0, f1, f4); }
324
}
325
```