aws / aws/graph-explorer

Gremlin `::` composite-label split is unconditional; gate it on a Neptune backend

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

Description

## Description

Graph Explorer splits Gremlin vertex labels on `::` at the five ingestion sites (`mapApiVertex`, `fetchEdgeConnections`, `verticesSchemaTemplate`, `edgesSchemaTemplate`, `neighborCounts`), because Amazon Neptune joins a vertex's multiple labels with the reserved `::` delimiter and surfaces the composite as a single string. This split is **unconditional** — applied regardless of the connected backend.

`::` is Neptune-specific and reserved. Core TinkerPop backends (JanusGraph, Gremlin Server, TinkerGraph) mandate one immutable label per element with no reserved characters, so a single label may legitimately *be* `foo::bar`. Against those backends, ingestion still breaks such a label apart into two types.

The 3.2.1 consolidation (#2063) mitigated the worst cases with a keep-whole-on-empty-segment rule (`foo::`, `::foo`, `a::::b`, `::` survive intact), but a non-empty composite like `foo::bar` on a generic TinkerPop backend is still incorrectly split. The [split ADR](https://github.com/aws/graph-explorer/blob/main/docs/adr/20260807-split-composite-labels-once-at-gremlin-ingestion.md) records this as the known limitation a follow-up addresses:

> The split is applied unconditionally, which is correct only for Neptune. […] this is the known limitation the follow-up issue addresses.

The ADR rejected gating the split on the backend "for now" because no reliable Neptune-vs-generic discriminator exists at the split sites, and plumbing one is a separate architectural change — the connection database-type work in #1329.

## Expected Behavior

The `::` split applies only when the connected backend is Neptune. A generic TinkerPop backend whose vertex carries a single label containing `::` (e.g. `foo::bar`) preserves it as one type. Requires a backend discriminator plumbed to the ingestion sites, which depends on #1329.

## Related Issues

- Blocked by #1329 (Add database type option)
- Follows up on #2063 (Split composite labels once at the Gremlin ingestion boundary)

> [!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

Read the split ADR and the dependency in #1329 first, then inspect the five ingestion sites: mapApiVertex, fetchEdgeConnections, verticesSchemaTemplate, edgesSchemaTemplate, and neighborCounts. Done means the `::` split occurs only for Neptune while a generic TinkerPop backend preserves a label such as `foo::bar` intact.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, typescript
Domain
backend, databases
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.