topologicpy.GraphDB module

class topologicpy.GraphDB.GraphDB

Bases: object

A provider-neutral dispatcher for graph database backends.

GraphDB is intentionally lightweight. It does not implement graph database logic itself. Instead, it stores a provider name and a backend manager, then dispatches calls to the corresponding TopologicPy database class, currently Kuzu or Neo4j.

The expected usage pattern is:

from topologicpy.GraphDB import GraphDB from topologicpy.Kuzu import Kuzu

manager = Kuzu.Manager(“my_db”) graphdb = GraphDB.ByParameters(provider=”kuzu”, manager=manager)

GraphDB.EnsureSchema(graphdb) GraphDB.UpsertGraph(graphdb, graph, graphIDKey=”graph_id”,

vertexIDKey=”node_id”, vertexLabelKey=”label”)

For Neo4j:

from topologicpy.GraphDB import GraphDB from topologicpy.Neo4j import Neo4j

driver = Neo4j.Connect(url, username, password) graphdb = GraphDB.ByParameters(provider=”neo4j”, manager=driver,

database=”neo4j”)

GraphDB.EnsureSchema(graphdb)

Methods

ByCSVPath(graphdb, path[, graphIDHeader, ...])	Reads CSV graph data and upserts all returned graphs into the selected backend.
ByParameters(provider[, manager, database, ...])	Creates a provider-neutral graph database descriptor.
CandidateCountsForLabels(graphdb, labels[, ...])	Returns likely candidate labels connected to the input labels.
Database(graphdb[, silent])	Returns the database name stored in the input graph database descriptor.
DeleteGraph(graphdb, graphID[, silent])	Deletes a graph by id from the selected backend.
EmptyDatabase(graphdb[, dropSchema, ...])	Empties the selected backend database.
EnsureSchema(graphdb[, silent])	Ensures that the backend-specific schema/indexes exist.
Execute(graphdb, query[, parameters, write, ...])	Executes a backend query and returns raw backend rows where supported.
FetchAllPairs(graphdb[, undirected, silent])	Returns all label-pair counts from the selected backend.
FindBestExampleForLabel(graphdb, label[, ...])	Returns a representative database example for the input label.
GraphByID(graphdb, graphID[, ontology, silent])	Constructs a TopologicPy graph from the selected backend using a graph id.
GraphsByQuery(graphdb, query[, parameters, ...])	Executes a backend query and returns matching TopologicPy graphs.
ListGraphs(graphdb[, where, limit, offset, ...])	Lists graph metadata from the selected backend.
Manager(graphdb[, silent])	Returns the backend-specific manager stored in the input graph database descriptor.
MaxNeighborsForLabel(graphdb, label[, silent])	Returns the maximum observed neighbour count for vertices with the input label.
OntologyKeys()	Returns the canonical ontology-related dictionary keys that should be preserved by graph database backends.
Options(graphdb[, silent])	Returns the options dictionary stored in the input graph database descriptor.
Provider(graphdb[, silent])	Returns the provider string stored in the input graph database descriptor.
Query(graphdb, query[, parameters, silent])	Executes a read query against the selected backend.
UpsertGraph(graphdb, graph[, graphIDKey, ...])	Upserts a TopologicPy graph into the selected backend.
VerticesByCategory(graphdb, category[, ...])	Returns backend rows for vertices/nodes with the requested category.
VerticesByOntologyClass(graphdb, ontologyClass)	Returns backend rows for vertices/nodes with the requested ontology class.

static ByCSVPath(graphdb, path, graphIDHeader='graph_id', graphLabelHeader='label', graphFeaturesHeader='feat', graphFeaturesKeys=None, edgeSRCHeader='src_id', edgeDSTHeader='dst_id', edgeLabelHeader='label', edgeTrainMaskHeader='train_mask', edgeValidateMaskHeader='val_mask', edgeTestMaskHeader='test_mask', edgeFeaturesHeader='feat', edgeFeaturesKeys=None, nodeIDHeader='node_id', nodeLabelHeader='label', nodeTrainMaskHeader='train_mask', nodeValidateMaskHeader='val_mask', nodeTestMaskHeader='test_mask', nodeFeaturesHeader='feat', nodeXHeader='X', nodeYHeader='Y', nodeZHeader='Z', nodeFeaturesKeys=None, tolerance=0.0001, ontology: bool = True, silent=False)

