PersistentGraph

A temporal graph that allows edges and nodes to be deleted.

Methods

Method	Description
`add_edge`	Adds a new edge with the given source and destination nodes and properties to the graph.
`add_metadata`	Adds metadata to the graph.
`add_node`	Adds a new node with the given id and properties to the graph.
`add_properties`	Adds properties to the graph.
`cache`	Write PersistentGraph to cache file and initialise the cache.
`create_index`	Create graph index
`create_index_in_ram`	Creates a graph index in memory (RAM).
`create_index_in_ram_with_spec`	Creates a graph index in memory (RAM) with the provided index spec.
`create_index_with_spec`	Create graph index with the provided index spec.
`create_node`	Creates a new node with the given id and properties to the graph. It fails if the node already exists.
`delete_edge`	Deletes an edge given the timestamp, src and dst nodes and layer (optional).
`deserialise`	Load PersistentGraph from serialised bytes.
`edge`	Gets the edge with the specified source and destination nodes
`event_graph`	Get event graph
`get_all_node_types`	Returns all the node types in the graph.
`import_edge`	Import a single edge into the graph.
`import_edge_as`	Import a single edge into the graph with new id.
`import_edges`	Import multiple edges into the graph.
`import_edges_as`	Import multiple edges into the graph with new ids.
`import_node`	Import a single node into the graph.
`import_node_as`	Import a single node into the graph with new id.
`import_nodes`	Import multiple nodes into the graph.
`import_nodes_as`	Import multiple nodes into the graph with new ids.
`load_cached`	Load PersistentGraph from a file and initialise it as a cache file.
`load_edge_deletions`	Load edge deletions into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method),
`load_edge_metadata`	Load edge metadata into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method),
`load_edges`	Load edges into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method),
`load_from_file`	Load PersistentGraph from a file.
`load_node_metadata`	Load node metadata into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method),
`load_nodes`	Load nodes into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method),
`node`	Gets the node with the specified id
`persistent_graph`	Get persistent graph
`save_to_file`	Saves the PersistentGraph to the given path.
`save_to_zip`	Saves the PersistentGraph to the given path.
`serialise`	Serialise PersistentGraph to bytes.
`update_metadata`	Updates metadata of the graph.
`write_updates`	Persist the new updates by appending them to the cache file.

Method Details

add_edge

Signature: add_edge(timestamp, src, dst, properties=None, layer=None, event_id=None)

Adds a new edge with the given source and destination nodes and properties to the graph.

Parameters

Name	Type	Default	Description
`timestamp`	int	-	The timestamp of the edge.
`src`	str \| int	-	The id of the source node.
`dst`	str \| int	-	The id of the destination node.
`properties`	PropInput, optional	`None`	The properties of the edge, as a dict of string and properties.
`layer`	str, optional	`None`	The layer of the edge.
`event_id`	int, optional	`None`	The optional integer which will be used as an event id.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

add_metadata

Signature: add_metadata(metadata)

Adds metadata to the graph.

Parameters

Name	Type	Default	Description
`metadata`	dict	-	The static properties of the graph.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

add_node

Signature: add_node(timestamp, id, properties=None, node_type=None, event_id=None)

Adds a new node with the given id and properties to the graph.

Parameters

Name	Type	Default	Description
`timestamp`	TimeInput	-	The timestamp of the node.
`id`	str \| int	-	The id of the node.
`properties`	PropInput, optional	`None`	The properties of the node.
`node_type`	str, optional	`None`	The optional string which will be used as a node type.
`event_id`	int, optional	`None`	The optional integer which will be used as an event id.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

add_properties

Signature: add_properties(timestamp, properties, event_id=None)

Adds properties to the graph.

Parameters

Name	Type	Default	Description
`timestamp`	TimeInput	-	The timestamp of the temporal property.
`properties`	dict	-	The temporal properties of the graph.
`event_id`	int, optional	`None`	The optional integer which will be used as an event id.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

cache

Signature: cache(path)

Write PersistentGraph to cache file and initialise the cache.

