aws / aws/graph-explorer

Test Graph Explorer with Neptune 1.4.7 spatial data support

Open
#1,657 0 comments 0 reactions 1 assignee Claimed by @kmcginnes View on GitHub
database support exploration fundamental query editor schema
Dominant language
TypeScript
Stars
481
Forks
108
Avg merge
6d 8h
Merged PRs (30d)
5

Description

## Goal

Determine how Graph Explorer behaves with Neptune 1.4.7's new native spatial data support and identify any issues that need to be addressed.

Neptune 1.4.7 (released March 2026) introduces a new `Geometry` data type and 11 spatial functions for openCypher, following the ISO 13249-3 standard. This is a significant addition because Graph Explorer has no existing handling for the `Geometry` type — property values, schema discovery, search, and visualization may all be affected.

## Background

### What's new in Neptune 1.4.7

Neptune now supports spatial queries via a new `Geometry` property type. Key details:

- **Coordinate system**: SRID 0 (Cartesian), compatible with longitude/latitude values
- **Data format**: Well-Known Text (WKT) for input, Well-Known Binary (WKB) via Bolt driver
- **Supported shapes**: Points, lines, polygons
- **Storage**: `Geometry` properties on nodes and edges, created via `ST_GeomFromText()` from WKT strings
- **Spatial index**: Automatic spatial indexing for Point data to accelerate functions like `ST_Contains`
- **3D storage**: Supports storing 3D coordinates, but spatial functions only operate on 2D (x/y)

### Spatial functions available

| Function | Purpose |
|---|---|
| `ST_Point` | Create a point |
| `ST_GeomFromText` | Create geometry from WKT string |
| `ST_AsText` | Convert geometry to WKT string |
| `ST_GeometryType` | Get the geometry type |
| `ST_Equals` | Test equality |
| `ST_Contains` | Test containment |
| `ST_Intersects` | Test intersection |
| `ST_Distance` | Calculate Cartesian distance |
| `ST_DistanceSpheroid` | Calculate spheroid distance (WGS84) |
| `ST_Envelope` | Get bounding box |
| `ST_Buffer` | Create buffer zone |

### Example data

```cypher
CREATE (n:airport {code: 'ATL', location: ST_GeomFromText('POINT (-84.4281 33.6367)')})
```

Bulk load CSV format uses a `Geometry` column type:
```csv
:ID,:LABEL,code:String,city:String,location:Geometry
21,airport,ATL,Atlanta,POINT (-84.42810059 33.63669968)
```

### Documentation

- [Spatial Data overview](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-22-spatial-data.html)
- [Spatial Functions reference](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-22-spatial-functions.html)
- [AWS announcement](https://aws.amazon.com/about-aws/whats-new/2026/03/amazon-neptune-database-spatial-data/)

## Testing Plan

### 1. Setup

- Provision a Neptune 1.4.7 cluster
- Load the [air-routes dataset](https://github.com/krlawrence/graph/tree/main/sample-data) with `Geometry` properties using the example from the docs
- Connect Graph Explorer to the cluster

### 2. Schema discovery

- Does `fetchSchema` correctly discover `Geometry`-typed properties?
- How does the schema represent the `Geometry` type? Is it treated as a string, an object, or something else?
- Does the schema sync complete without errors?

### 3. Property display

- How are `Geometry` values rendered in the node/edge detail panels?
- Are WKT strings displayed readably, or do we get raw binary / `[object Object]`?
- If using the Bolt driver, values come back as WKB (byte arrays) — does the proxy server or the UI handle this?

### 4. Search and filtering

- Can keyword search match on `Geometry` properties?
- Do attribute filters work with `Geometry` values?
- Does filtering on `Geometry` properties cause errors?

### 5. Graph visualization

- Do nodes with `Geometry` properties render correctly in the graph view?
- Are there any issues with Cytoscape.js when nodes have non-primitive property values?

### 6. Bulk load / import

- Can Graph Explorer import data that includes `Geometry` columns?

## Potential Issues

1. **Unknown data type**: Graph Explorer has zero handling for `Geometry` types today. Properties may render as `[object Object]`, raw binary, or cause runtime errors.
2. **WKB via Bolt**: The proxy server uses the Bolt driver for openCypher connections. Geometry values will be returned as WKB byte arrays, not human-readable WKT strings. The proxy likely does not convert these.
3. **Schema type mapping**: The openCypher schema discovery queries may not recognize `Geometry` as a valid property type, potentially causing schema sync failures or omitting spatial properties.
4. **Search queries**: Keyword search templates construct `CONTAINS` or `=` comparisons on property values. These may fail or produce errors when applied to `Geometry` properties.
5. **Property serialization**: Geometry values may not serialize cleanly to JSON for the REST API between the proxy server and the UI.

## Expected Outcome

- A summary of what works and what breaks when connecting to Neptune 1.4.7 with spatial data
- A list of issues to file for any bugs or missing functionality discovered
- A recommendation on whether we need explicit `Geometry` type support or if treating it as a string (WKT) is sufficient

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.