Neptune Streams generates a complete sequence of change-log entries that record every change made to graph data as it happens, enabling real-time capture of graph mutations via a REST API.
openapi: 3.1.0
info:
title: Amazon Neptune Neptune Streams API
description: >-
Neptune Streams generates a complete sequence of change-log entries that
record every change made to graph data as it happens, enabling real-time
capture of graph mutations via a REST API. Streams must be enabled by
setting the neptune_streams DB cluster parameter to 1. The API supports
both property graph (Gremlin/openCypher) and RDF (SPARQL) stream
endpoints. Only HTTP GET operations are allowed. Maximum response size
is 10 MB. Supports gzip compression via Accept-Encoding header.
version: '2024-01-01'
contact:
name: Amazon Web Services
url: https://docs.aws.amazon.com/neptune/latest/userguide/streams.html
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{cluster-endpoint}:8182
description: Neptune Streams REST endpoint
variables:
cluster-endpoint:
default: your-cluster-endpoint.region.neptune.amazonaws.com
description: The cluster endpoint DNS name for your Neptune DB cluster
security:
- aws_sigv4: []
tags:
- name: Property Graph Stream
description: Change data capture for property graph (Gremlin/openCypher) data
- name: SPARQL Stream
description: Change data capture for RDF (SPARQL) data
paths:
/propertygraph/stream:
get:
operationId: getPropertyGraphStream
summary: Amazon Neptune Get Property Graph Change Stream Records
description: >-
Gets a stream of change-log entries for property graph
(Gremlin/openCypher) data. Each entry records a mutation (ADD or
REMOVE) made to vertices, edges, or their properties. The response
format is PG_JSON. This is the recommended endpoint for property
graph streams, replacing the deprecated /gremlin/stream endpoint.
tags:
- Property Graph Stream
parameters:
- name: limit
in: query
description: >-
Maximum number of records to return (1-100,000). Default is 10.
The 10 MB response size limit takes precedence over this value.
schema:
type: integer
minimum: 1
maximum: 100000
default: 10
- name: iteratorType
in: query
description: >-
Determines the starting point for reading the stream.
schema:
type: string
enum:
- AT_SEQUENCE_NUMBER
- AFTER_SEQUENCE_NUMBER
- TRIM_HORIZON
- LATEST
default: AT_SEQUENCE_NUMBER
- name: commitNum
in: query
description: >-
The commit number to start reading from. Required when
iteratorType is AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER.
schema:
type: integer
- name: opNum
in: query
description: >-
The operation sequence number within the specified commit.
Default is 1.
schema:
type: integer
default: 1
- name: Accept-Encoding
in: header
description: Set to 'gzip' to receive compressed responses.
schema:
type: string
enum:
- gzip
responses:
'200':
description: Stream records retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyGraphStreamResponse'
examples:
getPropertyGraphStream200Example:
summary: Default getPropertyGraphStream 200 response
x-microcks-default: true
value:
lastEventId: {}
lastTrxTimestamp: 1
format: PG_JSON
records:
- {}
totalRecords: 1
'400':
description: Bad request - invalid parameters.
'500':
description: Internal server error.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/pg/stream:
get:
operationId: getPropertyGraphStreamAlias
summary: Amazon Neptune Get Property Graph Change Stream Records (alias)
description: >-
Alias for /propertygraph/stream. Gets a stream of change-log entries
for property graph data. Supports the same parameters and returns
the same response format.
tags:
- Property Graph Stream
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100000
default: 10
- name: iteratorType
in: query
schema:
type: string
enum:
- AT_SEQUENCE_NUMBER
- AFTER_SEQUENCE_NUMBER
- TRIM_HORIZON
- LATEST
- name: commitNum
in: query
schema:
type: integer
- name: opNum
in: query
schema:
type: integer
default: 1
responses:
'200':
description: Stream records retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyGraphStreamResponse'
examples:
getPropertyGraphStreamAlias200Example:
summary: Default getPropertyGraphStreamAlias 200 response
x-microcks-default: true
value:
lastEventId: {}
lastTrxTimestamp: 1
format: PG_JSON
records:
- {}
totalRecords: 1
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/sparql/stream:
get:
operationId: getSparqlStream
summary: Amazon Neptune Get SPARQL RDF Change Stream Records
description: >-
Gets a stream of change-log entries for RDF (SPARQL) data. Each
entry records a mutation (ADD or REMOVE) of an RDF triple or quad.
The response format is NQUADS, with each change represented as an
N-Quads statement string.
tags:
- SPARQL Stream
parameters:
- name: limit
in: query
description: >-
Maximum number of records to return (1-100,000). Default is 10.
schema:
type: integer
minimum: 1
maximum: 100000
default: 10
- name: iteratorType
in: query
description: >-
Determines the starting point for reading the stream.
schema:
type: string
enum:
- AT_SEQUENCE_NUMBER
- AFTER_SEQUENCE_NUMBER
- TRIM_HORIZON
- LATEST
default: AT_SEQUENCE_NUMBER
- name: commitNum
in: query
description: >-
The commit number to start reading from. Required when
iteratorType is AT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER.
schema:
type: integer
- name: opNum
in: query
description: >-
The operation sequence number within the specified commit.
schema:
type: integer
default: 1
- name: Accept-Encoding
in: header
description: Set to 'gzip' to receive compressed responses.
schema:
type: string
enum:
- gzip
responses:
'200':
description: Stream records retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SparqlStreamResponse'
examples:
getSparqlStream200Example:
summary: Default getSparqlStream 200 response
x-microcks-default: true
value:
lastEventId: {}
lastTrxTimestamp: 1
format: NQUADS
records:
- {}
totalRecords: 1
'400':
description: Bad request - invalid parameters.
'500':
description: Internal server error.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
aws_sigv4:
type: apiKey
name: Authorization
in: header
description: AWS Signature Version 4 authentication via IAM
schemas:
PropertyGraphStreamResponse:
type: object
properties:
lastEventId:
$ref: '#/components/schemas/StreamEventId'
lastTrxTimestamp:
type: integer
description: Unix epoch timestamp in milliseconds of the last commit.
format:
type: string
enum:
- PG_JSON
description: The serialization format (always PG_JSON for property graph).
records:
type: array
description: The array of change-log stream records.
items:
$ref: '#/components/schemas/PropertyGraphStreamRecord'
totalRecords:
type: integer
description: Total number of records in the response.
PropertyGraphStreamRecord:
type: object
properties:
commitTimestamp:
type: integer
description: Unix epoch timestamp in milliseconds of the transaction commit.
eventId:
$ref: '#/components/schemas/StreamEventId'
data:
$ref: '#/components/schemas/PropertyGraphData'
op:
type: string
enum:
- ADD
- REMOVE
description: The operation type (ADD or REMOVE).
isLastOp:
type: boolean
description: >-
True only if this is the last operation in the transaction.
PropertyGraphData:
type: object
description: >-
The serialized property graph change data. The type field indicates
the element kind.
properties:
id:
type: string
description: The unique identifier of the element.
type:
type: string
description: >-
The element type: v (vertex), vl (vertex label), vp (vertex
property), e (edge), ep (edge property).
enum:
- v
- vl
- vp
- e
- ep
key:
type: string
description: The property key name.
value:
type: object
description: The property value with its data type.
properties:
value:
description: The actual property value.
dataType:
type: string
description: The data type (String, Integer, Double, etc.).
from:
type: string
description: Source vertex ID (for edges only).
to:
type: string
description: Target vertex ID (for edges only).
SparqlStreamResponse:
type: object
properties:
lastEventId:
$ref: '#/components/schemas/StreamEventId'
lastTrxTimestamp:
type: integer
description: Unix epoch timestamp in milliseconds of the last commit.
format:
type: string
enum:
- NQUADS
description: The serialization format (always NQUADS for RDF).
records:
type: array
description: The array of change-log stream records.
items:
$ref: '#/components/schemas/SparqlStreamRecord'
totalRecords:
type: integer
description: Total number of records in the response.
SparqlStreamRecord:
type: object
properties:
commitTimestamp:
type: integer
description: Unix epoch timestamp in milliseconds of the transaction commit.
eventId:
$ref: '#/components/schemas/StreamEventId'
data:
type: object
properties:
stmt:
type: string
description: >-
The N-Quads statement representing the RDF triple or quad change.
op:
type: string
enum:
- ADD
- REMOVE
description: The operation type (ADD or REMOVE).
isLastOp:
type: boolean
description: True only if this is the last operation in the transaction.
StreamEventId:
type: object
description: A sequence identifier for a stream event.
properties:
commitNum:
type: integer
description: The commit (transaction) number.
opNum:
type: integer
description: The operation number within the commit.