Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

GetSparqlStream

Gets a stream for an RDF graph.

With the Neptune Streams feature, you can generate a complete sequence of change-log entries that record every change made to your graph data as it happens. GetSparqlStream lets you collect these change-log entries for an RDF graph.

The Neptune streams feature needs to be enabled on your Neptune DBcluster. To enable streams, set the neptune_streams DB cluster parameter to 1.

See Capturing graph changes in real time using Neptune streams.

When invoking this operation in a Neptune cluster that has IAM authentication enabled, the IAM user or role making the request must have a policy attached that allows the neptune-db:GetStreamRecords IAM action in that cluster.

Note that the neptune-db:QueryLanguage:Sparql IAM condition key can be used in the policy document to restrict the use of SPARQL queries (see Condition keys available in Neptune IAM data-access policy statements).

Request Syntax


GET /sparql/stream?commitNum=commitNum&iteratorType=iteratorType&limit=limit&opNum=opNum HTTP/1.1
Accept-Encoding: encoding

URI Request Parameters

The request uses the following URI parameters.

commitNum

The commit number of the starting record to read from the change-log stream. This parameter is required when iteratorType isAT_SEQUENCE_NUMBER or AFTER_SEQUENCE_NUMBER, and ignored when iteratorType is TRIM_HORIZON or LATEST.

encoding

If set to TRUE, Neptune compresses the response using gzip encoding.

Valid Values: gzip

iteratorType

Can be one of:

AT_SEQUENCE_NUMBER – Indicates that reading should start from the event sequence number specified jointly by the commitNum and opNum parameters.
AFTER_SEQUENCE_NUMBER – Indicates that reading should start right after the event sequence number specified jointly by the commitNum and opNum parameters.
TRIM_HORIZON – Indicates that reading should start at the last untrimmed record in the system, which is the oldest unexpired (not yet deleted) record in the change-log stream.
LATEST – Indicates that reading should start at the most recent record in the system, which is the latest unexpired (not yet deleted) record in the change-log stream.

Valid Values: AT_SEQUENCE_NUMBER | AFTER_SEQUENCE_NUMBER | TRIM_HORIZON | LATEST

limit

Specifies the maximum number of records to return. There is also a size limit of 10 MB on the response that can't be modified and that takes precedence over the number of records specified in the limit parameter. The response does include a threshold-breaching record if the 10 MB limit was reached.

The range for limit is 1 to 100,000, with a default of 10.

Valid Range: Minimum value of 1. Maximum value of 100000.

opNum

The operation sequence number within the specified commit to start reading from in the change-log stream data. The default is 1.

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "format": "string",
   "lastEventId": { 
      "string" : "string" 
   },
   "lastTrxTimestamp": number,
   "records": [ 
      { 
         "commitTimestamp": number,
         "data": { 
            "stmt": "string"
         },
         "eventId": { 
            "string" : "string" 
         },
         "isLastOp": boolean,
         "op": "string"
      }
   ],
   "totalRecords": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

format

Serialization format for the change records being returned. Currently, the only supported value is NQUADS.

Type: String

lastEventId

Sequence identifier of the last change in the stream response.

An event ID is composed of two fields: a commitNum, which identifies a transaction that changed the graph, and an opNum, which identifies a specific operation within that transaction:

Type: String to string map

lastTrxTimestamp

The time at which the commit for the transaction was requested, in milliseconds from the Unix epoch.

Type: Long

records

An array of serialized change-log stream records included in the response.

Type: Array of SparqlRecord objects

totalRecords

The total number of records in the response.

Type: Integer

Errors

For information about the errors that are common to all actions, see Common Errors.

ClientTimeoutException

Raised when a request timed out in the client.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 408

ConstraintViolationException

Raised when a value in a request field did not satisfy required constraints.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400

ExpiredStreamException

Raised when a request attempts to access an stream that has expired.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400

IllegalArgumentException

Raised when an argument in a request is not supported.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400

InvalidArgumentException

Raised when an argument in a request has an invalid value.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400

InvalidParameterException

Raised when a parameter value is not valid.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request that includes an invalid parameter.

HTTP Status Code: 400

MemoryLimitExceededException

Raised when a request fails because of insufficient memory resources. The request can be retried.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request that failed.

HTTP Status Code: 500

PreconditionsFailedException

Raised when a precondition for processing a request is not satisfied.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400

StreamRecordsNotFoundException

Raised when stream records requested by a query cannot be found.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 404

ThrottlingException

Raised when the rate of requests exceeds the maximum throughput. Requests can be retried after encountering this exception.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request that could not be processed for this reason.

HTTP Status Code: 500

TooManyRequestsException

Raised when the number of requests being processed exceeds the limit.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request that could not be processed for this reason.

HTTP Status Code: 429

UnsupportedOperationException

Raised when a request attempts to initiate an operation that is not supported.

code: The HTTP status code returned with the exception.
detailedMessage: A detailed message describing the problem.
requestId: The ID of the request in question.

HTTP Status Code: 400