3. Managing Sessions

The PgxSession class can be used to manage and execute operations on the underlying session.

class pypgx.api.PgxSession(java_session)

A PGX session represents an active user connected to a ServerInstance.

Every session gets a workspace assigned on the server, which can be used to read graph data, create transient data or custom algorithms for the sake of graph analysis. Once a session gets destroyed, all data in the session workspace is freed.

close()

Close this session object.

compile_program(path, overwrite=False)

Compile a Green-Marl program for parallel execution with all optimizations enabled.

Parameters

  • path – Path to program

  • overwrite – If the procedure in the given code already exists, overwrite if true, throw an exception otherwise

compile_program_code(code, overwrite=False)

Compile a Green-Marl program.

Parameters

  • code – The Green-Marl code to compile

  • overwrite – If the procedure in the given code already exists, overwrite if true, throw an exception otherwise

create_analyst()

Create and return a new analyst.

Returns

An analyst object

create_frame(schema, column_data, frame_name)

Create a frame with the specified data

Parameters

  • schema – List of tuples (columnName, columnType)

  • column_data – Map of iterables, columnName -> columnData

  • frame_name – Name of the frame

Returns

A frame builder initialized with the given schema

create_frame_builder(schema)

Create a frame builder initialized with the given schema

Parameters

schema – List of tuples (columnName, columnType)

Returns

A frame builder initialized with the given schema

create_graph_builder(id_type='integer', vertex_id_generation_strategy='user_ids', edge_id_generation_strategy='auto_generated')

Create a graph builder with integer vertex IDs.

Parameters

  • id_type – The type of the vertex ID

  • vertex_id_generation_strategy – The vertices Id generation strategy to be used

  • edge_id_generation_strategy – The edges Id generation strategy to be used

create_map(key_type, value_type, name=None)

Create a 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

  • value_type – Property type of the values that are going to be stored inside the map

  • name – Map name

Returns

A named PgxMap of key content type key_type and value content type value_type

create_sequence(content_type, name=None)

Create a sequence of scalars.

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

Parameters

  • content_type – Property type of the elements in the sequence

  • name – Sequence name

Returns

A named ScalarSequence of content type content_type

create_set(content_type, name=None)

Create a set of scalars.

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

Parameters

  • content_type – content type of the set

  • name – the set’s name

Returns

A named ScalarSet of content type content_type

describe_graph_file(file_path)

Describe the graph contained in the file at the given path.

Parameters

file_path – Graph file path

Returns

The configuration which can be used to load the graph

describe_graph_files(files_path)

Describe the graph contained in the files at the given paths.

Parameters

files_path – Paths to the files

Returns

The configuration which can be used to load the graph

destroy()

Destroy this session object.

edge_provider_from_frame(provider_name, source_provider, destination_provider, frame, source_vertex_column='src', destination_vertex_column='dst')

Create an edge provider from a PgxFrame to later build a PgxGraph

Parameters

  • provider_name – edge provider name

  • source_provider – vertex source provider name

  • destination_provider – vertex destination provider name

  • frame – PgxFrame to use

  • source_vertex_column – column to use as source keys. Defaults to “src”

  • destination_vertex_column – column to use as destination keys. Defaults to “dst”

Returns

the EdgeFrameDeclaration object

execute_pgql(pgql_query)

Submit any query with a ON-clause.

The ON-clause indicates the graph on which the query will be executed. The graph name in the ON-clause is evaluated with the same semantics as PgxSession.getGraphAsync(String).

Parameters

pgql_query – Query string in PGQL

Returns

The query result set

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.

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

get_available_compiled_program_ids()

Get the set of available compiled program IDs.

get_available_snapshots(snapshot)

Return a list of all available snapshots of the given input graph.

Parameters

snapshot – A ‘PgxGraph’ object for which the available snapshots shall be retrieved

Returns

A list of ‘GraphMetaData’ objects, each corresponding to a snapshot of the input graph

get_compiled_program(id)

Get a compiled program by ID.

Parameters

id – The id of the compiled program

get_graph(name, namespace=None)

Find and return a graph with name name within the given namespace loaded inside PGX.

The search for the snapshot to return is done according to the following rules:

  • if namespace is private, than the search occurs on already referenced snapshots of the graph with name name and the most recent snapshot is returned

  • if namespace is public, then the search occurs on published graphs and the most recent snapshot of the published graph with name name is returned

  • if namespace is null, then the private namespace is searched first and, if no snapshot is found, the public namespace is then searched

Multiple calls of this method with the same parameters will return different PgxGraph objects referencing the same graph, with the server keeping track of how many references a session has to each graph.

Therefore, a graph is released within the server either if:

  • all the references are moved to another graph (e.g. via setSnapshot(PgxGraph, long))

  • the Destroyable.destroy() method is called on one reference: note that

this invalidates all references

Parameters

  • name – The name of the graph

  • namespace – The namespace where to look up the graph

Returns

The graph with the given name

get_graphs(namespace=None)

Return a collection of graph names accessible under the given namespace.

Parameters

namespace – The namespace where to look up the graphs

get_idle_timeout()

Get the idle timeout of this session

Returns

the idle timeout in seconds

get_name()

Get the identifier of the current session.

Returns

identifier of this session

get_pattern_matching_semantic()
Returns

The current pattern matching semantic. If the return value is None, the current session respects the pattern matching configuration of the engine.

get_pgql_result_set(id)

Get a PGQL result set by ID.

Parameters

id – The PGQL result set ID

Returns

The requested PGQL result set or None if no such result set exists for this session

get_session_context()

Get the context describing the current session.

Returns

context of this session

get_source()

Get the current session source

