feat: add optional Grafeo graph database export

[StevenBtw]

Summary

Adds an optional "Push to Grafeo" export that materializes the current ontology as a live, queryable property graph, complementing the existing Fabric IQ export path with a local development backend.

• src/lib/grafeo.ts: pure-function ontology-to-query converter + thin REST client (~130 LOC)
• src/lib/grafeo.test.ts: 7 unit tests covering conversion, edge cases, and escaping
• src/components/GrafeoExportModal.tsx: connection modal following the existing Fabric export pattern
• Feature-flagged via VITE_ENABLE_GRAFEO_EXPORT (default: false); zero impact when disabled

Motivation: accelerating the Fabric IQ design loop

Ontology Playground is a design and learning tool for Microsoft Fabric IQ: users build ontologies that ultimately power Fabric's natural-language query engine. Today the workflow is:

Design (Playground) → Push (Fabric REST API) → Bind to data (OneLake / Power BI) → Query (IQ)

The gap is between steps 1 and 2: there's no way to validate an ontology as a live graph before pushing to Fabric. Designers either push incomplete ontologies to iterate, or reason about structure purely visually.

Grafeo fills this gap as a lightweight local backend:

Design (Playground) → Validate locally (Grafeo) → Push to production (Fabric IQ)

Entity types become queryable nodes, relationships become typed edges. Designers can verify structure, trace join paths, and test cardinality, all locally, before touching Fabric.

Why Grafeo fits

Grafeo is an open-source (Apache-2.0), lightweight graph database built on the same open standards that Fabric IQ and the Playground already use:

Standard	Spec	How it connects
GQL	ISO/IEC 39075	The ISO standard query language for property graphs; the model Fabric ontologies describe
SPARQL	W3C Rec	Direct match for the RDF/OWL format the Playground already produces and exports
SQL/PGQ	ISO 9075:2023	SQL property graph extensions; bridges graph and relational worlds, like Fabric does
Cypher	openCypher	Widely adopted, natural fit for CREATE/MATCH patterns over ontology schemas

Grafeo ships as a single ~7 MB binary: no JVM, no cluster, no cloud account required. Users can spin it up locally alongside the Playground for immediate ontology validation, then push to Fabric when ready.

How it works

1. Entity types become labeled nodes with metadata (description, icon, color, properties)
2. Relationships become typed directed edges with cardinality annotations
3. The generated query is POST'd to Grafeo's /query REST endpoint
4. The graph is immediately queryable with GQL, Cypher, SPARQL, Gremlin, GraphQL, or SQL

Test plan

• npm run build passes (TypeScript + Vite)
• npm test passes: 259 tests (252 existing + 7 new), 0 failures
• Feature disabled by default (VITE_ENABLE_GRAFEO_EXPORT=false); no UI change
• When enabled, "Push to Grafeo" button appears in Import/Export modal
• Manual test: push sample ontology to local Grafeo instance, verify nodes/edges created
• Verify no regressions in existing Fabric export flow

[StevenBtw]

@microsoft-github-policy-service agree

[videlalvaro]

Thanks for the contribution. Does Grafeo supports pushing to Fabric or how does it work on this setup? Do you deploy the playground locally, and push to grafeo there?

[StevenBtw]

Thanks @videlalvaro! No, Grafeo doesn't push to Fabric (yet) but the two are complementary, not a replacement. Grafeo sits before Fabric in the loop:

Design (Playground) → Validate locally (Grafeo) → Push to production (Fabric IQ)

The typical setup is fully local (but would work wherever you run the Playground):

1. Run Grafeo as a local binary (~7 MB, single executable, no JVM/cluster) and it listens on http://localhost:7474 by default.
2. Run the Playground (locally via npm run dev, or wherever you normally run it) with VITE_ENABLE_GRAFEO_EXPORT=true.
3. The new "Push to Grafeo" button in the Import/Export modal POSTs the ontology as Cypher to Grafeo's /query REST endpoint. Entity types become labeled nodes, relationships become typed edges.
4. You can then query that graph locally with GQL / Cypher / SPARQL / etc. to validate structure, trace join paths, and test cardinality before pushing to Fabric.

The existing Fabric export path is completely untouched, this just adds an optional second target for fast local iteration. The whole feature is gated behind VITE_ENABLE_GRAFEO_EXPORT (default false), so it's a no-op unless explicitly enabled.

[videlalvaro]

Hi @StevenBtw — the code looks great and merges cleanly. One small question before we land it: pingGrafeo currently verifies connectivity by sending POST /query with RETURN 1. Does Grafeo expose a dedicated health/status endpoint (e.g. GET /health or GET /status)? Using that would avoid creating an unnecessary graph transaction on connect. If not, the current approach is fine — just want to confirm before merging.