Altering Partitioned Graphs

This section explains the graph alteration mutation used to add or remove vertex and edge providers of partitioned graphs.

What Altering Partitioned Graph Can Do

The graph-alteration mutation makes it possible to add or remove vertex and edge providers in a partitioned graph that has been loaded or created previously. The mutation can either create a new independent graph, or create a new snapshot for the graph.

Starting a Graph Alteration

To start a graph alteration on a partitioned graph obtained previously and stored in the variable graph, it is necessary to create a graph-alteration builder as follows:

var alterationBuilder = graph.alterGraph();

import oracle.pgx.api.*;
import oracle.pgx.api.graphalteration.GraphAlterationBuilder;

GraphAlterationBuilder alterationBuilder = graph.alterGraph();

Removing Vertex or Edge Providers

Calling alterationBuilder.removeEdgeProvider(String edgeProviderName) where edgeProviderName is the name of the edge provider to remove will make the graph resulting from the application of the alteration to not contain that specific edge provider.

Similarly, calling alterationBuilder.removeVertexProvider(String vertexProviderName) will result in the created graph to not contain that specific vertex provider. If that vertex provider was the source or destination provider for some edge providers in the base graph, those edge providers should also be removed before the application of the alteration or an exception will be thrown. It is possible to indicate that the edge providers associated to a removed vertex provider should be automatically removed by calling alterationBuilder.cascadeEdgeProviderRemovals(boolean cascadeEdgeProviderRemovals) with cascadeEdgeProviderRemovals set to true.

Loading Additional Vertex or Edge Providers from a Datasource

It is possible within a graph alteration to add vertex or edge providers by loading them from a specific datasource.

Keys in Additionally Loaded Providers

The vertex (respectively edge providers) that are loaded should provide keys in accordance with the vertex ID strategy (respectively edge ID strategy) of the graph being altered: if the ID strategy is KEYS_AS_IDS, the provider should create a key mapping; on the contrary, if the ID strategy is UNSTABLE_GENERATED_IDS, it should not create the key mapping.

Please refer to the partitioned graph ID strategy documentation in the partitioned graph overview for more information about ID strategies.

Loading Additional Vertex Providers

To add a vertex provider, it is necessary to call alterationBuilder.addVertexProvider(EntityProviderConfig vertexProviderConfig) where vertexProviderConfig is a vertex provider configuration indicating the location of the datasource to load from, the format it is stored in, the properties of the vertex provider and so on. It is also possible to add the provider by calling alterationBuilder.addVertexProvider(String pathToVertexProviderConfig) where pathToVertexProviderConfig points to a file accessible from the client that contains a JSON representation of a vertex provider configuration. For example, a vertex provider configuration can be stored in a JSON file and look as follow:

{
    "name": "typicalVertexProvider",
    "format": "csv",
    "uris": ["typical.csv"],
    "props": [{
      "name": "prop1",
      "type": "string",
      "column": 2
    }, {
      "name": "prop2",
      "type": "local_date",
      "column": 3
    }],
    "key_column": 1
}

If this JSON file is stored at /path/to/typicalVertexProvider.json (on the client side), then this vertex provider can be added in the alteration in the following manners:

// loading by indicating the path to the JSON file
alterationBuilder.addVertexProvider("/path/to/typicalVertexProvider.json");

// or by first loading the content of a JSON file into an EntityProviderConfig object
EntityProviderConfig vertexProviderConfig = new AnyFormatEntityProviderConfigFactory().fromPath("/path/to/typicalVertexProvider.json");
alterationBuilder.addVertexProvider(vertexProviderConfig);

Alternatively, the vertex provider configuration can be built programmatically:

FileEntityProviderConfigBuilder vertexProviderConfigBuilder = new FileEntityProviderConfigBuilder().
  setFormat(ProviderFormat.CSV).
  setName("typicalVertexProvider").
  setUris("typical.csv").
  setKeyColumn(1).
  addProperty("prop1", PropertyType.STRING, null, 2).
  addProperty("prop2", PropertyType.LOCAL_DATE, null, 3);

