4. Managing Graphs¶

The PgxGraph class can be used to manage and execute operations on the underlying graph.

class pypgx.api.PgxGraph(session, java_graph)

A reference to a graph on the server side.

Operations on instances of this class are executed on the server side onto the referenced graph. Note that a session can have multiple objects referencing the same graph: the result of any operation mutating the graph on any of those references will be visible on all of them.

add_redaction_rule(redaction_rule_config, authorization_type, *names)

Add a redaction rule for authorization_type names.

Possible authorization types are: [‘user’, ‘role’]

Parameters

authorization_type – the authorization type of the rule to be added
names – the names of the users or roles for which the rule should be added

alter_graph()

Create a graph alteration builder to define the graph schema alterations to perform on the graph.

Returns: an empty graph alteration builder

bipartite_sub_graph_from_in_degree(vertex_properties=True, edge_properties=True, name=None, is_left_name=None, in_place=False)

Create a bipartite version of this graph with all vertices of in-degree = 0 being the left set.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
name – New graph name
is_left_name – Name of the boolean isLeft vertex property of the new graph. If None, a name will be generated.
in_place – Whether to create a new copy (False) or overwrite this graph (True)

bipartite_sub_graph_from_left_set(vset, vertex_properties=True, edge_properties=True, name=None, is_left_name=None)

Create a bipartite version of this graph with the given vertex set being the left set.

Parameters

vset – Vertex set representing the left side
vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
name – name of the new graph. If None, a name will be generated.
is_left_name – Name of the boolean isLeft vertex property of the new graph. If None, a name will be generated.

clone(vertex_properties=True, edge_properties=True, name=None)

Return a copy of this graph.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be cloned as well
edge_properties – List of edge properties belonging to graph specified to be cloned as well
name – Name of the new graph

clone_and_execute_pgql(pgql_query)

Create a deep copy of the graph, and execute on it the pgql query.

Parameters: pgql_query – Query string in PGQL
Returns: A cloned PgxGraph with the pgql query executed

throws InterruptedException if the caller thread gets interrupted while waiting for: completion.
throws ExecutionException if any exception occurred during asynchronous execution.: The actual exception will be nested.

close(): Destroy without waiting for completion.

combine_edge_properties_into_vector_property(properties, name=None)

Take a list of scalar edge properties of same type and create a new edge vector property by combining them.

The dimension of the vector property will be equals to the number of properties.

Parameters

properties – List of scalar edge properties
name – Name for the vector property. If not null, vector property will be named. If that results in a name conflict, the returned future will complete exceptionally.

combine_vertex_properties_into_vector_property(properties, name=None)

Take a list of scalar vertex properties of same type and create a new vertex vector property by combining them.

The dimension of the vector property will be equals to the number of properties.

Parameters

properties – List of scalar vertex properties
name – Name for the vector property. If not null, vector property will be named. If that results in a name conflict, the returned future will complete exceptionally.

property config: Get the GraphConfig object.

create_all_paths(src, cost, dist, parent, parent_edge)

Create an AllPaths object representing all the shortest paths from a single source to all the possible destinations (shortest regarding the given edge costs).

Parameters

src – Source vertex of the path
cost – Property holding the edge costs. If None, the resulting cost will equal the hop distance
dist – Property holding the distance to the source vertex for each vertex in the graph
parent – Property holding the parent vertices of all the shortest paths For example, if the shortest path is A -> B -> C, then parent[C] -> B and parent[B] -> A
parent_edge – Property holding the parent edges for each vertex of the shortest path

Returns

The AllPaths object

create_components(components, num_components)

Create a Partition object holding a collection of vertex sets, one for each component.

Parameters

components – Vertex property mapping each vertex to its component ID. Note that only component IDs in the range of [0..numComponents-1] are allowed. The returned future will complete exceptionally with an IllegalArgumentException if an invalid component ID is encountered. Gaps are supported: certain IDs not being associated with any vertices will yield to empty components.
num_components – How many different components the components property contains

Returns

The Partition object

create_edge_property(data_type, name=None)

Create a session-bound edge property.

Parameters

data_type – Type of the vector property to create
name – Name of vector property to be created

create_edge_sequence(name=None)

Create a new edge sequence.

Parameters: name – Sequence name

create_edge_set(name=None)

Create a new edge set.

Parameters: name – Edge set name

create_edge_vector_property(data_type, dim, name=None)

