GQL Support Implementation

[danielhmills]

Summary

Implements GQL query support in Virtuoso by translating GQL to SPARQL, built on top of the merged develop/7 upstream (RDF 1.2/RDF-star, OpenSSL 3 modernization, zlib 1.3.2, delta_sharing plugin, SQL optimizer fixes).

• 140 commits on top of develop/7 (105 files changed, ~50k insertions)
• Merges 61 upstream commits from danielhmills/develop/7 with all 6 predicted conflicts resolved
• Removes the standalone openCypher plugin/endpoint while preserving shared GQL infrastructure (the OPENCYPHER_L SQL token mapping is retained as the shared lexer entry point)

Core GQL implementation (libsrc/Wi/gql_*.sql)

14 new server-bootstrap SQL modules implementing a full GQL→SPARQL translator:

Module	Responsibility
gql_lexer.sql	GQL tokenizer
gql_parser.sql	GQL parser (MATCH, RETURN, WHERE, ORDER BY, LIMIT, SKIP, set ops, DDL)
gql_expr.sql	Expression evaluation (arithmetic, string, logical, path)
gql_translate.sql	AST → SPARQL translation, context/alias management
gql_sparql_gen.sql	SPARQL SELECT/ASK/CONSTRUCT generation, WHERE emission
gql_plan.sql	Query planning and optimization passes
gql_var_pass.sql	Variable binding and scoping pass
gql_runtime.sql	Runtime execution via GQL_RUN / OPENGQL_EXEC
gql_pg_ddl.sql	CREATE/DROP VIRTUAL & PHYSICAL PROPERTY GRAPH DDL
gql_pl.sql	Virtuoso/PL functions with no native BIF (hyperbolic, duration, etc.)
gql_main.sql	Entry point, USE PROPERTY GRAPH scoping
gql_endpoint.sql	/sparql and openGQL HTTP endpoint integration
gql_stats.sql	Observability — stats, timing, EXPLAIN
gql_bootstrap.sql	Server bootstrap loader

Key features

• GQL MATCH/RETURN with node/edge labels, property access, AS aliases
• Path patterns: SHORTEST, SHORTEST k GROUPS (k=1..n), transitive closure
• Set operations: UNION, EXCEPT, INTERSECT
• DML: INSERT INTO GRAPH, DELETE, SET (atomic multi-statement, parameter binding)
• Property graph DDL: CREATE/DROP VIRTUAL PROPERTY GRAPH (quad-map over relational tables) and CREATE/DROP PHYSICAL PROPERTY GRAPH (materialized from tables)
• USE PROPERTY GRAPH with per-graph IRI scheme and home-property-graph mode
• RDF 1.2 / RDF-star syntax: <<(...)>>, <<...>>, ~ reifier for edge properties
• Per-graph namespace scheme: node/edge IRIs minted under gql/data, vocabulary under gql/ontology
• Observability: EXPLAIN, timing stats, query logging
• C plugin (binsrc/hosting/gqlc/): ICU-based GQL_NORMALIZE, GQL_IS_NORMALIZED, GQL_PERCENTILE_CONT, GQL_PERCENTILE_DISC

Tests

• 18 new test files in binsrc/tests/suite/ (test_gql_.sql, tgql_.sh) + unit tests in binsrc/gql/
• TCK (Technology Compatibility Kit) extraction/runner scripts in binsrc/gql/tck/

VAD packaging

• binsrc/gql/vad/ — openGQL VAD package with install/uninstall scripts and mirrored vad/data/ copies

Build system

• libsrc/Wi/Makefile.am — GQL modules compiled into server bootstrap
• binsrc/hosting/gqlc/Makefile.am — gqlc C plugin
• binsrc/ws/delta_sharing/Makefile.am — delta_sharing plugin (from upstream)

Test plan

• make -j4 builds cleanly (macOS Apple Silicon, OpenSSL 3.6.2)
• make check — full test suite: 9,922 passed, 0 failed, 0 aborted
• TPC-D: 56 + 90 passed, 0 failed
• tgraphql: 82 passed, 0 failed
• tgql_unit: 21 passed (GQL observability + unit tests)
• tgql_rdf_equiv: 14 passed, 0 failed
• SHORTEST k GROUPS: k=1, k=2, k=10 + translation checks pass
• Runtime: DB.DBA.GQL_TO_SPARQL_PARAMS translates GQL MATCH to SPARQL correctly
• Runtime: GraphQL plugin loads (GraphQL/SPARQL Bridge version 0.9.3)
• Runtime: RDF-star quoted-triple INSERT + QUERY works
• All new source files have OpenLink GPL v2 license headers
• No AI-tool directories (.claude, .windsurf, etc.) or LLM prompt files in tree or history
• No local directory paths in commit messages

Generated with Devin

[imitko]

The gql_to_sparql() may return incorrect SPARQL, example:

select gql_to_sparql('MATCH (p:Person)-[:studyAt]->(u:University) return p.name as ?n')

The AS ?n is not tested valid name and SPARQL generated:

.... SELECT (?prop_1 AS ??n) ... 

[danielhmills]

Thanks for catching this. The issue is fixed in commit 006a58a on this branch.

Root cause was two-fold:

1. Parser (gql_parser.sql): The RETURN item parser took the raw token value after AS without checking the token type. When the alias was a ?n or $n parameter token, the prefix was retained in the AST, and downstream emission code unconditionally prepended ?, producing ??n.

2. Translator (gql_translate.sql): The PARAM handler in GQL_GEN_EXPR only stripped the $ prefix (char 36) from parameter names, not ? (char 63). So ?n appearing in ORDER BY (parsed as a PARAM node) also produced ??n.

Fix:

• The parser now normalizes the alias token after AS based on token type: IDENT is used as-is, PARAM (?name/$name) has the prefix stripped, `name` (accent-quoted) has backticks stripped, and keyword tokens (e.g. AS node) are accepted as-is. Other token types raise GQ003.
• The PARAM handler now strips both ? and $ prefixes.

This means all of the following now produce (?prop_1 AS ?n):

RETURN p.name AS ?n
RETURN p.name AS $n
RETURN p.name AS `n`
RETURN p.name AS n

And ORDER BY ?n now produces ORDER BY ASC(?n) instead of ORDER BY ASC(??n).

Four regression tests (TR175–TR178) were added to test_gql_translate.sql covering these cases. The full test suite passes (9922 tests, 0 failures).