Neptune SPARQL API
W3C SPARQL 1.1 query language API for querying RDF graphs in Neptune. It provides an HTTP REST endpoint compatible with the SPARQL 1.1 protocol specification.
OpenAPI Specification
openapi: 3.1.0
info:
title: Amazon Neptune Neptune SPARQL API
description: >-
W3C SPARQL 1.1 query language API for querying RDF graphs in Neptune.
It provides an HTTP REST endpoint compatible with the SPARQL 1.1
protocol specification. Supports SELECT, ASK, CONSTRUCT, DESCRIBE
query forms and INSERT/DELETE update operations. Uses HTTP/1.1 with
HTTPS only.
version: '2024-01-01'
contact:
name: Amazon Web Services
url: https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-sparql.html
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://{cluster-endpoint}:8182
description: Neptune SPARQL HTTP 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: Query
description: Execute SPARQL queries and updates
- name: Status
description: Query status and cancellation operations
paths:
/sparql:
post:
operationId: executeSparqlQuery
summary: Amazon Neptune Execute a SPARQL Query or Update via HTTP POST
description: >-
Submits a SPARQL 1.1 query or update operation to the Neptune SPARQL
endpoint. For queries, use the 'query' parameter with SELECT, ASK,
CONSTRUCT, or DESCRIBE forms. For mutations, use the 'update' parameter
with INSERT DATA or DELETE DATA operations. The request body is
form-encoded per the SPARQL 1.1 Protocol specification.
tags:
- Query
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SparqlRequestBody'
examples:
selectQuery:
summary: SELECT query
value:
query: 'SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10'
insertData:
summary: INSERT DATA update
value:
update: 'INSERT DATA { <https://example.org/s> <https://example.org/p> <https://example.org/o> . }'
responses:
'200':
description: SPARQL query or update executed successfully.
content:
application/sparql-results+json:
schema:
$ref: '#/components/schemas/SparqlSelectResponse'
application/n-quads:
schema:
type: string
description: >-
N-Quads serialization for CONSTRUCT and DESCRIBE results.
'400':
description: Bad request - malformed SPARQL query or update.
content:
application/json:
schema:
$ref: '#/components/schemas/SparqlErrorResponse'
examples:
executeSparqlQuery400Example:
summary: Default executeSparqlQuery 400 response
x-microcks-default: true
value:
requestId: neptune-cluster-abc123
code: example-value
detailedMessage: example-value
'408':
description: Query timed out before completing.
'500':
description: Internal server error during query execution.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
get:
operationId: executeSparqlQueryGet
summary: Amazon Neptune Execute a SPARQL Query via HTTP GET
description: >-
Submits a read-only SPARQL 1.1 query via URL query parameters. Only
SELECT, ASK, CONSTRUCT, and DESCRIBE query forms are supported via
GET. Update operations require POST.
tags:
- Query
parameters:
- name: query
in: query
required: true
description: The SPARQL query string (URL-encoded).
schema:
type: string
example: SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10
responses:
'200':
description: SPARQL query executed successfully.
content:
application/sparql-results+json:
schema:
$ref: '#/components/schemas/SparqlSelectResponse'
'400':
description: Bad request - malformed SPARQL query.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/sparql/status:
get:
operationId: getSparqlQueryStatus
summary: Amazon Neptune Get the Status of All Running SPARQL Queries
description: >-
Returns the status of all running and waiting SPARQL queries,
including query IDs and execution statistics.
tags:
- Status
responses:
'200':
description: Query status retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SparqlQueryStatusList'
examples:
getSparqlQueryStatus200Example:
summary: Default getSparqlQueryStatus 200 response
x-microcks-default: true
value:
acceptedQueryCount: 1
runningQueryCount: 1
queries:
- {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/sparql/status/{queryId}:
get:
operationId: getSparqlQueryStatusById
summary: Amazon Neptune Get the Status of a Specific SPARQL Query
description: >-
Returns the status of a specific SPARQL query by its query ID.
tags:
- Status
parameters:
- name: queryId
in: path
required: true
description: The unique identifier of the SPARQL query.
schema:
type: string
responses:
'200':
description: Query status retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SparqlQueryStatusDetail'
examples:
getSparqlQueryStatusById200Example:
summary: Default getSparqlQueryStatusById 200 response
x-microcks-default: true
value:
queryId: neptune-cluster-abc123
queryString: example-value
queryEvalStats:
waited: 1
elapsed: 1
cancelled: true
'404':
description: Query with the specified ID was not found.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: cancelSparqlQuery
summary: Amazon Neptune Cancel a Running SPARQL Query
description: >-
Cancels a running SPARQL query by its query ID.
tags:
- Status
parameters:
- name: queryId
in: path
required: true
description: The unique identifier of the SPARQL query to cancel.
schema:
type: string
responses:
'200':
description: Query cancelled successfully.
'404':
description: Query with the specified ID was not found.
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:
SparqlRequestBody:
type: object
properties:
query:
type: string
description: >-
A SPARQL 1.1 query (SELECT, ASK, CONSTRUCT, or DESCRIBE). Mutually
exclusive with update.
update:
type: string
description: >-
A SPARQL 1.1 Update operation (INSERT DATA, DELETE DATA, etc.).
Mutually exclusive with query.
using-graph-uri:
type: string
description: Default graph URI for the query.
using-named-graph-uri:
type: string
description: Named graph URI for the query.
SparqlSelectResponse:
type: object
description: >-
SPARQL 1.1 Query Results JSON Format as defined by W3C.
properties:
head:
type: object
properties:
vars:
type: array
description: The list of variable names in the result set.
items:
type: string
link:
type: array
items:
type: string
results:
type: object
properties:
bindings:
type: array
description: The result bindings for each solution.
items:
type: object
additionalProperties:
type: object
properties:
type:
type: string
enum:
- uri
- literal
- bnode
value:
type: string
datatype:
type: string
xml:lang:
type: string
boolean:
type: boolean
description: The result for ASK queries.
SparqlErrorResponse:
type: object
properties:
requestId:
type: string
code:
type: string
detailedMessage:
type: string
description: Detailed error message explaining the issue.
SparqlQueryStatusList:
type: object
properties:
acceptedQueryCount:
type: integer
runningQueryCount:
type: integer
queries:
type: array
items:
$ref: '#/components/schemas/SparqlQueryStatusDetail'
SparqlQueryStatusDetail:
type: object
properties:
queryId:
type: string
queryString:
type: string
queryEvalStats:
type: object
properties:
waited:
type: integer
description: Time waited in queue (milliseconds).
elapsed:
type: integer
description: Elapsed execution time (milliseconds).
cancelled:
type: boolean