Future updates are tracked. Use write_updates to persist them to the cache file. If the file already exists its contents are overwritten.

Parameters

Name	Type	Default	Description
`path`	str	-	The path to the cache file

Returns

Type	Description
None

create_index

Create graph index

Returns

Type	Description
None

create_index_in_ram

Creates a graph index in memory (RAM).

This is primarily intended for use in tests and should not be used in production environments, as the index will not be persisted to disk.

Returns

Type	Description
None

create_index_in_ram_with_spec

Signature: create_index_in_ram_with_spec(py_spec)

Creates a graph index in memory (RAM) with the provided index spec.

This is primarily intended for use in tests and should not be used in production environments, as the index will not be persisted to disk.

Parameters

Name	Type	Default	Description
`py_spec`	IndexSpec	-	The specification for the in-memory index to be created.

Returns

Type	Description
None

create_index_with_spec

Signature: create_index_with_spec(py_spec)

Create graph index with the provided index spec.

Parameters

Name	Type	Default	Description
`py_spec`	Any	-

Returns

Type	Description
None

create_node

Signature: create_node(timestamp, id, properties=None, node_type=None, event_id=None)

Creates a new node with the given id and properties to the graph. It fails if the node already exists.

Parameters

Name	Type	Default	Description
`timestamp`	TimeInput	-	The timestamp of the node.
`id`	str \| int	-	The id of the node.
`properties`	PropInput, optional	`None`	The properties of the node.
`node_type`	str, optional	`None`	The optional string which will be used as a node type.
`event_id`	int, optional	`None`	The optional integer which will be used as an event id.

Returns

Type	Description
MutableNode	the newly created node.

Raises

Exception	Description
`GraphError`	If the operation fails.

delete_edge

Signature: delete_edge(timestamp, src, dst, layer=None, event_id=None)

Deletes an edge given the timestamp, src and dst nodes and layer (optional).

Parameters

Name	Type	Default	Description
`timestamp`	int	-	The timestamp of the edge.
`src`	str \| int	-	The id of the source node.
`dst`	str \| int	-	The id of the destination node.
`layer`	str, optional	`None`	The layer of the edge.
`event_id`	int, optional	`None`	The optional integer which will be used as an event id.

Returns

Type	Description
MutableEdge	The deleted edge

Raises

Exception	Description
`GraphError`	If the operation fails.

deserialise

Signature: deserialise(bytes)

Load PersistentGraph from serialised bytes.

Parameters

Name	Type	Default	Description
`bytes`	bytes	-	The serialised bytes to decode

Returns

Type	Description
PersistentGraph

edge

Signature: edge(src, dst)

Gets the edge with the specified source and destination nodes

Parameters

Name	Type	Default	Description
`src`	str \| int	-	the source node id
`dst`	str \| int	-	the destination node id

Returns

Type	Description
MutableEdge, optional	The edge with the specified source and destination nodes, or None if the edge does not exist

event_graph

Get event graph

Returns

Type	Description
Graph	the graph with event semantics applied

get_all_node_types

Returns all the node types in the graph.

Returns

Type	Description
list[str]	A list of node types

import_edge

Signature: import_edge(edge, merge=False)

Import a single edge into the graph.

This function takes an edge object and an optional boolean flag. If the flag is set to true, the function will merge the import of the edge even if it already exists in the graph.

Parameters

Name	Type	Default	Description
`edge`	Edge	-	An edge object representing the edge to be imported.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the edge. Defaults to False.

Returns

Type	Description
Edge	The imported edge.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_edge_as

Signature: import_edge_as(edge, new_id, merge=False)

Import a single edge into the graph with new id.

This function takes a edge object, a new edge id and an optional boolean flag. If the flag is set to true, the function will merge the import of the edge even if it already exists in the graph.

Parameters

Name	Type	Default	Description
`edge`	Edge	-	A edge object representing the edge to be imported.
`new_id`	tuple	-	The ID of the new edge. It's a tuple of the source and destination node ids.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the edge. Defaults to False.

