Skip to content

fix(ui): show TripleTrail's plan in MatGUI's Explain tab - #67

Merged
MathiasVDA merged 6 commits into
mainfrom
claude/project-thread-uprney
Nov 20, 2026
Merged

MathiasVDA merged 6 commits into
mainfrom
claude/project-thread-uprney

Conversation

@MathiasVDA

@MathiasVDA MathiasVDA commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

What and why

On the Query page, MatGUI's Explain tab of the results showed no plan and said "No engine recognised for this endpoint". The MatGUI 6.13.0 explain plugin only knows QLever, GraphDB, Stardog, Blazegraph and Neptune (detected from the Server header or the URL), and there is no hook to add an engine from outside the bundle. The server's /{ds}/explain itself was fine.

The Query page now subclasses MatGUI's Explain plugin after MatGUI loads and registers it under the same name:

  • resolveEngine: when the plugin finds no engine and the endpoint is this server's own …/sparql or …/query (a dataset or a Workbench workspace), it uses a TripleTrail engine, shown as "Detect (TripleTrail)" in the Engine list. A stored or forced engine choice still wins.
  • runRequest: POSTs the query to …/explain as application/sparql-query with the admin token and the view-as headers (as the query itself is sent).
  • parse: maps plan.plan (name, number of results, duration in seconds, children) to the plugin's tree, with the row count, planning time and spatial decisions as the summary. A restricted caller (row count only) gets a short text instead of a tree.

It works the same with --matgui-url pointing at the CDN build, since it only relies on Yasgui.Yasr.plugins.Explain. The Explain button above MatGUI is unchanged.

Also in this PR:

  • Server: TripleTrail/<version> on every answer (it said tiny-http (Rust)), and --cors exposes it. The Explain plugin's new TripleTrail engine (feat: add TripleTrail as an engine yasgui-explain-plugin#9) recognises the server by this header, so MatGUI on any host can find the plan once a plugin release with that engine is bundled (not yet). Until then, the Query page's own registration above covers the built-in UI.

How it was tested

  • New tests/admin.rs::the_query_page_explain_view_reads_the_plan_of_this_server: the served app.js wires the engine, and /{ds}/explain answers the request the view sends with the fields it reads, for every step of the plan.
  • Checked in Chromium (Playwright) against a local server: after running a query, the Explain tab shows "Detect (TripleTrail)", the operation count, and the plan tree with rows and ms; choosing QLever in the Engine list still overrides it.
  • The admin test also checks that the Server header names TripleTrail; cargo test -p tripletrail-server --test admin --test http pass.
  • cargo fmt --check, cargo clippy -p tripletrail-server --all-targets -- -D warnings, cargo test -p tripletrail-server --test admin, GUIDE_CHAPTER=02 cargo test -p tripletrail-server --test guide.

Documentation

  • No user-facing change, or:
  • The user guide (docs/guide/) shows it: new section "See how a query ran" in 02-first-steps.md, with a tested /ds/explain example
  • The reference page in docs/ (server.md, Web UI, --cors) and the CHANGELOG entry describe it

MatGUI's Explain view only knows QLever, GraphDB, Stardog, Blazegraph and
Neptune, so on the Query page it said "No engine recognised for this
endpoint" and showed no plan. The Query page now registers a TripleTrail
engine with it: for this server's own endpoints it POSTs the query to
…/explain (with the admin token and view-as headers) and draws plan.plan
as a tree with the rows and time of each step.
a_saved_graph_is_read_again_by_a_new_engine removed its folder with
remove_dir_all while the engine's background save of the rebuilt graph
could still write into it, which failed on CI with "Directory not empty"
and left the folder behind. It now uses tripletrail_testdir::tempdir,
removed after the engine is dropped and retried while a writer finishes.
Answers said "Server: tiny-http (Rust)". They now say
"TripleTrail/<version>", and --cors exposes the header, so the Explain
plugin of MatGUI and YASGUI can recognise the engine (the plugin's
TripleTrail engine keys on it) on any host, not only the Query page.
The Explain plugin of MatGUI and YASGUI does not recognise TripleTrail
yet; its TripleTrail engine waits for a plugin release.
@MathiasVDA
MathiasVDA merged commit 53a8ae3 into main Nov 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant