Fetch graph schema live via APOC, cached for the session (1.4.0)#18
Merged
adamjohnwright merged 1 commit intomainfrom Apr 24, 2026
Merged
Fetch graph schema live via APOC, cached for the session (1.4.0)#18adamjohnwright merged 1 commit intomainfrom
adamjohnwright merged 1 commit intomainfrom
Conversation
The curator reported Claude saying the APOC schema was "limited." Root
cause: reactome_cypher_schema was calling the sparse built-in
db.schema.*, which omits counts, cardinalities, and indexes. When
Claude tried apoc.meta.schema() via reactome_cypher_query, the ~500 KB
single-row result hit the per-row token cap and returned a truncation
stub.
Fix: pull the rich schema inside fetchGraphSchema, format it ourselves,
never surface it through the capped query tool.
What changed
- src/graph/schema.ts: new module. fetchGraphSchema runs
apoc.meta.{schema,stats,nodeTypeProperties,relTypeProperties},
dbms.components, db.indexes, db.constraints in parallel and
assembles a GraphSchema object. Cached in-memory for the session;
concurrent first-callers share one fetch via a pending-promise.
60 s timeout per query (up from the 30 s cypher default) because
apoc.meta.schema() samples 3M nodes.
- src/graph/format-schema.ts: markdown digest with labels sorted by
node count, relationship types sorted by cardinality, per-label +
per-rel property types with mandatory flags, indexes, constraints.
~80 KB on Reactome (was ~40 KB with db.schema.*).
- src/index.ts: prefetch on startup so the first tool call is warm.
- src/tools/cypher.ts + src/resources/static.ts: route to the new
module. No functional change beyond what's documented.
- Split out of src/clients/neo4j.ts so tests can vi.mock runRead
across the module boundary.
- 7 new tests: format coverage + cache/dedup/fallback behaviors.
Verified live against the running Reactome Release96 container:
- Cold fetch: 21 s on the full graph (this is why we prefetch).
- Second call: 0 ms, same object reference.
- Markdown digest: 80,123 chars.
- Mocked-fallback test confirms graceful degradation when
apoc.meta.relTypeProperties / db.indexes / db.constraints are
unavailable.
No vendored schema artifact. No coordination with reactome_neo4j_env.
One source of truth: the live database.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The curator reported Claude saying the APOC schema was "limited." Root cause: reactome_cypher_schema was calling the sparse built-in db.schema.*, which omits counts, cardinalities, and indexes. When Claude tried apoc.meta.schema() via reactome_cypher_query, the ~500 KB single-row result hit the per-row token cap and returned a truncation stub.
Fix: pull the rich schema inside fetchGraphSchema, format it ourselves, never surface it through the capped query tool.
What changed
Verified live against the running Reactome Release96 container:
No vendored schema artifact. No coordination with reactome_neo4j_env. One source of truth: the live database.