EntityProviderConfig vertexProviderConfig = vertexProviderConfigBuilder.build();

alterationBuilder.addVertexProvider(vertexProviderConfig);

For more information about provider configurations, and partitioned graph configurations in general, please refer to the documentation for the partitioned graph configuration APIs, partitioned graph configuration examples.

Loading Additional Edge Providers

To add an edge provider, it is necessary to call alterationBuilder.addEdgeProvider(EntityProviderConfig edgeProviderConfig) where edgeProviderConfig is an edge provider configuration indicating the location of the datasource to load from, the format it is stored in, the properties of the edge provider and so on. The source and destination vertex providers to which it is linked should either be already in the base graph (and not removed in the alteration), or added with the alteration. It is also possible to add the provider by calling alterationBuilder.addVertexProvider(String pathToVertexProviderConfig) where pathToVertexProviderConfig points to a file accessible from the client that contains a JSON representation of a vertex provider configuration. For example, an edge provider configuration can be stored in a JSON file and look as follow:

{
    "name": "typicalEdgeProvider",
    "format": "csv",
    "header": true,
    "uris": ["../typical.csv"],
    "source_vertex_provider": "typicalVertexProvider",
    "destination_vertex_provider": "anotherTypicalVertexProvider",
    "key_column": "EID",
    "source_column": "source",
    "destination_column": "destination",
    "props": [{
      "name": "cost",
      "type": "double"
    }],
    "loading": {
      "create_key_mapping": true
    },
    "error_handling": {
      "on_missing_vertex": "ignore_edge"
    }
}

If this JSON file is stored at /path/to/typicalEdgeProvider.json (on the client side), then this edge provider can be added in the alteration in the following manners:

// loading by indicating the path to the JSON file
alterationBuilder.addEdgeProvider("/path/to/typicalEdgeProvider.json");

// or by first loading the content of a JSON file into an EntityProviderConfig object
EntityProviderConfig edgeProviderConfig = new AnyFormatEntityProviderConfigFactory().fromPath("/path/to/typicalEdgeProvider.json");
alterationBuilder.addEdgeProvider(edgeProviderConfig);

Alternatively, the edge provider configuration can be built programmatically:

FileEntityProviderConfigBuilder edgeProviderConfigBuilder = new FileEntityProviderConfigBuilder().
  setFormat(ProviderFormat.CSV).
  setName("typicalEdgeProvider").
  hasHeader(true).
  setUris("../typical.csv").
  setSourceVertexProvider("typicalVertexProvider").
  setDestinationVertexProvider("anotherTypicalVertexProvider").
  setSourceColumn("source").
  setDestinationColumn("destination").
  setKeyColumn("EID").
  createKeyMapping(true).
  setErrorHandlingOnMissingVertex(OnMissingVertex.IGNORE_EDGE).
  addProperty("cost", PropertyType.DOUBLE);

EntityProviderConfig edgeProviderConfig = edgeProviderConfigBuilder.build();

alterationBuilder.addEdgeProvider(edgeProviderConfig);

For more information about provider configurations, and partitioned graph configurations in general, please refer to the documentation for the partitioned graph configuration APIs, partitioned graph configuration examples.

Applying the Alteration and Building a Graph or Snapshot

Once the different vertex and edge providers have been added or removed in the alteration, the only things remaining to do is to actually apply the operation. By calling alterationBuilder.build(), a new graph is created and that graph contains all the providers of the base graph minus the removed providers, and the additionally loaded providers.

By calling alterationBuilder.buildNewSnapshot(), a new snapshot for the base graph is created and that snapshot contains all the providers of the base graph minus the removed providers, and the additionally loaded providers (for more information about graph snapshots, you can refer to Graph Versioning).