aws / aws/graph-explorer

Kickoff: Native Schema API Support

Open
#2,009 0 comments 0 reactions 0 assignees View on GitHub
internal schema wayfinder:kickoff
Dominant language
TypeScript
Stars
481
Forks
108
Avg merge
6d 8h
Merged PRs (30d)
5

Description

> [!NOTE]
> **Kickoff — Wayfinder not yet run, no chart yet.** Placeholder child of the **Native Schema API Support** initiative (#2008), holding a brain dump of paths to explore and potential blockers until scoping happens. "Placeholder" means only that there's no chart — the content below is real. Run `/wayfinder` against the initiative to create the map; **this kickoff closes when that map is created**, and the map takes over the scoping route.

## Rough intent

Determine how Graph Explorer should adopt the native **Neptune DB Schema API** (and the existing **Neptune Analytics** equivalent) as a source for schema discovery, replacing or augmenting today's query-derived schema-sync path — while keeping generic (non-Neptune) databases working.

## Notes

- **Domain:** schema sync — how Graph Explorer discovers a connection's vertex/edge types, properties, and relationships.
- **Skills to consult when charting:** `/wayfinder` to chart; `/research` to read the Neptune DB Schema API and Neptune Analytics schema docs; `/domain-modeling` for schema vocabulary.

## Paths to explore

Educated guesses at what needs investigating — the charting session confirms, splits, or drops them.

- **API capabilities** *(research)* — what exactly do the Neptune DB Schema API and the Neptune Analytics schema feature return? Does their output cover everything our current sync derives (types, properties, counts, multi-label nodes, edge connections)? Where are the gaps?
- **Detection & routing** *(grilling)* — how do we know a connection *supports* the Schema API? This overlaps capability probing (#1596). Does the answer depend on the **database provider type** (#1326)?
- **Fallback for generic databases** *(grilling)* — non-Neptune Gremlin/SPARQL endpoints won't have this API; the existing query-based sync must remain for them. What's the selection model?
- **Reconcile with existing sync work** *(grilling)* — the native API may obsolete some current efforts: #1604 (alternative SPARQL queries for sync perf) and #381 (optimize SPARQL sync query) could become moot on the Neptune path; #1681 (large-schema sync perf) may be largely solved by it. Which existing issues does adoption close, change, or leave untouched?
- **Data model mapping** *(research + grilling)* — how does the API's shape map onto our internal schema model? Does it require changes to how schema is stored/cached (relates to #1616, decoupling sync from the TanStack cache)?

## Potential blockers & pitfalls

- **Provider-type dependency (related, likely not blocking):** cleanly routing to the Schema API may be easier once **database provider type** (#1326) and the **connection UI overhaul** exist — related, but adoption is probably not *blocked* on them.
- **Version/availability gating:** the Neptune DB Schema API is newly released — older Neptune engine versions won't have it, so detection can't assume presence by "it's Neptune."
- **Gap risk:** if the API doesn't return everything sync needs, we may end up running *both* the API and supplemental queries — worth confirming early so the design doesn't assume a clean replacement.

## Related issues

- Initiative: #2008
- Related (likely not blocking): #1326 (database provider type / connection UI overhaul)
- Existing schema-sync work to reconcile: #1681, #1604, #1616, #1596, #381, #1212

> [!IMPORTANT]
> Internal only — this issue is maintained by the core team and is not accepting external contributions.

Contributor guide

Open the contributing guide

Research direction

Start by running /wayfinder against initiative #2008, then research the Neptune DB Schema API and Neptune Analytics schema documentation. Review the existing query-based schema sync and related issues #1681, #1604, #1616, #1596, #381, and #1212. Done means the initiative has a confirmed map covering capabilities, routing, fallback behavior, data-model mapping, and blockers; this kickoff then closes.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, databases
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
15/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.