4. Managing Graphs ¶

clone_and_execute_pgql(pgql_query)

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

Parameters: pgql_query (str) – Query string in PGQL
Returns: A cloned PgxGraph with the pgql query executed
Return type: pypgx.api._pgx_graph.PgxGraph

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.

Return type: None

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[Union[pypgx.api._property.EdgeProperty, str]]) – List of scalar edge properties
name (Optional[str]) – 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.

Return type

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[Union[pypgx.api._property.VertexProperty, str]]) – List of scalar vertex properties
name (Optional[str]) – 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.

Return type

pypgx.api._all_paths.AllPaths

property config: pypgx.api._graph_config.GraphConfig: 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 (Union[str, pypgx.api._pgx_entity.PgxVertex]) – Source vertex of the path
cost (Optional[Union[str, pypgx.api._property.EdgeProperty]]) – Property holding the edge costs. If None, the resulting cost will equal the hop distance
dist (Union[pypgx.api._property.VertexProperty, str]) – Property holding the distance to the source vertex for each vertex in the graph
parent (Union[pypgx.api._property.VertexProperty, str]) – 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 (Union[pypgx.api._property.VertexProperty, str]) – Property holding the parent edges for each vertex of the shortest path

Returns

The AllPaths object

Return type

create_change_set(vertex_id_generation_strategy='user_ids', edge_id_generation_strategy='auto_generated')

Create a change set for updating the graph.

Uses auto generated IDs for the edges.

Note

This is currently not supported for undirected graphs.

Returns

an empty change set

Return type

GraphChangeSet

Parameters

vertex_id_generation_strategy (str) –
edge_id_generation_strategy (str) –

create_components(components, num_components)

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

Parameters

components (Union[pypgx.api._property.VertexProperty, str]) – 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 (int) – How many different components the components property contains

Returns

The Partition object

Return type

pypgx.api._partition.PgxPartition

create_edge_property(data_type, name=None)

Create a session-bound edge property.

Parameters

data_type (str) – Type of the vector property to create
name (Optional[str]) – Name of vector property to be created

Return type

create_edge_sequence(name=None)

Create a new edge sequence.

Parameters: name (Optional[str]) – Sequence name
Return type: pypgx.api._pgx_collection.EdgeSequence

create_edge_set(name=None)

Create a new edge set.

Parameters: name (Optional[str]) – Edge set name
Return type: pypgx.api._pgx_collection.EdgeSet

create_edge_vector_property(data_type, dim, name=None)

Create a session-bound vector property.

Parameters

data_type (str) – Type of the vector property to create
dim (int) – Dimension of vector property to be created
name (Optional[str]) – Name of vector property to be created

Return type

pypgx.api._pgx_map.PgxMap

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 (str) – Property type of the keys that are going to be stored inside the map
val_type (str) – Property type of the values that are going to be stored inside the map
name (Optional[str]) – Map name

Return type

create_merging_strategy_builder()

Create a new MergingStrategyBuilder that can be used to build a new MutationStrategy to simplify this graph.

Return type: pypgx.api._mutation_strategy_builder.MergingStrategyBuilder

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

Parameters

src (pypgx.api._pgx_entity.PgxVertex) – Source vertex of the path
dst (pypgx.api._pgx_entity.PgxVertex) – Destination vertex of the path
cost (pypgx.api._property.EdgeProperty) – Property holding the edge costs. If null, the resulting cost will equal the hop distance.
parent (pypgx.api._property.VertexProperty) – 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 (pypgx.api._property.VertexProperty) – Property holding the parent edges for each vertex of the shortest path

Returns

The PgxPath object

Return type

pypgx.api._pgx_path.PgxPath

create_picking_strategy_builder()

Create a new PickingStrategyBuilder that can be used to build a new PickingStrategy to simplify this graph.

Return type: pypgx.api._mutation_strategy_builder.PickingStrategyBuilder

create_scalar(data_type, name=None)

Create a new Scalar.

Parameters

data_type (str) – Scalar type
name (Optional[str]) – Name of the scalar to be created

Return type

pypgx.api._scalar.Scalar

