[zipdoki]

Summary

A ranking gets written and can be read by naming its entity, but only through its own endpoint. Nothing can use one mid-query. Taking the accounts a user follows and then reading each one's top purchases needs two round trips and a client-side join. This adds a TOPK step to the multi-hop query so a ranking is just another hop.

The step names the source table and the declaration on it; the rows come from the ranking table that declaration points at. RankScan.from(...) resolves that table, its metric index and the start key from (topk, entity, dimensionValues). entity is a vertex like any other hop's source, so it can be a REF into an earlier step's
field. Omit it and the step reads a global ranking.

{
  "fetch": [
    {
      "type": "SCAN",
      "name": "a",
      "database": "graph",
      "table": "follows",
      "index": "created_at",
      "source": { "type": "VALUE", "value": "user1" }
    },
    {
      "type": "TOPK",
      "name": "b",
      "database": "graph",
      "table": "orders",
      "topk": "top_product_groups_1y",
      "entity": { "type": "REF", "ref": "a", "field": "tgt" },
      "limit": 10,
      "include": true
    }
  ]
}

I renamed query to fetch. There is no alias, so a payload written against query fails to parse. Nothing is released on this path, so I took the break rather than carrying two names; if someone turns out to be on the old one, the alias is a one-liner.

An empty result now carries the table's columns. TableBinding.emptyFrame replaces DataFrame.empty on the SCAN, CACHE and TOPK paths. A read that found nothing still came from a table that has columns, and dropping them turns "no rows" into "no such column" for anything that resolves names against the frame — the SQL transform stacked on
top of this cannot plan against a schema-less one. For a TOPK step the empty frame comes from the ranking table, not from the source table the step names, which costs one extra binding lookup on the empty path.

One thing this does not do: a TOPK step over several entities concatenates their rankings rather than merging them by metric, so the rows come back grouped per entity and not globally ordered. Ordering across entities is what the SQL transform in the next PR is for, and I'd rather do it there than hard-code a merge here.

Stacked on #497 — that needs to land first.

Part of #386.

Test plan

• ./gradlew :engine:test --tests '*TopkQuerySpec*' — per-entity, global and dimension-split rankings as a hop, REF entities, empty rankings
• ./gradlew :engine:test --tests '*ActionbaseQueryParserSpec*' — TOPK step parsing and the fetch key
• ./gradlew :engine:test --tests '*MultiHopQuerySpec*' — existing hops still chain
• ./gradlew :server:test --tests '*ActionbaseQueryE2ETest*' — the query endpoint over HTTP
• ./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