topologicpy.GQL module

class topologicpy.GQL.GQL

Bases: object

Convenience API for parsing and executing GQL-like queries.

Methods

`Mutate`(graph, query[, ontology, ...])	Alias for Query, intended for CREATE, MERGE, SET, and DELETE queries.
`NormalizeOntologyLabels`(query[, ...])	Normalises ontology labels in a GQL-like query.
`OntologyTerms`(result[, ontologyClassKey, ...])	Extracts ontology-related terms from query results.
`Query`(graph, query[, ontology, ...])	Parses and executes a GQL-like query.
`TGraph`(graph[, ontology, ontologyClass, ...])	Returns a TGraph from a TGraph or GQL working graph.
`TopologicGraph`(graph[, ontology, ...])	Compatibility alias for `GQL.TGraph`.

CATEGORY_KEY = 'category'

DEFAULT_EDGE_ONTOLOGY_CLASS = 'top:Relationship'

DEFAULT_GRAPH_ONTOLOGY_CLASS = 'top:Graph'

DEFAULT_NODE_ONTOLOGY_CLASS = 'top:Node'

GENERATED_BY_KEY = 'generated_by'

LABEL_KEY = 'label'

static Mutate(graph, query: str, ontology: bool = True, normalizeOntologyLabels: bool = True, ontologyLabelMode: str = 'label', silent: bool = False)

Alias for Query, intended for CREATE, MERGE, SET, and DELETE queries.

Parameters

graphtopologicpy.TGraph or dict: The input TGraph or GQL working graph.
querystr: The GQL-like mutation query.
ontologybool , optional: If True, ontology metadata is preserved and graph outputs are annotated where possible. Default is True.
normalizeOntologyLabelsbool , optional: If True, normalises top: labels before parsing. Default is True.
ontologyLabelModestr , optional: Ontology label normalisation mode. Default is "label".
silentbool , optional: Suppress warnings/errors. Default is False.

Returns

list or dict or None: The mutation result, or None.

static NormalizeOntologyLabels(query: str, ontologyClassKey: str = 'ontology_class', labelKey: str = 'label', mode: str = 'label', silent: bool = False) → str

Normalises ontology labels in a GQL-like query.

Many simple GQL parsers treat labels as single identifiers and cannot parse :top:Room. This helper converts ontology-prefixed labels to a parser-safe form.

Parameters

querystr

The input GQL-like query string.

ontologyClassKeystr , optional

The dictionary key used for ontology class metadata. Default is "ontology_class".

labelKeystr , optional

The dictionary key used for ordinary labels. Default is "label".

modestr , optional

Supported values:

"none": return query unchanged.
"label": replace :top:Room with :Room.
"where": replace :top:Room with no label and append a best-effort WHERE clause is intentionally not attempted because the parser grammar may vary.

Default is "label".

silentbool , optional

If True, suppress warning messages. Default is False.

Returns

str: The normalised query string.

ONTOLOGY_CLASS_KEY = 'ontology_class'

ONTOLOGY_NAMESPACE = 'http://w3id.org/topologicpy/#'

ONTOLOGY_NAMESPACES = ['http://w3id.org/topologicpy/#', 'http://w3id.org/topologicpy#']

ONTOLOGY_PREFIX = 'top'

ONTOLOGY_URI_KEY = 'uri'

static OntologyTerms(result, ontologyClassKey: str = 'ontology_class', categoryKey: str = 'category', labelKey: str = 'label', silent: bool = False)

Extracts ontology-related terms from query results.

Parameters

resultany: A GQL query result, mutation result, graph, row list, or row dict.
ontologyClassKeystr , optional: The dictionary key that stores ontology classes.
categoryKeystr , optional: The dictionary key that stores categories.
labelKeystr , optional: The dictionary key that stores labels.
silentbool , optional: If True, suppress warnings.

Returns

dict: A dictionary containing unique ontology classes, categories, and labels.

static Query(graph, query: str, ontology: bool = True, normalizeOntologyLabels: bool = True, ontologyLabelMode: str = 'label', silent: bool = False)

Parses and executes a GQL-like query.

The executor accepts either a TopologicPy TGraph or the internal GQL working graph returned by a previous mutation. For best performance, continue passing the returned result["graph"] between mutation and read queries. Convert back to a TopologicPy TGraph only when needed by calling GQL.TGraph(...).

Parameters

graphtopologicpy.TGraph or dict: The input TGraph or GQL working graph.
querystr: The GQL-like query string to parse and execute.
ontologybool , optional: If set to True, GQL annotates returned TopologicPy TGraphs with ontology metadata where possible and preserves ontology dictionaries in result rows. Default is True.
normalizeOntologyLabelsbool , optional: If set to True, parser-hostile labels such as :top:Room are normalised to :Room before parsing. Default is True.
ontologyLabelModestr , optional: The normalisation mode passed to GQL.NormalizeOntologyLabels. Default is "label".
silentbool , optional: If set to True, error and warning messages are suppressed. Default is False.

Returns

list or dict or None: The query result, mutation result, or None if parsing/execution fails.

static TGraph(graph, ontology: bool = True, ontologyClass: str = 'top:Graph', generatedBy: str = 'GQL.TGraph', silent: bool = False)

Returns a TGraph from a TGraph or GQL working graph.

Parameters

graphtopologicpy.TGraph or dict: The input TGraph or GQL working graph.
ontologybool , optional: If True, the returned TGraph is annotated with ontology metadata. Default is True.
ontologyClassstr , optional: The ontology class assigned to the returned TGraph when missing. Default is "top:Graph".
generatedBystr , optional: The value stored under generated_by when missing. Default is "GQL.TGraph".
silentbool , optional: Suppress warnings/errors. Default is False.

Returns

topologicpy.TGraph: The returned TGraph, or None.

static TopologicGraph(graph, ontology: bool = True, ontologyClass: str = 'top:Graph', generatedBy: str = 'GQL.TopologicGraph', silent: bool = False)

Compatibility alias for GQL.TGraph.

Parameters

graphtopologicpy.TGraph or dict: The input TGraph or GQL working graph.
ontologybool , optional: If True, the returned TGraph is annotated with ontology metadata. Default is True.
ontologyClassstr , optional: The ontology class assigned to the returned TGraph when missing. Default is "top:Graph".
generatedBystr , optional: The value stored under generated_by when missing. Default is "GQL.TopologicGraph".
silentbool , optional: Suppress warnings/errors. Default is False.

Returns

topologicpy.TGraph: The returned TGraph, or None.