Returns

Type	Description
Edge	The imported edge.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_edges

Signature: import_edges(edges, merge=False)

Import multiple edges into the graph.

This function takes a vector of edge objects and an optional boolean flag. If the flag is set to true, the function will merge the import of the edges even if they already exist in the graph.

Parameters

Name	Type	Default	Description
`edges`	list[Edge]	-	A vector of edge objects representing the edges to be imported.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the edges. Defaults to False.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_edges_as

Signature: import_edges_as(edges, new_ids, merge=False)

Import multiple edges into the graph with new ids.

This function takes a vector of edge objects, a list of new edge ids and an optional boolean flag. If the flag is set to true, the function will merge the import of the edges even if they already exist in the graph.

Parameters

Name	Type	Default	Description
`edges`	list[Edge]	-	A vector of edge objects representing the edges to be imported.
`new_ids`	list[tuple[GID, GID]]	-	The new edge ids
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the edges. Defaults to False.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_node

Signature: import_node(node, merge=False)

Import a single node into the graph.

This function takes a node object and an optional boolean flag. If the flag is set to true, the function will merge the import of the node even if it already exists in the graph.

Parameters

Name	Type	Default	Description
`node`	Node	-	A node object representing the node to be imported.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the node. Defaults to False.

Returns

Type	Description
Node	A Node object if the node was successfully imported, and an error otherwise.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_node_as

Signature: import_node_as(node, new_id, merge=False)

Import a single node into the graph with new id.

This function takes a node object, a new node id and an optional boolean flag. If the flag is set to true, the function will merge the import of the node even if it already exists in the graph.

Parameters

Name	Type	Default	Description
`node`	Node	-	A node object representing the node to be imported.
`new_id`	str \| int	-	The new node id.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the node. Defaults to False.

Returns

Type	Description
Node	A Node object if the node was successfully imported, and an error otherwise.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_nodes

Signature: import_nodes(nodes, merge=False)

Import multiple nodes into the graph.

This function takes a vector of node objects and an optional boolean flag. If the flag is set to true, the function will merge the import of the nodes even if they already exist in the graph.

Parameters

Name	Type	Default	Description
`nodes`	list[Node]	-	A vector of node objects representing the nodes to be imported.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the nodes. Defaults to False.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_nodes_as

Signature: import_nodes_as(nodes, new_ids, merge=False)

Import multiple nodes into the graph with new ids.

This function takes a vector of node objects, a list of new node ids and an optional boolean flag. If the flag is set to true, the function will merge the import of the nodes even if they already exist in the graph.

Parameters

Name	Type	Default	Description
`nodes`	list[Node]	-	A vector of node objects representing the nodes to be imported.
`new_ids`	List \| `int]`	-	A list of node IDs to use for the imported nodes.
`merge`	bool, optional	`False`	An optional boolean flag indicating whether to merge the import of the nodes. Defaults to False.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

load_cached

Signature: load_cached(path)

Load PersistentGraph from a file and initialise it as a cache file.

Future updates are tracked. Use write_updates to persist them to the cache file.

Parameters

Name	Type	Default	Description
`path`	str	-	The path to the cache file

Returns

Type	Description
PersistentGraph	the loaded graph with initialised cache

load_edge_deletions

Signature: load_edge_deletions(data, time, src, dst, layer=None, layer_col=None, schema=None, csv_options=None)

Load edge deletions into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method), a path to a CSV or Parquet file, or a directory containing multiple CSV or Parquet files. The following are known to support the ArrowStreamExportable protocol: Pandas dataframes, FireDucks(.pandas) dataframes, Polars dataframes, Arrow tables, DuckDB (e.g. DuckDBPyRelation obtained from running an SQL query).

Parameters