create_synchronizer(synchronizer_class='oracle.pgx.api.FlashbackSynchronizer', 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

synchronizer_class (str) – string representing java class including package, currently ‘oracle.pgx.api.FlashbackSynchronize’ is the only existent option
connection (Optional[Any]) – the connection object to the RDBMS (# TODO : GM-28504)
invalid_change_policy (Optional[str]) – sets the OnInvalidChange parameter to the Synchronizer ChangeSet

Returns

a synchronizer

Return type

pypgx.api._synchronizer.Synchronizer

create_vector_scalar(data_type, dimension=0, name=None)

Create a new vertex property.

Parameters

data_type (str) – Property type
dimension (int) – the dimension of the vector property
name (Optional[str]) – Name of the scalar to be created

Return type

pypgx.api._scalar.Scalar

create_vertex_property(data_type, name=None)

Create a new vertex property.

Parameters

data_type (str) – Property type
name (Optional[str]) – Name of the property to be created

Return type

create_vertex_sequence(name=None)

Create a new vertex sequence.

Parameters: name (Optional[str]) – Sequence name
Return type: pypgx.api._pgx_collection.VertexSequence

create_vertex_set(name=None)

Create a new vertex set.

Parameters: name (Optional[str]) – Set name
Return type: pypgx.api._pgx_collection.VertexSet

create_vertex_vector_property(data_type, dim, name=None)

Create a session-bound vertex vector property.

Parameters

data_type (str) – Type of the vector property to create
dim (int) – Dimension of vector property to be created
name (Optional[str]) – Name of vector property to be created

Return type

destroy()

Destroy the graph with all its properties.

After this operation, neither the graph nor its properties can be used anymore within this session.

Note

if you have multiple PgxGraph objects referencing the same graph (e.g. because you called PgxSession.get_graph() multiple times with the same argument), they will ALL become invalid after calling this method; therefore, subsequent operations on ANY of them will result in an exception.

Return type: None

destroy_edge_property_if_exists(name)

Destroy a specific edge property if it exists.

Parameters: name (str) – Property name
Return type: None

destroy_vertex_property_if_exists(name)

Destroy a specific vertex property if it exists.

Parameters: name (str) – Property name
Return type: None

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 (str) – Query string in PGQL
Returns: The query result set as PgqlResultSet object
Return type: Optional[pypgx.api._pgql_result_set.PgqlResultSet]

expand_with_pgql(pgql_queries, new_graph_name=None, pg_view_name=None, as_snapshot=False)

Expand this graph with data matching one or more PGQL queries. Given a list of either queries or prepared queries (with arguments), this will load all data matching at least on of the queries and merge it with the data from this graph.

Parameters

pgql_queries (Union[str, pypgx.api._graph_offloading.PreparedPgqlQuery, List[Union[str, pypgx.api._graph_offloading.PreparedPgqlQuery]]]) – One or more PGQL queries (or prepared queries).
new_graph_name (Optional[str]) – An optional name for the new graph.
pg_view_name (Optional[str]) – The PG View name from which to load the data.
scn – The SCN as of which the data should be loaded (optional).
as_snapshot (bool) – Expand as a new snapshot, instead of new graph?

Returns

The graph containing data both from this graph and the external source.

Return type

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 (str) – Query string in PGQL
Returns: The query plan
Return type: pypgx.api._operation.Operation

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 (Union[str, pypgx.api.filters._graph_filter.VertexFilter, pypgx.api.filters._graph_filter.EdgeFilter]) – Object representing a filter expression that is applied to create the subgraph
vertex_properties (bool) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (bool) – List of edge properties belonging to graph specified to be kept in the new graph
name (Optional[str]) – Filtered graph name

Return type

pypgx.api._pgx_collection.EdgeSet

get_collections()

Retrieve all currently allocated collections associated with the graph.

Return type: Dict[str, pypgx.api._pgx_collection.PgxCollection]

get_edge(eid)

Get an edge with a specified id.

Parameters: eid (int) – edge id
Return type: pypgx.api._pgx_entity.PgxEdge

get_edge_label()

Get the edge labels belonging to this graph.

Return type: pypgx.api._property.EdgeLabel

get_edge_properties()

Get the set of edge properties belonging to this graph.

This list might contain transient, private and published properties.

Return type: List[pypgx.api._property.EdgeProperty]

get_edge_property(name)

Get an edge property by name.

Parameters: name (str) – Property name
Return type: Optional[pypgx.api._property.EdgeProperty]

get_edges(filter_expr=None, name=None)

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

Parameters

filter_expr (Optional[Union[str, pypgx.api.filters._graph_filter.EdgeFilter]]) – EdgeFilter object with the filter expression. If None all the vertices are returned.
name (Optional[str]) – the name of the collection to be created. If None, a name will be generated.

Return type

get_id()

Get the Graph id.

Returns: A string representation of the id of this graph.
Return type: str

get_meta_data()

Get the GraphMetaData object.

Returns: A ‘GraphMetaData’ object of this graph.
Return type: pypgx.api._graph_meta_data.GraphMetaData

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

Get or create an edge property.

Parameters

name (str) – Property name
data_type (Optional[str]) – Property type
dim (int) – Dimension of vector property to be created

Return type

get_or_create_edge_vector_property(data_type, dim, name=None)

Get or create a session-bound edge property.

Parameters

data_type (str) – Type of the vector property to create
dim (int) – Dimension of vector property to be created
name (Optional[str]) – Name of vector property to be created

Return type

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

Get or create a vertex property.

Parameters

name (str) – Property name
data_type (Optional[str]) – Property type
dim (int) – Dimension of vector property to be created

Return type

get_or_create_vertex_vector_property(data_type, dim, name=None)

Get or create a session-bound vertex vector property.

Parameters

data_type (str) – Type of the vector property to create
dim (int) – Dimension of vector property to be created
name (Optional[str]) – Name of vector property to be created

Return type

pypgx.api._pgx_collection.VertexSet

get_permission()

Return permission object for the graph.

Return type: pypgx.api.auth._pgx_resource_permission.PgxResourcePermission

get_pgx_id()

Get the Graph id.

Returns: The id of this graph.
Return type: pypgx.api._pgx_id.PgxId

get_random_edge()

Get a edge vertex from the graph.

Return type: pypgx.api._pgx_entity.PgxEdge

get_random_vertex()

Get a random vertex from the graph.

Return type: pypgx.api._pgx_entity.PgxVertex

get_redaction_rules(authorization_type, name)

Get the redaction rules for an authorization_type name.

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

Parameters

authorization_type (str) – the authorization type of the rules to be returned
name (str) – 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

Return type

List[pypgx.api.redaction._redaction_rule_config.PgxRedactionRuleConfig]

get_vertex(vid)

Get a vertex with a specified id.

Parameters: vid (Union[str, int]) – Vertex id
Returns: pgxVertex object
Return type: pypgx.api._pgx_entity.PgxVertex

get_vertex_labels()

Get the vertex labels belonging to this graph.

Return type: pypgx.api._property.VertexLabels

get_vertex_properties()

Get the set of vertex properties belonging to this graph.

This list might contain transient, private and published properties.

Return type: List[pypgx.api._property.VertexProperty]

get_vertex_property(name)

Get a vertex property by name.

Parameters: name (str) – Property name
Return type: Optional[pypgx.api._property.VertexProperty]

get_vertices(filter_expr=None, name=None)

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

Parameters

filter_expr (Optional[Union[str, pypgx.api.filters._graph_filter.VertexFilter]]) – VertexFilter object with the filter expression if None all the vertices are returned
name (Optional[str]) – The name of the collection to be created. If None, a name will be generated.

Return type

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 (pypgx.api.auth._permission_entity.PermissionEntity) – the entity the rule is granted to
pgx_resource_permission (str) – the permission type

Return type

None

has_edge(eid)

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

Parameters: eid (int) – Edge id
Return type: bool

has_edge_label()

Return True if the graph has edge labels, False if not.

Return type: bool

has_vertex(vid)

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

Parameters: vid (int) – vertex id
Return type: bool

has_vertex_labels()

Return True if the graph has vertex labels, False if not.

Return type: bool

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 (Union[pypgx.api._property.VertexProperty, str]) – 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.
Return type: int

property is_fresh: bool: 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.

Return type: bool

property is_published: bool: 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
Return type: bool

property pgx_instance: pypgx.api._server_instance.ServerInstance: Get the server instance.

pick_random_vertex()

Select a random vertex from the graph.

Returns: The PgxVertex object
Return type: pypgx.api._pgx_entity.PgxVertex

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.

Return type: None

prepare_pgql(pgql_query)

Prepare a PGQL query.

Parameters: pgql_query (str) – Query string in PGQL
Returns: A prepared statement object
Return type: PreparedStatement

publish(vertex_properties=None, edge_properties=None)

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 (Optional[Union[List[pypgx.api._property.VertexProperty], bool]]) – List of vertex properties belonging to graph specified to be published as well
edge_properties (Optional[Union[List[pypgx.api._property.EdgeProperty], bool]]) – List of edge properties belonging to graph specified by graph to be published as well

Return type

None

publish_with_snapshots()

Publish the graph and all its snapshots so they can be shared between sessions.

Return type: None

query_pgql(query)

Submit a pattern matching select only query.

Parameters: query (str) – Query string in PGQL
Returns: PgqlResultSet with the result
Return type: pypgx.api._pgql_result_set.PgqlResultSet

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 (str) – the authorization type of the rule to be removed
names (str) – the names of the users or roles for which the rule should be removed
redaction_rule_config (pypgx.api.redaction._redaction_rule_config.PgxRedactionRuleConfig) –

Return type

None

rename(name)

Rename this graph.

Parameters: name (str) – New name
Return type: None

revoke_permission(permission_entity)

Revoke all permissions on this graph from the given entity.

Possible PermissionEntity objects are: PgxUser and PgxRole.

Parameters: permission_entity (pypgx.api.auth._permission_entity.PermissionEntity) – the entity for which all permissions will be revoked
Return type: None

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 (Union[bool, List[pypgx.api._property.VertexProperty]]) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (Union[bool, List[pypgx.api._property.EdgeProperty]]) – List of edge properties belonging to graph specified to be kept in the new graph
keep_multi_edges (bool) – Defines if multi-edges should be kept in the result
keep_self_edges (bool) – Defines if self-edges should be kept in the result
keep_trivial_vertices (bool) – Defines if isolated nodes should be kept in the result
in_place (bool) – If the operation should be done in place of if a new graph has to be created
name (Optional[str]) – New graph name. If None, a name will be generated. Only relevant if a new graph is to be created.

Return type

simplify_with_strategy(mutation_strategy)

Create a simplified version of a graph using a custom mutation strategy.

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: mutation_strategy (pypgx.api._mutation_strategy.MutationStrategy) – Defines a custom strategy for dealing with multi-edges.
Return type: pypgx.api._pgx_graph.PgxGraph

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 (Union[List[pypgx.api._property.VertexProperty], bool]) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (Union[List[pypgx.api._property.EdgeProperty], bool]) – List of edge properties belonging to graph specified to be kept in the new graph
ascending (bool) – Sorting order
in_degree (bool) – If in_degree should be used for sorting. Otherwise use out degree.
in_place (bool) – If the sorting should be done in place or a new graph should be created
name (Optional[str]) – New graph name

Return type

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

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

Parameters

sparsification (float) – The sparsification coefficient. Must be between 0.0 and 1.0..
vertex_properties (bool) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (bool) – List of edge properties belonging to graph specified to be kept in the new graph
name (Optional[str]) – Filtered graph name

Return type

pypgx.api._graph_config.GraphConfig

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

Store graph in a file.

Parameters

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

Return type

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 (bool) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (bool) – List of edge properties belonging to graph specified to be kept in the new graph
edge_label_mapping (Optional[Mapping[str, str]]) – 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 (bool) – If the transpose should be done in place or a new graph should be created
name (Optional[str]) – New graph name

Return type

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

Create an undirected version of the graph.

An undirected graph has some restrictions. Some algorithms are only supported on directed graphs or are not yet supported for undirected graphs. Further, PGX does not support storing undirected graphs nor reading from undirected formats. Since the edges do not have a direction anymore, the behavior of pgxEdge.source() or pgxEdge.destination() can be ambiguous. In order to provide deterministic results, PGX will always return the vertex with the smaller internal id as source and the other as destination vertex.

Parameters

vertex_properties (Union[bool, List[pypgx.api._property.VertexProperty]]) – List of vertex properties belonging to graph specified to be kept in the new graph
edge_properties (Union[bool, List[pypgx.api._property.EdgeProperty]]) – List of edge properties belonging to graph specified to be kept in the new graph
keep_multi_edges (bool) – Defines if multi-edges should be kept in the result
keep_self_edges (bool) – Defines if self-edges should be kept in the result
keep_trivial_vertices (bool) – Defines if isolated nodes should be kept in the result
in_place (bool) – If the operation should be done in place of if a new graph has to be created
name (Optional[str]) – New graph name

Return type