PGX 20.2.2
Documentation

Modifying Loaded Graphs

This guide shows how to add and remove vertices and edges from already loaded graphs. This can be useful for "what-if" analyses.

Recap: Loading a Graph

At first we need to load a graph. For detailed instructions, refer to the Graph Loading Guide.

var graph = session.readGraphWithProperties("examples/graphs/sample.csv.json")
import oracle.pgx.api.*;

PgxSession session = Pgx.createSession("my-session");
PgxGraph graph = session.readGraphWithProperties("examples/graphs/sample.csv.json");
session = pypgx.get_session("my-session")
graph = session.read_graph_with_properties("examples/graphs/sample.csv.json")

This will load the following sample graph:

sample_graph

Adding, Removing and Modifying Vertices

Now that we have a graph loaded we can start modifying it. First we need a GraphChangeSet - an object similar to the GraphBuilder. It provides methods for modifying all aspects of a graph.

We are going to add a new vertex 42 with the property value 23 for prop1. Additionally we are going to set the value of prop1 for vertex 128 to 5. Finally we will remove the vertex with ID 1908.

var changeSet = graph.<Integer>createChangeSet()

changeSet.addVertex(42).setProperty("prop", 23)
changeSet.updateVertex(128).setProperty("prop", 5)
changeSet.removeVertex(1908)

var updatedGraph = changeSet.build()

updatedGraph.hasVertex(42) // Evaluates to: true
updatedGraph.hasVertex(1908) // Evaluates to: false
import oracle.pgx.api.*;

GraphChangeSet<Integer> changeSet = graph.createChangeSet();

changeSet.addVertex(42).setProperty("prop", 23);
changeSet.updateVertex(128).setProperty("prop", 5);
changeSet.removeVertex(1908);

PgxGraph updatedGraph = changeSet.build();

assert updatedGraph.hasVertex(42) == true;
assert updatedGraph.hasVertex(1908) == false;
from pypgx.api import *

change_set = graph.create_change_set()

change_set.add_vertex(42).set_property("prop", 23)
changeSet.update_vertex(128).set_property("prop", 5)
changeSet.remove_vertex(1908)

updated_graph = change_set.build()

assert updatedGraph.hasVertex(42) == True
assert updatedGraph.hasVertex(1908) == False

Notice that vertex 1908 has one edge attached in the original graph. This edge will be deleted automatically with the deletion of the vertex.

The resulting graph will have the following form:

updated sample graph

Adding Edges

The same way edges can be added to the graph. For example we can add a new triangle to the graph:

var changeSet2 = updatedGraph.<Integer>createChangeSet()

changeSet2.addEdge(333, 42).setProperty("cost", 42.3)
changeSet2.addEdge(42, 99)

var updatedGraph2 = changeSet2.build()

analyst.countTriangles(updatedGraph, true) // Evaluates to: 1
analyst.countTriangles(updatedGraph2, true) // Evaluates to: 2
import oracle.pgx.api.*;

GraphChangeSet<Integer> changeSet2 = graph.createChangeSet();

changeSet2.addEdge(333, 42).setProperty("cost", 42.42);
changeSet2.addEdge(42, 99);

PgxGraph updatedGraph2 = changeSet2.build();

assert analyst.countTriangles(updatedGraph, true) == 1;
assert analyst.countTriangles(updatedGraph2, true) == 2;
change_set_2 = graph.create_change_set()
changeSet2.add_edge(333, 42).set_property("cost", 42.42)
changeSet2.add_edge(42, 99)
updated_graph_2 = change_set_2.build()

Note that we do not provide a value for the property cost for the second edge we add. In this case the property will be assigned a default value of 0.0.

This is the resulting graph:

second updated sample graph

Note that by calling changeSet2.build() we created a brand new graph with a unique name assigned by PGX; if need be, we can specify a name argument to the build() method. Additionally, we can create a new snapshot on top of the current graph with the buildNewSnapshot() method; for more information about this capability, you can refer to Graph Versioning. Please see the Graph Change Set API reference for detailed information on the graph ChangeSet.

Error Handling

Error handling while populating a ChangeSet or while applying a ChangeSet to the existing graph can be configured by setting the InvalidChangePolicy. The options are:

  • OnInvalidChange.ERROR: throws an exception (default configuration)
  • OnInvalidChange.IGNORE: ignores the issue and continues
  • OnInvalidChange.IGNORE_AND_LOG: ignores the issue, logs in DEBUG log level and continues
  • OnInvalidChange.IGNORE_AND_LOG_ONCE: only logs the first occurrence of each issue type

Issues that can be ignored with InvalidChangePolicy include trying to remove a vertex or an edge that does not exist in the graph, property type mismatch, updates to non existing properties, providing a vertex ID with wrong type or invalid vertex/edge providers.

In the following example, we try to remove vertex 9032 which does not exist in the graph. By configuring IGNORE_AND_LOG, this action will be ignored while the property value update for vertex 99 will still be applied successfully.

var changeSet3 = updatedGraph2.<Integer>createChangeSet()
changeSet3.setInvalidChangePolicy(OnInvalidChange.IGNORE_AND_LOG)

changeSet3.removeVertex(9032)
changeSet3.updateVertex(99).setProperty("prop1", 17)
var updatedGraph3 = changeSet3.build() // will log that a vertex removal was ignored

var prop1Val = updatedGraph3.getVertex(99).getProperty("prop1") // evaluates to 17
import oracle.pgx.api.*;

GraphChangeSet<Integer> changeSet3 = graph.createChangeSet();

changeSet3.removeVertex(9032);
changeSet3.updateVertex(99).setProperty("prop1", 17);
PgxGraph updatedGraph3 = changeSet3.build(); // will log that a vertex removal was ignored

int prop1Val = updatedGraph3.getVertex(99).getProperty("prop1"); // evaluates to 17

Note

When connecting to a remote PGX server, error handling log messages will not be relayed to the client. Access to the server logs is required to determine which issues have been ignored.

Add Existing Edges and Vertices

The error handling for adding a vertex or an edge where its ID is already used in the graph or in an incompatible ChangeSet action can be configured with AddExistingVertexPolicy and AddExistingEdgePolicy.

Note

The default setting for AddExistingVertexPolicy and AddExistingEdgePolicy is IGNORE. This is different from InvalidChangePolicy where the default is ERROR.

Refer to the javadocs for more information on how the set the policies.