[zipdoki]

Summary

The skeleton in #491 declared the endpoints and returned nothing. This fills them in: a query registers once, gets called by id or by a name pointing at one, and takes its values per call.

POST   /graph/v3/prepared-queries            register
GET    /graph/v3/prepared-queries/{id}       read one, by id or by a name for it
PUT    /graph/v3/prepared-queries/{id}
DELETE /graph/v3/prepared-queries/{id}
POST   /graph/v3/prepared-queries/aliases    point a name at an id
POST   /graph/v3/query/{id}                  run it

Registration declares the arguments with their types, and the body holds {name} anywhere a whole value would go.

{
  "name": "top_items_of_friends",
  "arguments": [{ "name": "entity", "type": "STRING" }, { "name": "size", "type": "INT" }],
  "fetch": [
    { "type": "SCAN", "name": "follows", "database": "graph", "table": "follows", "index": "created_at", "source": { "type": "VALUE", "value": "{entity}" } },
    { "type": "TOPK", "name": "ranked", "database": "graph", "table": "orders", "topk": "top_product_groups_1y", "entity": { "type": "REF", "ref": "follows", "field": "tgt" }, "limit": "{size}" }
  ],
  "transform": [
    { "type": "SQL", "name": "top_items", "sql": "SELECT ranked.tgt, SUM(ranked.metric) AS metric FROM ranked GROUP BY ranked.tgt ORDER BY metric DESC LIMIT ?", "arguments": ["size"] }
  ]
}

{ "arguments": { "entity": "user1", "size": 10 } }

Binding happens on the JSON, before it's read into an ActionbaseQuery. It has to: "limit": "{size}" can't be the Int that slot wants until the value is in. A placeholder inside SQL is different — it becomes a ? bound at execution, so the SQL text and therefore the compiled plan stay identical between calls.

Registration checks that the names used and the names declared are the same set, so a typo fails at registration rather than at the first call. POST /graph/v3/query takes the same shape unregistered, with values sent alongside the body — no declaration, so a value goes in as the JSON it came as.

Registered queries and the names for them live in the metastore as sys.query and sys.query_alias. PreparedQueryService caches the compiled query by id and the id behind each name, since resolving a name and re-parsing a template on every call is the cost this whole feature exists to avoid.

Placeholders are whole values only. "user-{entity}" is a literal string, not a template. That keeps arguments typed and keeps me out of building strings from untrusted input. If string composition turns out to be needed, it belongs in the SQL transform rather than in the binder.

Running a query lives on the query path (POST /graph/v3/query/{id}), not under /prepared-queries/{id}, so reading a query and running it never look alike. That's another read on POST, so ReadOnlyRequestFilter learns one more segment (/query/).

The second commit fixes the first. Cache invalidation on delete ran in doFinally, which fires after the completion signal has already reached the caller — so a caller's very next read could still be served the query it just deleted. It runs before completion now. PreparedQuerySpec > a query a name still points at cannot be dropped is
the test that caught it.

There's no versioning. An update replaces a registration in place, and a call already in flight binds against the shape it loaded. I'll leave versioned registrations for a follow-up.

Stacked on #499 — that needs to land first. This supersedes #491; I'll close that one once this lands.

Part of #490.

Test plan

• ./gradlew :engine:test --tests '*PreparedQueryTest*' — placeholder binding, whole-value rule, declared-vs-used names, type casting, SQL arguments
• ./gradlew :engine:test --tests '*TransformRequestTest*' — the request shape for fetch plus transform plus arguments
• ./gradlew :engine:test --tests '*PreparedQuerySpec*' --tests '*TransformQuerySpec*' — registration, names, update, delete, cache invalidation, and a registered query with a transform end to end
• ./gradlew :server:test --tests '*PreparedQueryE2ETest*' — every endpoint over HTTP, by id and by name
• ./gradlew :server:test --tests '*ReadOnlyRequestFilterTest*' — running a prepared query passes in read-only mode
• ./gradlew spotlessCheck build — formatting and full build

AI Assistance

• This PR was written largely with AI assistance.
  • Tool / model: Claude Code (Opus 5)

[zipdoki]

Optimistic Merge