arango-sparql-py: Skill for Cursor

SPARQL → AQL Porting

This skill is the deterministic recipe for adding or fixing a SPARQL construct in arango-sparql-py. It exists because the translation behavior is non-obvious and must match the legacy Foxx service's semantics — never invented from scratch.

Inputs you will work with

• Legacy source of truth: references/arango-sparql/src/lib/
  • aql-translator.js — top-level dispatch by query type.
  • pgt-translator.js — Property Graph Topology translation rules.
  • rpt-translator.js — RDF Property Triple translation rules.
  • filter-translator.js — FILTER → AQL boolean expression mapping.
  • triple-constructor.js — CONSTRUCT clause helpers.
  • aql-query-builder.js — fluent AQL builder API to mimic.
  • uri-resolver.js, uri-hasher.js — URI ↔ collection/key mapping.
• Python target: arango_sparql/translate/
  • parser.py — wraps rdflib.plugins.sparql.parser.parseQuery + algebra.translateQuery.
  • visitor.py — the Algebra visitor (one visit_<NodeType> per Algebra op).
  • builder.py — the parameterized AQL builder.
  • resolver.py — SchemaResolver over the in-memory OWL graph.
  • errors.py — SparqlError hierarchy.

Workflow

Copy this checklist into your scratchpad and tick items as you go:

Task progress:
- [ ] 1. Identify the SPARQL construct and its Algebra node name
- [ ] 2. Read the legacy JS translator for that construct
- [ ] 3. Locate (or create) the visitor method
- [ ] 4. Implement using the AQL builder (no string concat)
- [ ] 5. Add a golden test
- [ ] 6. Add a pyoxigraph cross-validation test (when applicable)
- [ ] 7. Run pytest and ruff

1. Identify the Algebra node

Run this in a scratch shell or a unit test to see the exact Algebra node name rdflib produces for your SPARQL fragment:

from rdflib.plugins.sparql.parser import parseQuery
from rdflib.plugins.sparql.algebra import translateQuery
print(translateQuery(parseQuery("SELECT ?s WHERE { ?s ?p ?o OPTIONAL { ?s :name ?n } }")).algebra)