Name	Type	Default	Description
`data`	Any	-	The data source containing the edges.
`time`	str	-	The column name for the update timestamps.
`src`	str	-	The column name for the source node ids.
`dst`	str	-	The column name for the destination node ids.
`layer`	str, optional	`None`	A value to use as the layer for all edges. Cannot be used in combination with layer_col. Defaults to None.
`layer_col`	str, optional	`None`	The edge layer col name in the data source. Cannot be used in combination with layer. Defaults to None.
`schema`	list \| PropType \| `str]]` \| dict \| PropType \| `str]`, optional	`None`	A list of (column_name, column_type) tuples or dict of {"column_name": column_type} to cast columns to. Defaults to None.
`csv_options`	dict \| `bool]`, optional	`None`	A dictionary of CSV reading options such as delimiter, comment, escape, quote, and terminator characters, as well as allow_truncated_rows and has_header flags. Defaults to None.

Returns

Type	Description
None	This function does not return a value, if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

load_edge_metadata

Signature: load_edge_metadata(data, src, dst, metadata=None, shared_metadata=None, layer=None, layer_col=None, schema=None, csv_options=None)

Load edge metadata into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method), a path to a CSV or Parquet file, or a directory containing multiple CSV or Parquet files. The following are known to support the ArrowStreamExportable protocol: Pandas dataframes, FireDucks(.pandas) dataframes, Polars dataframes, Arrow tables, DuckDB (e.g. DuckDBPyRelation obtained from running an SQL query).

Parameters

Name	Type	Default	Description
`data`	Any	-	The data source containing edge information.
`src`	str	-	The column name for the source node.
`dst`	str	-	The column name for the destination node.
`metadata`	list[str], optional	`None`	List of edge metadata column names. Defaults to None.
`shared_metadata`	PropInput, optional	`None`	A dictionary of metadata properties that will be added to every edge. Defaults to None.
`layer`	str, optional	`None`	The edge layer name. Defaults to None.
`layer_col`	str, optional	`None`	The edge layer column name in a dataframe. Defaults to None.
`schema`	list \| PropType \| `str]]` \| dict \| PropType \| `str]`, optional	`None`	A list of (column_name, column_type) tuples or dict of {"column_name": column_type} to cast columns to. Defaults to None.
`csv_options`	dict \| `bool]`, optional	`None`	A dictionary of CSV reading options such as delimiter, comment, escape, quote, and terminator characters, as well as allow_truncated_rows and has_header flags. Defaults to None.

Returns

Type	Description
None	This function does not return a value if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

load_edges

Signature: load_edges(data, time, src, dst, properties=None, metadata=None, shared_metadata=None, layer=None, layer_col=None, schema=None, csv_options=None)

Load edges into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method), a path to a CSV or Parquet file, or a directory containing multiple CSV or Parquet files. The following are known to support the ArrowStreamExportable protocol: Pandas dataframes, FireDucks(.pandas) dataframes, Polars dataframes, Arrow tables, DuckDB (e.g. DuckDBPyRelation obtained from running an SQL query).

Parameters

Name	Type	Default	Description
`data`	Any	-	The data source containing the edges.
`time`	str	-	The column name for the update timestamps.
`src`	str	-	The column name for the source node IDs.
`dst`	str	-	The column name for the destination node IDs.
`properties`	list[str], optional	`None`	List of edge property column names. Defaults to None.
`metadata`	list[str], optional	`None`	List of edge metadata column names. Defaults to None.
`shared_metadata`	PropInput, optional	`None`	A dictionary of metadata properties that will be added to every edge. Defaults to None.
`layer`	str, optional	`None`	A value to use as the layer for all edges. Cannot be used in combination with layer_col. Defaults to None.
`layer_col`	str, optional	`None`	The edge layer column name in a dataframe. Cannot be used in combination with layer. Defaults to None.
`schema`	list \| PropType \| `str]]` \| dict \| PropType \| `str]`, optional	`None`	A list of (column_name, column_type) tuples or dict of {"column_name": column_type} to cast columns to. Defaults to None.
`csv_options`	dict \| `bool]`, optional	`None`	A dictionary of CSV reading options such as delimiter, comment, escape, quote, and terminator characters, as well as allow_truncated_rows and has_header flags. Defaults to None.