Reads CSV graph data and upserts all returned graphs into the selected backend.

The signature mirrors the TopologicPy CSV graph import/export format and the backend-specific ByCSVPath methods in Kuzu and Neo4j.

Parameters

graphdbdict

The graph database descriptor.

pathstr

The CSV dataset path.

graphIDHeaderstr , optional

The graph id column/header. Default is “graph_id”.

graphLabelHeaderstr , optional

The graph label column/header. Default is “label”.

graphFeaturesHeaderstr , optional

The graph features prefix/header. Default is “feat”.

graphFeaturesKeyslist , optional

Optional graph feature keys. Default is None.

edgeSRCHeaderstr , optional

The edge source id column/header. Default is “src_id”.

edgeDSTHeaderstr , optional

The edge destination id column/header. Default is “dst_id”.

edgeLabelHeaderstr , optional

The edge label column/header. Default is “label”.

edgeTrainMaskHeaderstr , optional

The edge train mask column/header. Default is “train_mask”.

edgeValidateMaskHeaderstr , optional

The edge validation mask column/header. Default is “val_mask”.

edgeTestMaskHeaderstr , optional

The edge test mask column/header. Default is “test_mask”.

edgeFeaturesHeaderstr , optional

The edge features prefix/header. Default is “feat”.

edgeFeaturesKeyslist , optional

Optional edge feature keys. Default is None.

nodeIDHeaderstr , optional

The node id column/header. Default is “node_id”.

nodeLabelHeaderstr , optional

The node label column/header. Default is “label”.

nodeTrainMaskHeaderstr , optional

The node train mask column/header. Default is “train_mask”.

nodeValidateMaskHeaderstr , optional

The node validation mask column/header. Default is “val_mask”.

nodeTestMaskHeaderstr , optional

The node test mask column/header. Default is “test_mask”.

nodeFeaturesHeaderstr , optional

The node features prefix/header. Default is “feat”.

nodeXHeaderstr , optional

The node X-coordinate column/header. Default is “X”.

nodeYHeaderstr , optional

The node Y-coordinate column/header. Default is “Y”.

nodeZHeaderstr , optional

The node Z-coordinate column/header. Default is “Z”.

nodeFeaturesKeyslist , optional

Optional node feature keys. Default is None.

tolerancefloat , optional

The tolerance passed to the backend CSV importer. Default is 0.0001.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

A dictionary containing the number of upserted graphs and their ids.

static ByParameters(provider: str, manager=None, database: str = None, options: dict = None, silent: bool = False) → dict

Creates a provider-neutral graph database descriptor.

Parameters

providerstr

The backend provider name. Supported values are “kuzu”, “neo4j”, and “ladybugdb”.

managerobject , optional

The backend-specific manager. For Kuzu, this is usually the object returned by Kuzu.Manager(…). For Neo4j, this is usually the driver returned by Neo4j.Connect(…).

databasestr , optional

Optional database name. This is mainly used by Neo4j. Default is None.

optionsdict , optional

Optional provider-specific settings. Default is None.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

A graph database descriptor, or None on error.

static CandidateCountsForLabels(graphdb, labels, excludeLabels=None, limit: int = 50, silent: bool = False)

Returns likely candidate labels connected to the input labels.

Parameters

graphdbdict

The graph database descriptor.

labelslist

The input labels.

excludeLabelslist , optional

Labels to exclude from candidates. Default is None.

limitint , optional

Maximum number of candidates to return. Default is 50.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

A list of candidate label dictionaries.

static Database(graphdb, silent: bool = False)

Returns the database name stored in the input graph database descriptor.

Parameters

graphdbdict

The input graph database descriptor.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

str

The database name, or None.

static DeleteGraph(graphdb, graphID: str, silent: bool = False) → bool

Deletes a graph by id from the selected backend.

Parameters

graphdbdict

The graph database descriptor.