Create a session-bound vector property.

Parameters

data_type – Type of the vector property to create
dim – Dimension of vector property to be created
name – Name of vector property to be created

create_map(key_type, val_type, name=None)

Create a session-bound map.

Possible types are: [‘integer’,’long’,’double’,’boolean’,’string’,’vertex’,’edge’, ‘local_date’,’time’,’timestamp’,’time_with_timezone’,’timestamp_with_timezone’]

Parameters

key_type – Property type of the keys that are going to be stored inside the map
val_type – Property type of the values that are going to be stored inside the map
name – Map name

create_merging_strategy_builder(): Create a new MergingStrategyBuilder that can be used to build a new MutationStrategy to simplify this graph.

create_path(src, dst, cost, parent, parent_edge)

Parameters

src – Source vertex of the path
dst – Destination vertex of the path
cost – Property holding the edge costs. If null, the resulting cost will equal the hop distance.
parent – Property holding the parent vertices for each vertex of the shortest path. For example, if the shortest path is A -> B -> C, then parent[C] -> B and parent[B] -> A.
parent_edge – Property holding the parent edges for each vertex of the shortest path

Returns

The PgxPath object

create_picking_strategy_builder(): Create a new PickingStrategyBuilder that can be used to build a new PickingStrategy to simplify this graph.

create_scalar(data_type, name=None)

Create a new Scalar.

Parameters

data_type – Scalar type
name – Name of the scalar to be created

create_synchronizer(synchronizer_class, connection=None, invalid_change_policy=None)

Create a synchronizer object which can be used to keep this graph in sync with changes happening in its original data source. Only partitioned graphs with all providers loaded from Oracle Database are supported.

Possible invalid_change_policy types are: [‘ignore’, ‘ignore_and_log’,: ‘ignore_and_log_once’, ‘error’]

Parameters

class – the implementation class of the Synchronizer
connection – the connection object to the RDBMS
invalid_change_policy – sets the OnInvalidChange parameter to the Synchronizer ChangeSet

Returns

a synchronizer

create_vector_scalar(data_type, name=None)

Create a new vertex property.

Parameters

data_type – Property type
name – Name of the scalar to be created

create_vertex_property(data_type, name=None)

Create a new vertex property.

Parameters

data_type – Property type
name – Name of the property to be created

create_vertex_sequence(name=None)

Create a new vertex sequence.

Parameters: name – Sequence name

create_vertex_set(name=None)

Create a new vertex set.

Parameters: name – Set name

create_vertex_vector_property(data_type, dim, name=None)

Create a session-bound vertex vector property.

Parameters

data_type – Type of the vector property to create
dim – Dimension of vector property to be created
name – Name of vector property to be created

destroy_edge_property_if_exists(name)

Destroy a specific edge property if it exists.

Parameters: name – Property name

destroy_vertex_property_if_exists(name)

Destroy a specific vertex property if it exists.

Parameters: name – Property name

execute_pgql(pgql_query)

(BETA) Blocking version of cloneAndExecutePgqlAsync(String).

Calls cloneAndExecutePgqlAsync(String) and waits for the returned PgxFuture to complete.

throws InterruptedException if the caller thread gets interrupted while waiting for completion.

throws ExecutionException if any exception occurred during asynchronous execution. The actual exception will be nested.

Parameters: pgql_query – Query string in PGQL
Returns: The query result set as PgqlResultSet object

explain_pgql(pgql_query)

Explain the execution plan of a pattern matching query.

Note: Different PGX versions may return different execution plans.

Parameters: pgql_query – Query string in PGQL
Returns: The query plan

filter(graph_filter, vertex_properties=True, edge_properties=True, name=None)

Create a subgraph of this graph.

To create the subgraph, a given filter expression is used to determine which parts of the graph will be part of the subgraph.

Parameters

graph_filter – Object representing a filter expression that is applied to create the subgraph
vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
name – Filtered graph name

get_collections(): Retrieve all currently allocated collections associated with the graph.

get_edge(eid)

Get an edge with a specified id.

Parameters: eid – edge id

get_edge_label(): Get the edge labels belonging to this graph.

get_edge_properties()

Get the set of edge properties belonging to this graph.

This list might contain transient, private and published properties.

get_edge_property(name)

Get an edge property by name.

Parameters: name – Property name

get_edges(filter_expr=None, name=None)

Create a new edge set containing vertices according to the given filter expression.

