This section explains the graph alteration mutation used to add or remove vertex and edge providers of partitioned graphs.
Applicable only to partitioned graphs
This mutation can only be applied to partitioned graphs, and an exception will be thrown if it is applied to a non-partitioned graph
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.
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();
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
.
It is possible within a graph alteration to add vertex or edge providers by loading them from a specific datasource.
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.
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.
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.
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).