Graph

A temporal graph with event semantics.

Methods

Method	Description
`add_edge`	Adds a new edge with the given source and destination nodes and properties to the graph.
`add_metadata`	Adds static properties 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 Graph 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.
`deserialise`	Load Graph from serialised bytes.
`edge`	Gets the edge with the specified source and destination nodes
`event_graph`	View graph with event semantics
`from_parquet`	Read graph from parquet files
`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.
`largest_connected_component`	Gives the large connected component of a graph.
`load_cached`	Load Graph from a file and initialise it as a cache file.
`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 Graph 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`	View graph with persistent semantics
`save_to_file`	Saves the Graph to the given path.
`save_to_zip`	Saves the Graph to the given path.
`serialise`	Serialise Graph to bytes.
`to_parquet`	Persist graph to parquet files.
`update_metadata`	Updates static properties to 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`	TimeInput	-	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
MutableEdge	The added edge.

Raises

Exception	Description
`GraphError`	If the operation fails.

add_metadata

Signature: add_metadata(metadata)

Adds static properties to the graph.

Parameters

Name	Type	Default	Description
`metadata`	PropInput	-	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
MutableNode	The added node.

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`	PropInput	-	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 Graph 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 created node.

Raises

Exception	Description
`GraphError`	If the operation fails.

deserialise

Signature: deserialise(bytes)

Load Graph from serialised bytes.

Parameters

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

Returns

Type	Description
Graph

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	the edge with the specified source and destination nodes, or None if the edge does not exist

event_graph

View graph with event semantics

Returns

Type	Description
Graph	the graph with event semantics applied

from_parquet

Signature: from_parquet(graph_dir)

Read graph from parquet files

Parameters

Name	Type	Default	Description
`graph_dir`	str \| PathLike	-	the folder where the graph is stored as parquet

Returns

Type	Description
Graph	a view of the graph

get_all_node_types

Returns all the node types in the graph.

Returns

Type	Description
list[str]	the node types

import_edge

Signature: import_edge(edge, merge=False)

Import a single edge into the graph.

Parameters

Name	Type	Default	Description
`edge`	Edge	-	A Edge object representing the edge to be imported.
`merge`	bool, optional	`False`	An optional boolean flag. Defaults to False. If merge is False, the function will return an error if the imported edge already exists in the graph. If merge is True, the function merges the histories of the imported edge and the existing edge (in the graph).

Returns

Type	Description
MutableEdge	An Edge object if the edge was successfully imported.

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.

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. Defaults to False. If merge is False, the function will return an error if the imported edge already exists in the graph. If merge is True, the function merges the histories of the imported edge and the existing edge (in the graph).

Returns

Type	Description
Edge	An Edge object if the edge was successfully imported.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_edges

Signature: import_edges(edges, merge=False)

Import multiple edges into the graph.

Parameters

Name	Type	Default	Description
`edges`	list[Edge]	-	A list of Edge objects representing the edges to be imported.
`merge`	bool, optional	`False`	An optional boolean flag. Defaults to False. If merge is False, the function will return an error if any of the imported edges already exists in the graph. If merge is True, the function merges the histories of the imported edges and the existing edges (in 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.

import_edges_as

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

Import multiple edges into the graph with new ids.

Parameters

Name	Type	Default	Description
`edges`	list[Edge]	-	A list of Edge objects representing the edges to be imported.
`new_ids`	list[tuple[int, int]]	-	The IDs of the new edges. It's a vector of tuples of the source and destination node ids.
`merge`	bool, optional	`False`	An optional boolean flag. Defaults to False. If merge is False, the function will return an error if any of the imported edges already exists in the graph. If merge is True, the function merges the histories of the imported edges and the existing edges (in 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.

import_node

Signature: import_node(node, merge=False)

Import a single node into 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. Defaults to False. If merge is False, the function will return an error if the imported node already exists in the graph. If merge is True, the function merges the histories of the imported node and the existing node (in the graph).

Returns

Type	Description
Node	A node object if the node was successfully imported.

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.

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. Defaults to False. If merge is False, the function will return an error if the imported node already exists in the graph. If merge is True, the function merges the histories of the imported node and the existing node (in the graph).

Returns

Type	Description
MutableNode	A node object if the node was successfully imported.

Raises

Exception	Description
`GraphError`	If the operation fails.

import_nodes

Signature: import_nodes(nodes, merge=False)

Import multiple nodes into 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. Defaults to False. If merge is False, the function will return an error if any of the imported nodes already exists in the graph. If merge is True, the function merges the histories of the imported nodes and the existing nodes (in 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.

import_nodes_as

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

Import multiple nodes into the graph with new ids.

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. Defaults to False. If merge is True, the function will return an error if any of the imported nodes already exists in the graph. If merge is False, the function merges the histories of the imported nodes and the existing nodes (in 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.

largest_connected_component

Gives the large connected component of a graph.

Example Usage:

g.largest_connected_component()

Returns

Type	Description
GraphView	sub-graph of the graph `g` containing the largest connected component

load_cached

Signature: load_cached(path)

Load Graph 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
Graph	the loaded graph with initialised cache

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 Graph from a file.

Parameters

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

Returns

Type	Description
Graph

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	The node object with the specified id, or None if the node does not exist

persistent_graph

View graph with persistent semantics

Returns

Type	Description
PersistentGraph	the graph with persistent semantics applied

save_to_file

Signature: save_to_file(path)

Saves the Graph to the given path.

Parameters

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

Returns

Type	Description
None

save_to_zip

Signature: save_to_zip(path)

Saves the Graph to the given path.

Parameters

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

Returns

Type	Description
None

serialise

Serialise Graph to bytes.

Returns

Type	Description
bytes

to_parquet

Signature: to_parquet(graph_dir)

Persist graph to parquet files.

Parameters

Name	Type	Default	Description
`graph_dir`	str \| PathLike	-	the folder where the graph will be persisted as parquet

Returns

Type	Description
None

update_metadata

Signature: update_metadata(metadata)

Updates static properties to the graph.

Parameters

Name	Type	Default	Description
`metadata`	PropInput	-	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.

write_updates

Persist the new updates by appending them to the cache file.

Returns

Type	Description
None