graphIDstr

The graph id to delete.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

bool

True on success, False otherwise.

static EmptyDatabase(graphdb, dropSchema: bool = False, recreateSchema: bool = True, silent: bool = False) → bool

Empties the selected backend database.

Parameters

graphdbdict

The graph database descriptor.

dropSchemabool , optional

If True, drops the schema where the backend supports it. Default is False.

recreateSchemabool , optional

If True and dropSchema is True, recreates schema afterwards. Default is True.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

bool

True on success, False otherwise.

static EnsureSchema(graphdb, silent: bool = False) → bool

Ensures that the backend-specific schema/indexes exist.

Parameters

graphdbdict

The graph database descriptor.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

bool

True if successful, False otherwise.

static Execute(graphdb, query: str, parameters: dict = None, write: bool = False, silent: bool = False)

Executes a backend query and returns raw backend rows where supported.

Parameters

graphdbdict

The graph database descriptor.

querystr

The query to execute.

parametersdict , optional

Query parameters. Default is None.

writebool , optional

If True, executes a write query. Default is False.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

Backend-normalized result rows, or None on error.

static FetchAllPairs(graphdb, undirected: bool = True, silent: bool = False)

Returns all label-pair counts from the selected backend.

Parameters

graphdbdict

The graph database descriptor.

undirectedbool , optional

If True, normalizes direction so A-B and B-A are counted together. Default is True.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

A list of dictionaries describing label pairs and counts.

static FindBestExampleForLabel(graphdb, label, attachTo=None, silent: bool = False)

Returns a representative database example for the input label.

Parameters

graphdbdict

The graph database descriptor.

labelstr

The input vertex label.

attachTostr , optional

Optional label of the node to which the candidate is expected to attach. Default is None.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

A representative example dictionary, or None on error.

static GraphByID(graphdb, graphID: str, ontology: bool = True, silent: bool = False)

Constructs a TopologicPy graph from the selected backend using a graph id.

Parameters

graphdbdict

The graph database descriptor.

graphIDstr

The graph id to retrieve.

ontologybool , optional

If True, annotates the returned graph with TopologicPy ontology classes where missing. Default is True.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

topologic_core.Graph or topologicpy.TGraph

A TopologicPy Graph or TGraph, or None on error.

static GraphsByQuery(graphdb, query: str, parameters: dict = None, ontology: bool = True, silent: bool = False)

Executes a backend query and returns matching TopologicPy graphs.

Parameters

graphdbdict

The graph database descriptor.

querystr

The backend query string. For Kuzu and Neo4j this is Cypher.

parametersdict , optional

Query parameters. Default is None.

ontologybool , optional

If True, annotates the returned graphs with TopologicPy ontology classes where missing. Default is True.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

A list of TopologicPy graphs, or None on error.

static ListGraphs(graphdb, where: dict = None, limit: int = 100, offset: int = 0, silent: bool = False)

Lists graph metadata from the selected backend.

Parameters

graphdbdict

The graph database descriptor.

wheredict , optional

Simple backend-supported filters. Default is None.

limitint , optional

Maximum number of records to return. Default is 100.

offsetint , optional

Number of records to skip. Default is 0.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

A list of graph metadata dictionaries, or None on error.

static Manager(graphdb, silent: bool = False)

Returns the backend-specific manager stored in the input graph database descriptor.

Parameters

graphdbdict

The input graph database descriptor.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

object

The backend manager, or None on error.

static MaxNeighborsForLabel(graphdb, label, silent: bool = False)

Returns the maximum observed neighbour count for vertices with the input label.

Parameters

graphdbdict

The graph database descriptor.

labelstr

The input vertex label.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

int

The maximum neighbour count, or None on error.

static OntologyKeys() → list

Returns the canonical ontology-related dictionary keys that should be preserved by graph database backends.

Returns

list

The list of ontology-related dictionary keys.

static Options(graphdb, silent: bool = False)

Returns the options dictionary stored in the input graph database descriptor.

Parameters

graphdbdict

The input graph database descriptor.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

dict

The options dictionary, or None on error.

static Provider(graphdb, silent: bool = False)

