Managing Transient Properties and Collections

PGX allows each client to maintain its own isolated workspace, called session. Clients may create additional data objects in their own session, which they can then use for analysis.

Transient Properties

PGX adopts the Property Graph data model. Once a graph is loaded into PGX, the graph instance itself and its original properties are set as immutable. However, the client can create and attach additional properties to the graph dynamically. These extra properties are referred to as transient properties and are mutable by the client. See this document for details.

The methods for creating transient properties are available in PgxGraph:

PgxFuture<VertexProperty<ID, V>> createVertexPropertyAsync(PropertyType type)
PgxFuture<VertexProperty<ID, V>> createVertexPropertyAsync(PropertyType type, String name)
PgxFuture<EdgeProperty<V>> createEdgePropertyAsync(PropertyType type)
PgxFuture<EdgeProperty<V>> createEdgePropertyAsync(PropertyType type, String name)

Blocking variants:

VertexProperty<ID, V> createVertexProperty(PropertyType type)
VertexProperty<ID, V> createVertexProperty(PropertyType type, String name)
EdgeProperty<V> createEdgeProperty(PropertyType type)
EdgeProperty<V> createEdgeProperty(PropertyType type, String name)

The PropertyType argument is an enum for the data type of the property, which must be one of the primitive types supported by PGX. See this document for details.

name is an optional argument to assign a unique name to the newly created property. If no name is specified, PGX will assign one to the client. Note that names must be unique. There cannot be two different vertex/edge properties for the same graph and with the same name.

All methods return a Property object, which represent the newly created transient property. Both of the underlying classes, VertexProperty<ID, V> and EdgeProperty<V>, are parametrized with the value type V the property holds. V matches the given PropertyType. VertexProperty<ID, V> is additionally parametrized with the vertex ID type. This is due to PGX support of several types of vertex identifiers. See our graph configuration chapter on how to specify the vertex ID type of a graph. EdgeProperty<V> is not parameterized with the edge ID type, because PGX only supports edge identifiers of type long.

Example:

GraphConfig config = GraphConfigBuilder.forFileFormats(...)
    ...
    .setVertexIdType(IdType.LONG)
    ...
    .build();

PgxGraph G = session.readGraphWithProperties(config);
VertexProperty<Long, String> p1 = G.createVertexProperty(PropertyType.STRING);
EdgeProperty<Double> p2 = G.createEdgeProperty(PropertyType.DOUBLE);

To delete a transient property from the session, call destroyAsync() (or destroy()) on the property object.

Collections and Scalars

The client can create graph-bound vertex and edge collections to use during the analysis with the following methods in PgxGraph:

PgxFuture<VertexSequence<E>> createVertexSequenceAsync()
PgxFuture<VertexSequence<E>> createVertexSequenceAsync(String name)
PgxFuture<VertexSet<E>> createVertexSetAsync()
PgxFuture<VertexSet<E>> createVertexSetAsync(String name)
PgxFuture<EdgeSequence> createEdgeSequenceAsync()
PgxFuture<EdgeSequence> createEdgeSequenceAsync(String name)
PgxFuture<EdgeSet> createEdgeSetAsync()
PgxFuture<EdgeSet> createEdgeSetAsync(String name)

Blocking variants:

VertexSequence<E> createVertexSequence()
VertexSequence<E> createVertexSequence(String name)
VertexSet<E> createVertexSet()
VertexSet<E> createVertexSet(String name)
EdgeSequence createEdgeSequence()
EdgeSequence createEdgeSequence(String name)
EdgeSet createEdgeSet()
EdgeSet createEdgeSet(String name)

PGX also supports scalar collections such as set and sequence. Each of these collections can hold elements of various primitive data types like INTEGER, LONG, FLOAT, DOUBLE or BOOLEAN. Scalar collections are session-bound and can be created with the following methods in PgxSession:

PgxFuture<ScalarSet<T>> createSetAsync(PropertyType contentType, String name)
PgxFuture<ScalarSequence<T>> createSequenceAsync(PropertyType contentType, String name)
PgxFuture<ScalarSet<T>> createSetAsync(PropertyType contentType)
PgxFuture<ScalarSequence<T>> createSequenceAsync(PropertyType contentType)

Blocking variants:

ScalarSet<T> createSet(PropertyType contentType, String name)
ScalarSequence<T> createSequence(PropertyType contentType, String name)
ScalarSet<T> createSet(PropertyType contentType)
ScalarSequence<T> createSequence(PropertyType contentType)

The optional argument (name) specifies the name of the newly created collection. If omitted, PGX chooses a name for the client. As with properties, the collections holding vertices are parametrized with the ID type of the vertices. Refer to graph configuration chapter to learn how to specify the vertex ID type of a graph.

The return value is the collection object which points to the newly created empty collection.

To drop a collection from the session, call destroyAsync() (or destroy()) on the collection object.

To check which collections are currently allocated for a graph you can use the following method:

PgxFuture<Map<String, PgxCollection<? extends PgxEntity<?>, ?>>> getCollectionsAsync()

Blocking variant:

Map<String, PgxCollection<? extends PgxEntity<?>, ?>> getCollections()

The returned map contains the names of the collections as keys and the collections as values. The collections can be casted to the matching collection subclass.

PGX supports special Map collection types and allows users to map between different data types (see oracle.pgx.common.types.PropertyType). Maps can be created using PgxGraph or PgxSession APIs, the difference is that the latter supports only non graph-related types, and that the created maps directly depend on the session:

PgxFuture<PgxMap<K, V>> createMapAsync(PropertyType keyType, PropertyType valType)
PgxFuture<PgxMap<K, V>> createMapAsync(PropertyType keyType, PropertyType valType, String mapName)

Blocking variants:

PgxMap<K, V> createMap(PropertyType keyType, PropertyType valType)
PgxMap<K, V> createMap(PropertyType keyType, PropertyType valType, String mapName)

Refer to this document for details.

Similarly, scalar variables can be created in the client session using the following methods:

PgxFuture<Scalar<T>> createScalarAsync(PropertyType type, String newScalarName)
PgxFuture<Scalar<T>> createScalarAsync(PropertyType type)

Blocking variants:

Scalar<T> createScalar(PropertyType type, String newScalarName)
Scalar<T> createScalar(PropertyType type)

These collections and scalar variables can then be passed as arguments to graph algorithms. Refer to the related document for more information.