Parameters

filter_expr – EdgeFilter object with the filter expression. If None all the vertices are returned.
name – the name of the collection to be created. If None, a name will be generated.

get_id()

Get the Graph id.

Returns: A string representation of the id of this graph.

get_meta_data()

Get the GraphMetaData object.

Returns: A ‘GraphMetaData’ object of this graph.

get_or_create_edge_property(name, data_type=None, dim=0)

Get or create an edge property.

Parameters

name – Property name
data_type – Property type
dim – Dimension of vector property to be created

get_or_create_edge_vector_property(data_type, dim, name=None)

Get or create a session-bound edge property.

Parameters

data_type – Type of the vector property to create
dim – Dimension of vector property to be created
name – Name of vector property to be created

get_or_create_vertex_property(name, data_type=None, dim=0)

Get or create a vertex property.

Parameters

name – Property name
data_type – Property type
dim – Dimension of vector property to be created

get_or_create_vertex_vector_property(data_type, dim, name=None)

Get or create a session-bound vertex vector property.

Parameters

data_type – Type of the vector property to create
dim – Dimension of vector property to be created
name – Name of vector property to be created

get_pgx_id()

Get the Graph id.

Returns: The id of this graph.

get_random_edge(): Get a edge vertex from the graph.

get_random_vertex(): Get a random vertex from the graph.

get_redaction_rules(authorization_type, name)

Get the redaction rules for an authorization_type name.

Possible authorization types are: [‘user’, ‘role’]

Parameters

authorization_type – the authorization type of the rules to be returned
name – the name of the user or role for which the rules should be returned

Returns

a list of redaction rules for the given name of type authorization_type

get_vertex(vid)

Get a vertex with a specified id.

Parameters: vid – Vertex id
Returns: pgxVertex object

get_vertex_labels(): Get the vertex labels belonging to this graph.

get_vertex_properties()

Get the set of vertex properties belonging to this graph.

This list might contain transient, private and published properties.

get_vertex_property(name)

Get a vertex property by name.

Parameters: name – Property name

get_vertices(filter_expr=None, name=None)

Create a new vertex set containing vertices according to the given filter expression.

Parameters

filter_expr – VertexFilter object with the filter expression if None all the vertices are returned
name – The name of the collection to be created. If None, a name will be generated.

grant_permission(permission_entity, pgx_resource_permission)

Grant a permission on this graph to the given entity.

Possible PGXResourcePermission types are: [‘none’, ‘read’, ‘write’, ‘export’, ‘manage’] Possible PermissionEntity objects are: PgxUser and PgxRole.

Cannont grant ‘manage’.

Parameters

permission_entity – the entity the rule is granted to
pgx_resource_permission – the permission type

has_edge(eid)

Check if the edge with id vid is in the graph.

Parameters: eid – Edge id

has_edge_label(): Return True if the graph has edge labels, False if not.

has_vertex(vid)

Check if the vertex with id vid is in the graph.

Parameters: vid – vertex id

has_vertex_labels(): Return True if the graph has vertex labels, False if not.

is_bipartite(is_left)

Check whether a given graph is a bipartite graph.

A graph is considered a bipartite graph if all nodes can be divided in a ‘left’ and a ‘right’ side where edges only go from nodes on the ‘left’ side to nodes on the ‘right’ side.

Parameters: is_left – Boolean vertex property that - if the method returns true - will contain for each node whether it is on the ‘left’ side of the bipartite graph. If the method returns False, the content is undefined.

property is_fresh: Check whether an in-memory representation of a graph is fresh.

is_pinned(): For a published graph, indicates if the graph is pinned. A pinned graph will stay published even if no session is using it.

property is_published: Check if this graph is published with snapshots.

is_published_with_snapshots()

Check if this graph is published with snapshots.

Returns: True if this graph is published, false otherwise

property pgx_instance: Get the server instance.

pick_random_vertex()

Select a random vertex from the graph.

Returns: The PgxVertex object

pin(): For a published graph, pin the graph so that it stays published even if no sessions uses it. This call pins the graph lineage, which ensures that at least the latest available snapshot stays published when no session uses the graph.

prepare_pgql(pgql_query)

Prepare a PGQL query.

Parameters: pgql_query – Query string in PGQL
Returns: A prepared statement object

publish(vertex_properties=True, edge_properties=True)

Publish the graph so it can be shared between sessions.