Returns the provider string stored in the input graph database descriptor.

Parameters

graphdbdict

The input graph database descriptor.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

str

The provider string, or None on error.

static Query(graphdb, query: str, parameters: dict = None, silent: bool = False)

Executes a read query against the selected backend.

Parameters

graphdbdict

The graph database descriptor.

querystr

The query to execute.

parametersdict , optional

Query parameters. Default is None.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

Backend-normalized result rows, or None on error.

static UpsertGraph(graphdb, graph, graphIDKey: str = 'graph_id', vertexIDKey: str = 'id', vertexLabelKey: str = 'label', defaultVertexLabel: str = 'Node', vertexCategoryKey: str = 'category', defaultVertexCategory: str = 'Node', edgeLabelKey: str = 'label', defaultEdgeLabel: str = 'CONNECTED_TO', edgeCategoryKey: str = 'category', defaultEdgeCategory: str = 'Edge', bidirectional: bool = True, overwrite: bool = False, mantissa: int = 6, ontology: bool = True, ontologyGraphClass: str = 'top:Graph', ontologyVertexClass: str = 'top:Node', ontologyEdgeClass: str = 'top:Relationship', silent: bool = False) → str

Upserts a TopologicPy graph into the selected backend.

Parameters

graphdbdict

The graph database descriptor. See GraphDB.ByParameters(…).

graphtopologic_core.Graph or topologicpy.TGraph

The graph to be upserted.

graphIDKeystr , optional

The dictionary key used to retrieve the graph id. Default is “graph_id”.

vertexIDKeystr , optional

The dictionary key used to retrieve each vertex id. Default is “id”.

vertexLabelKeystr , optional

The dictionary key used to retrieve each vertex label. Default is “label”.

defaultVertexLabelstr , optional

The default vertex label to use if no vertex label is found. Default is “Node”.

vertexCategoryKeystr , optional

The dictionary key used to retrieve each vertex category. Default is “category”.

defaultVertexCategorystr , optional

The default vertex category to use if no vertex category is found. Default is “Node”.

edgeLabelKeystr , optional

The dictionary key used to retrieve each edge label. Default is “label”.

defaultEdgeLabelstr , optional

The default edge label to use if no edge label is found. Default is “CONNECTED_TO”.

edgeCategoryKeystr , optional

The dictionary key used to retrieve each edge category. Default is “category”.

defaultEdgeCategorystr , optional

The default edge category to use if no edge category is found. Default is “Edge”.

bidirectionalbool , optional

If set to True, edges are written bidirectionally where supported by the backend. Default is True.

overwritebool , optional

If set to True, an existing graph with the same graph id is overwritten where supported by the backend. Default is False.

mantissaint , optional

The number of decimal places to use when extracting coordinate data. Default is 6.

ontologybool , optional

If True, annotates the graph, vertices, and edges with TopologicPy ontology classes before upserting. Default is True.

ontologyGraphClassstr , optional

The ontology class assigned to the graph if none exists. Default is “top:Graph”.

ontologyVertexClassstr , optional

The ontology class assigned to vertices if none exists. Default is “top:Node”.

ontologyEdgeClassstr , optional

The ontology class assigned to edges if none exists. Default is “top:Relationship”.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

str

The graph id used, or None on error.

static VerticesByCategory(graphdb, category: str, limit: int = 100, silent: bool = False)

Returns backend rows for vertices/nodes with the requested category.

Parameters

graphdbdict

The graph database descriptor.

categorystr

The requested category, for example “space”, “node”, or “element”.

limitint , optional

Maximum number of rows to return. Default is 100.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

Backend-normalized rows, or None on error.

static VerticesByOntologyClass(graphdb, ontologyClass: str, limit: int = 100, silent: bool = False)

Returns backend rows for vertices/nodes with the requested ontology class.

Parameters

graphdbdict

The graph database descriptor.

ontologyClassstr

The requested ontology class, for example “top:Room”.

limitint , optional

Maximum number of rows to return. Default is 100.

silentbool , optional

If set to True, error and warning messages are suppressed. Default is False.

Returns

list

Backend-normalized rows, or None on error.