Skip to content

feat: add TripleTrail as an engine - #9

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

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

Conversation

@MathiasVDA

@MathiasVDA MathiasVDA commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Adds TripleTrail to the engines the Explain view can ask for a plan.

  • src/engines/tripletrail.ts: asks /{ds}/explain beside /{ds}/sparql, /{ds}/query or /{ds}/update (also /$/workspaces/{id}/…), with Accept: application/json, through yasr.executeQuery with the tab's authentication where the host supports it. It draws plan.plan as a tree (each step's name, number of results, duration in seconds, children), with the row count, planning time and the spatial index's decisions as the summary. A caller limited to some graphs gets the row count and a note on why there is no plan. Query results or HTML instead of a plan give a clear error.
  • Detection: a Server header naming TripleTrail. TripleTrail sends Server: TripleTrail/<version> and exposes it to CORS pages from fix(ui): show TripleTrail's plan in MatGUI's Explain tab tripletrail#67. There is no URL rule, since /{ds}/sparql says nothing about the engine.
  • tripletrail added to EngineId, ENGINES and ENGINE_IDS. The "No engine recognised" message, README, package description/keywords and publiccode.yml list it.

Tests: new cases in tests/engines/engines.test.ts (URL mapping, request, tree and summary, restricted answer, wrong answers, header detection). npm test passes with 36 tests, and npm run build, tsc --noEmit and the Prettier check all pass too.

After merging, a release (e.g. 1.1.0) publishes it to npm, and MatGUI then bumps @matdata/yasgui-explain-plugin.

TripleTrail explains a query on /{ds}/explain beside /{ds}/sparql and
/{ds}/query, and answers JSON with the plan it ran: each step with its
name, rows, duration and children, plus the planning time and the
decisions of its spatial index. The engine asks that URL and draws the
plan as a tree; a caller limited to some graphs gets the row count with
a note. It is recognised from a Server header naming TripleTrail.
The demo has a recorded plan per engine to try the view without an endpoint. Add one for TripleTrail, with a spatial filter so the summary lines show, and name the engine in the demo intro and the README.

@MathiasVDA MathiasVDA left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: OK to merge.

Checked:

  • src/engines/tripletrail.ts: the /explain URL mapping keeps query strings and handles /sparql, /query, /update, trailing slashes and workspace paths. The parser copes with missing or non-numeric fields, refuses SPARQL results and non-JSON answers with a clear message, and falls back to text for a restricted caller.
  • Detection only from the Server header, placed after the other header checks, so no existing endpoint changes engine.
  • needsRequestOptions: true is right, since the request goes to another URL. Hosts without queryRequest fall back to the direct fetch, like Stardog.
  • npm test (36 tests), tsc --noEmit, Prettier on src and tests, and npm run build pass locally.

Pushed one commit: a TripleTrail sample plan for the demo (?sample=tripletrail), so every engine with a tree or text plan has a recorded sample, plus the engine name in the demo intro and README. Rendered it in the demo: the tree, rows, times and the spatial summary lines show as expected.

Notes, not blocking:

  • The plan shape is taken from the PR description and tests. It was not checked against a running TripleTrail server.
  • A JSON answer without plan, rows or restricted (for example an error object sent with status 200) shows "No plan." If TripleTrail has such a shape, a message for it can follow.
  • After the release, the MatGUI user guide (Explain section) should list TripleTrail when the plugin is bumped there.

Generated by Claude Code

@MathiasVDA
MathiasVDA merged commit d2594e6 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