Returns

Type	Description
None	This function does not return a value if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

load_from_file

Signature: load_from_file(path)

Load PersistentGraph from a file.

Parameters

Name	Type	Default	Description
`path`	str	-	The path to the file.

Returns

Type	Description
PersistentGraph

load_node_metadata

Signature: load_node_metadata(data, id, node_type=None, node_type_col=None, metadata=None, shared_metadata=None, schema=None, csv_options=None)

Load node metadata into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method), a path to a CSV or Parquet file, or a directory containing multiple CSV or Parquet files. The following are known to support the ArrowStreamExportable protocol: Pandas dataframes, FireDucks(.pandas) dataframes, Polars dataframes, Arrow tables, DuckDB (e.g. DuckDBPyRelation obtained from running an SQL query).

Parameters

Name	Type	Default	Description
`data`	Any	-	The data source containing node information.
`id`	str	-	The column name for the node IDs.
`node_type`	str, optional	`None`	A value to use as the node type for all nodes. Cannot be used in combination with node_type_col. Defaults to None.
`node_type_col`	str, optional	`None`	The node type column name in a dataframe. Cannot be used in combination with node_type. Defaults to None.
`metadata`	list[str], optional	`None`	List of node metadata column names. Defaults to None.
`shared_metadata`	PropInput, optional	`None`	A dictionary of metadata properties that will be added to every node. Defaults to None.
`schema`	list \| PropType \| `str]]` \| dict \| PropType \| `str]`, optional	`None`	A list of (column_name, column_type) tuples or dict of {"column_name": column_type} to cast columns to. Defaults to None.
`csv_options`	dict \| `bool]`, optional	`None`	A dictionary of CSV reading options such as delimiter, comment, escape, quote, and terminator characters, as well as allow_truncated_rows and has_header flags. Defaults to None.

Returns

Type	Description
None	This function does not return a value if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

load_nodes

Signature: load_nodes(data, time, id, node_type=None, node_type_col=None, properties=None, metadata=None, shared_metadata=None, schema=None, csv_options=None)

Load nodes into the graph from any data source that supports the ArrowStreamExportable protocol (by providing an arrow_c_stream() method), a path to a CSV or Parquet file, or a directory containing multiple CSV or Parquet files. The following are known to support the ArrowStreamExportable protocol: Pandas dataframes, FireDucks(.pandas) dataframes, Polars dataframes, Arrow tables, DuckDB (e.g. DuckDBPyRelation obtained from running an SQL query).

Parameters

Name	Type	Default	Description
`data`	Any	-	The data source containing the nodes.
`time`	str	-	The column name for the timestamps.
`id`	str	-	The column name for the node IDs.
`node_type`	str, optional	`None`	A value to use as the node type for all nodes. Cannot be used in combination with node_type_col. Defaults to None.
`node_type_col`	str, optional	`None`	The node type column name in a dataframe. Cannot be used in combination with node_type. Defaults to None.
`properties`	list[str], optional	`None`	List of node property column names. Defaults to None.
`metadata`	list[str], optional	`None`	List of node metadata column names. Defaults to None.
`shared_metadata`	PropInput, optional	`None`	A dictionary of metadata properties that will be added to every node. Defaults to None.
`schema`	list \| PropType \| `str]]` \| dict \| PropType \| `str]`, optional	`None`	A list of (column_name, column_type) tuples or dict of {"column_name": column_type} to cast columns to. Defaults to None.
`csv_options`	dict \| `bool]`, optional	`None`	A dictionary of CSV reading options such as delimiter, comment, escape, quote, and terminator characters, as well as allow_truncated_rows and has_header flags. Defaults to None.

Returns

Type	Description
None	This function does not return a value if the operation is successful.

Raises

Exception	Description
`GraphError`	If the operation fails.

node

Signature: node(id)

Gets the node with the specified id

Parameters

Name	Type	Default	Description
`id`	str \| int	-	the node id

Returns

Type	Description
MutableNode, optional	The node with the specified id, or None if the node does not exist