topologicpy.GQL module

Convenience wrapper for the TopologicPy GQL pipeline.

This module lives at topologicpy/GQL.py so it can be imported like the other TopologicPy classes:

from topologicpy.GQL import GQL

The parser and executor implementation live in the lowercase internal package topologicpy/gql.

Read queries return list[dict]. Mutation queries return a dictionary containing at least the updated graph or GQL working graph and projected rows.

Ontology support

This wrapper preserves TopologicPy ontology metadata during GQL execution and conversion. It does not make ontology mandatory inside the internal parser or executor. Instead, it provides a lightweight compatibility layer:

  • ontology=True annotates TopologicPy graph results where possible.

  • top:Class query labels can be normalised to parser-safe labels when normalizeOntologyLabels=True.

  • Query results can be enriched with ontology metadata copied from returned graph elements or working-graph dictionaries.

  • Returned TopologicPy graphs can be annotated with top:Graph.

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.

TopologicGraph(graph[, ontology, ...])

Returns a TopologicPy Graph from a TopologicPy graph or GQL working graph.
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
graphtopologic_core.Graph or dict

The input TopologicPy graph 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_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 graph 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 graph only when needed by calling GQL.TopologicGraph(...).

Parameters
graphtopologic_core.Graph or dict

The input TopologicPy graph or GQL working graph.

querystr

The GQL-like query string to parse and execute.

ontologybool , optional

If set to True, GQL annotates returned TopologicPy graphs 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 TopologicGraph(graph, ontology: bool = True, ontologyClass: str = 'top:Graph', generatedBy: str = 'GQL.TopologicGraph', silent: bool = False)

Returns a TopologicPy Graph from a TopologicPy graph or GQL working graph.

Parameters
graphtopologic_core.Graph or dict

The input TopologicPy graph or GQL working graph.

ontologybool , optional

If True, the returned graph is annotated with ontology metadata. Default is True.

ontologyClassstr , optional

The ontology class assigned to the returned graph 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
topologic_core.Graph

The returned TopologicPy Graph, or None.