Returns

session source

get_task_timeout()

Get the task timeout of this session

Returns

the task timeout in seconds

graph_from_frames(graph_name, vertex_providers, edge_providers, partitioned=True)

Create PgxGraph from vertex providers and edge providers.

partitioned must be set to True if multiple vertex or edge providers are given

Parameters

  • graph_name – graph name

  • vertex_providers – list of vertex providers

  • edge_providers – list of edge providers

  • partitioned – whether the graph is partitioned or not. Defaults to True

Returns

the PgxGraph object

pandas_to_pgx_frame(pandas_dataframe, frame_name)

Create a frame from a pandas dataframe Duplicate columns will be renamed. Mixed column types are not supported.

This method requires pandas

Parameters

  • frame_name – Name of the frame

  • pandas_dataframe – The Pandas dataframe to use

Returns

the frame created

prepare_pgql(pgql_query)

Prepare a pattern matching query with a ON-clause.

The ON-clause indicates the graph on which the query will be executed. The graph name in the ON-clause is evaluated with the same semantics as getGraph(String).

Parameters

pgql_query – Query string in PGQL

Returns

A prepared statement object

query_pgql(pgql_query)

Submit a pattern matching query with a ON-clause.

The ON-clause indicates the graph on which the query will be executed. The graph name in the ON-clause is evaluated with the same semantics as PgxSession.getGraph(String).

Parameters

pgql_query – Query string in PGQL

Returns

The query result set

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.

read_frame()

Create a new frame reader with which it is possible to parameterize the loading of the row frame.

Returns

A frame reader object with which it is possible to parameterize the loading

read_graph_as_of(config, meta_data=None, creation_timestamp=None, new_graph_name=None)

Read a graph and its properties of a specific version (metaData or creationTimestamp) into memory.

The creationTimestamp must be a valid version of the graph.

Parameters

  • config – The graph config

  • meta_data – The metaData object returned by get_available_snapshots(GraphConfig) identifying the version

  • creation_timestamp – The creation timestamp (milliseconds since jan 1st 1970) identifying the version to be checked out

  • new_graph_name – How the graph should be named. If None, a name will be generated.

Returns

The PgxGraph object

read_graph_by_name(graph_name, graph_source)
Parameters

  • graph_name – Name of graph

  • graph_source – Source of graph

read_graph_file(file_path, file_format=None, graph_name=None)
Parameters

  • file_path – File path

  • file_format – File format of graph

  • graph_name – Name of graph

read_graph_files(file_paths, edge_file_paths=None, file_format=None, graph_name=None)

Load the graph contained in the files at the given paths.

Parameters

  • file_paths – Paths to the vertex files

  • edge_file_paths – Path to the edge file

  • file_format – File format

  • graph_name – Loaded graph name

read_graph_with_properties(config, max_age=9223372036854775807, max_age_time_unit='days', block_if_full=False, update_if_not_fresh=True, graph_name=None)

Read a graph and its properties, specified in the graph config, into memory.

Parameters

  • config – The graph config

  • max_age – If another snapshot of the given graph already exists, the age of the latest existing snapshot will be compared to the given maxAge. If the latest snapshot is in the given range, it will be returned, otherwise a new snapshot will be created.

  • max_age_time_unit – The time unit of the maxAge parameter

  • block_if_full – If true and a new snapshot needs to be created but no more snapshots are allowed by the server configuration, the returned future will not complete until space becomes available. Iterable full and this flage is false, the returned future will complete exceptionally instead.

  • update_if_not_fresh – If a newer data version exists in the backing data source (see PgxGraph.is_fresh()), this flag tells whether to read it and create another snapshot inside PGX. If the “snapshots_source” field of config is SnapshotsSource.REFRESH, the returned graph may have multiple snapshots, depending on whether previous reads with the same config occurred; otherwise, if the “snapshots_source” field is SnapshotsSource.CHANGE_SET, only the most recent snapshot (either pre-existing or freshly read) will be visible.

  • graph_name – How the graph should be named. If null, a name will be generated. If a graph with that name already exists, the returned future will complete exceptionally.

register_keystore(keystore_path, keystore_password)

Register a keystore.

Parameters

  • keystore_path – The path to the keystore which shall be registered

  • keystore_password – The password of the provided keystore

property server_instance

Get the server instance.

Returns

The server instance

set_pattern_matching_semantic(pattern_matching_semantic)

Set the pattern matching semantic of the session.

Parameters

pattern_matching_semantic – Pattern matching semantic. If None is passed, the session respects the pattern matching semantic of the engine. Should be either ‘HOMOMORPHISM’ or ‘ISOMORPHISM’.

set_snapshot(graph, meta_data=None, creation_timestamp=None, force_delete_properties=False)

Set a graph to a specific snapshot.

You can use this method to jump back and forth in time between various snapshots of the same graph. If successful, the given graph will point to the requested snapshot after the returned future completes.

Parameters

  • graph – Input graph

  • meta_data – A GraphMetaData object used to identify the snapshot

  • creation_timestamp – The metaData object returned by (GraphConfig) identifying the version to be checked out

  • force_delete_properties – Graphs with transient properties cannot be checked out to a different version. If this flag is set to true, the checked out graph will no longer contain any transient properties. If false, the returned future will complete exceptionally with an UnsupportedOperationException as its cause.

vertex_provider_from_frame(provider_name, frame, vertex_key_column='id')

Create a vertex provider from a PgxFrame to later build a PgxGraph

Parameters

  • provider_name – vertex provider name

  • frame – PgxFrame to use

  • vertex_key_column – column to use as keys. Defaults to “id”

Returns

the VertexFrameDeclaration object