This moves the graph name from the private into the public namespace.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be published as well
edge_properties – List of edge properties belonging to graph specified by graph to be published as well

publish_with_snapshots(): Publish the graph and all its snapshots so they can be shared between sessions.

query_pgql(query)

Submit a pattern matching select only query.

Parameters: query – Query string in PGQL
Returns: PgqlResultSet with the result

remove_redaction_rule(redaction_rule_config, authorization_type, *names)

Remove a redaction rule for authorization_type names.

Possible authorization types are: [‘user’, ‘role’]

Parameters

authorization_type – the authorization type of the rule to be removed
names – the names of the users or roles for which the rule should be removed

rename(name)

Rename this graph.

Parameters: name – New name

revoke_permission(permission_entity)

Revoke all permissions on this graph from the given entity.

Possible PermissionEntity objects are: PgxUser and PgxRole.

Parameters: permission_entity – the entity for which all permissions will be revoked

simplify(vertex_properties=True, edge_properties=True, keep_multi_edges=False, keep_self_edges=False, keep_trivial_vertices=False, in_place=False, name=None)

Create a simplified version of a graph.

Note that the returned graph and properties are transient and therefore session bound. They can be explicitly destroyed and get automatically freed once the session dies.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
keep_multi_edges – Defines if multi-edges should be kept in the result
keep_self_edges – Defines if self-edges should be kept in the result
keep_trivial_vertices – Defines if isolated nodes should be kept in the result
in_place – If the operation should be done in place of if a new graph has to be created
name – New graph name

sort_by_degree(vertex_properties=True, edge_properties=True, ascending=True, in_degree=True, in_place=False, name=None)

Create a sorted version of a graph and all its properties.

The returned graph is sorted such that the node numbering is ordered by the degree of the nodes. Note that the returned graph and properties are transient.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
ascending – Sorting order
in_degree – If in_degree should be used for sorting. Otherwise use out degree.
in_place – If the sorting should be done in place or a new graph should be created
name – New graph name

sparsify(sparsification, vertex_properties=True, edge_properties=True, name=None)

Sparsify the given graph and returns a new graph with less edges.

Parameters

sparsification – The sparsification coefficient. Must be between 0.0 and 1.0..
vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
name – Filtered graph name

store(format, path, num_partitions=None, vertex_properties=True, edge_properties=True, overwrite=False)

Store graph in a file.

Parameters

format – One of [‘pgb’, ‘edge_list’, ‘two_tables’, ‘adj_list’, ‘flat_file’, ‘graphml’, ‘pg’, ‘rdf’, ‘csv’]
path – Path to which graph will be stored
num_partitions – The number of partitions that should be created, when exporting to multiple files
vertex_properties – The collection of vertex properties to store together with the graph data. If not specified all the vertex properties are stored
edge_properties – The collection of edge properties to store together with the graph data. If not specified all the vertex properties are stored
overwrite – Overwrite if existing

transpose(vertex_properties=True, edge_properties=True, edge_label_mapping=None, in_place=False, name=None)

Create a transpose of this graph.

A transpose of a directed graph is another directed graph on the same set of vertices with all of the edges reversed. If this graph contains an edge (u,v) then the return graph will contain an edge (v,u) and vice versa. If this graph is undirected (isDirected() returns false), this operation has no effect and will either return a copy or act as identity function depending on the mode parameter.

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
edge_label_mapping – Can be used to rename edge labels. For example, an edge (John,Mary) labeled “fatherOf” can be transformed to be labeled “hasFather” on the transpose graph’s edge (Mary,John) by passing in a dict like object {“fatherOf”:”hasFather”}.
in_place – If the transpose should be done in place or a new graph should be created
name – New graph name

undirect(vertex_properties=True, edge_properties=True, keep_multi_edges=True, keep_self_edges=True, keep_trivial_vertices=True, in_place=False, name=None)

Parameters

vertex_properties – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties – List of edge properties belonging to graph specified to be kept in the new graph
keep_multi_edges – Defines if multi-edges should be kept in the result
keep_self_edges – Defines if self-edges should be kept in the result
keep_trivial_vertices – Defines if isolated nodes should be kept in the result
in_place – If the operation should be done in place of if a new graph has to be created
name – New graph name

unpin(): For a published graph, unpin the graph so that if no snapshot of the graph is used by any session or pinned, the graph and all its snapshots can be removed.