# Accessing the Neptune Graph with openCypher
Neptune supports building graph applications using openCypher, currently one of the most popular query languages for developers working with graph databases. Developers, business analysts, and data scientists like openCypher’s SQL-inspired syntax because it provides a familiar structure to compose queries for graph applications.
**openCypher** is a declarative query language for property graphs that was originally developed by Neo4j, then open-sourced in 2015, and contributed to the [openCypher](http://www.opencypher.org/) project under an Apache 2 open-source license. Its syntax is documented in the [Cypher Query Language Reference, Version 9](https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf).
For the limitations and differences in Neptune support of the openCypher specification, see [openCypher specification compliance in Amazon Neptune](feature-opencypher-compliance.md).
**Note**
The current Neo4j implementation of the Cypher query language has diverged in some ways from the openCypher specification. If you are migrating current Neo4j Cypher code to Neptune, see [Neptune compatibility with Neo4j](migration-compatibility.md) and [Rewriting Cypher queries to run in openCypher on Neptune](migration-opencypher-rewrites.md) for help.
Starting with engine release 1.1.1.0, openCypher is available for production use in Neptune.
## Gremlin vs. openCypher: similarities and differences
Gremlin and openCypher are both property-graph query languages, and they are complementary in many ways.
Gremlin was designed to appeal to programmers and fit seamlessly into code. As a result, Gremlin is imperative by design, whereas openCypher's declarative syntax may feel more familiar for people with SQL or SPARQL experience. Gremlin might seem more natural to a data scientist using Python in a Jupyter notebook, whereas openCypher might seem more intuitive to a business user with some SQL background.
The nice thing is that **you don't have to choose** between Gremlin and openCypher in Neptune. Queries in either language can operate on the same graph regardless of which of the two language was used to enter that data. You may find it more convenient to use Gremlin for some things and openCypher for others, depending on what you're doing.
Gremlin uses an imperative syntax that lets you control how you move through your graph in a series of steps, each of which takes in a stream of data, performs some action on it (using a filter, map, and so forth), and then outputs the results to the next step. A Gremlin query commonly takes the form, `g.V()`, followed by additional steps.
In openCypher, you use a declarative syntax, inspired by SQL, that specifies a pattern of nodes and relationships to find in your graph using a motif syntax (like `()-[]->()`). An openCypher query often starts with a `MATCH` clause, followed by other clauses such as `WHERE`, `WITH`, and `RETURN`.
# Getting started using openCypher
You can query property-graph data in Neptune using openCypher regardless of how it was loaded, but you can't use openCypher to query data loaded as RDF.
The [Neptune bulk loader](bulk-load.md) accepts property-graph data in a [CSV format for Gremlin](bulk-load-tutorial-format-gremlin.md), and in a [CSV format for openCypher](bulk-load-tutorial-format-opencypher.md). Also, of course, you can add property data to your graph using Gremlin and/or openCypher queries.
There are many online tutorials available for learning the Cypher query language. Here, a few quick examples of openCypher queries may help you get an idea of the language, but by far the best and easiest way to get started using openCypher to query your Neptune graph is by using the openCypher notebooks in the [Neptune workbench](graph-notebooks.md). The workbench is open-source, and is hosted on GitHub at [https://github.com/aws-samples/amazon-neptune-samples](https://github.com/aws-samples/amazon-neptune-samples/).
You'll find the openCypher notebooks in the GitHub [Neptune graph-notebook repository](https://github.com/aws/graph-notebook/tree/main/src/graph_notebook/notebooks). In particular, check out the [Air-routes visualization](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/02-Visualization/Air-Routes-openCypher.ipynb), and [English Premier Teams](https://github.com/aws/graph-notebook/blob/main/src/graph_notebook/notebooks/02-Visualization/EPL-openCypher.ipynb) notebooks for openCypher.
Data processed by openCypher takes the form of an unordered series of key/value maps. The main way to refine, manipulate, and augment these maps is to use clauses that perform tasks such as pattern matching, insertion, update, and deletion on the key/value pairs.
There are several clauses in openCypher for finding data patterns in the graph, of which `MATCH` is the most common. `MATCH` lets you specify the pattern of nodes, relationships, and filters that you want to look for in your graph. For example:
+ **Get all nodes**
```
MATCH (n) RETURN n
```
+ **Find connected nodes**
```
MATCH (n)-[r]->(d) RETURN n, r, d
```
+ **Find a path**
```
MATCH p=(n)-[r]->(d) RETURN p
```
+ **Get all nodes with a label**
```
MATCH (n:airport) RETURN n
```
Note that the first query above returns every single node in your graph, and the next two return every node that has a relationship— this is not generally recommended\$1 In almost all cases, you want to narrow down the data being returned, which you can do by specifying node or relationship labels and properties, as in the fourth example.
You can find a handy cheat-sheet for openCypher syntax in the Neptune [github sample repository](https://github.com/aws-samples/amazon-neptune-samples/tree/master/opencypher/Cheatsheet.md).
# Neptune openCypher status servlet and status endpoint
The openCypher status endpoint provides access to information about queries that are currently running on the server or waiting to run. It also lets you cancel those queries. The endpoint is:
```
https://(the server):(the port number)/openCypher/status
```
You can use the HTTP `GET` and `POST` methods to get current status from the server, or to cancel a query. You can also use the `DELETE` method to cancel a running or waiting query.
## Parameters for status requests
**Status query parameters**
+ **`includeWaiting`** (`true` or `false`) – When set to `true` and other parameters are not present, causes status information for waiting queries to be returned as well as for running queries.
+ **`cancelQuery`** – Used only with `GET` and `POST` methods, to indicate that this is a cancelation request. The `DELETE` method does not need this parameter.
The value of the `cancelQuery` parameter is not used, but when `cancelQuery` is present, the `queryId` parameter is required, to identify which query to cancel.
+ **`queryId`** – Contains the ID of a specific query.
When used with the `GET` or `POST` method and the `cancelQuery` parameter is not present, `queryId` causes status information to be returned for the specific query it identifies. If the `cancelQuery` parameter is present, then the specific query that `queryId` identifies is canceled.
When used with the `DELETE` method, `queryId` always indicates a specific query to be canceled.
+ **`silent`** – Only used when canceling a query. If set to `true`, causes the cancelation to happen silently.
## Status request response fields
**Status response fields if the ID of a specific query is not provided**
+ **acceptedQueryCount** – The number of queries that have been accepted but not yet completed, including queries in the queue.
+ **runningQueryCount** – The number of currently running openCypher queries.
+ **queries** – A list of the current openCypher queries.
**Status response fields for a specific query**
+ **queryId** – A GUID id for the query. Neptune automatically assigns this ID value to each query, or you can also assign your own ID (see [Inject a Custom ID Into a Neptune Gremlin or SPARQL Query](features-query-id.md)).
+ **queryString** – The submitted query. This is truncated to 1024 characters if it is longer than that.
+ **queryEvalStats** – Statistics for this query:
+ **waited** – Indicates how long the query waited, in milliseconds.
+ **elapsed** – The number of milliseconds the query has been running so far.
+ **cancelled** – `True` indicates that the query was cancelled, or `False` that it has not been cancelled.
## Examples of status requests and responses
+ **Request for the status of all queries, including those waiting:**
------
#### [ AWS CLI ]
```
aws neptunedata get-open-cypher-query-status \
--endpoint-url https://your-neptune-endpoint:port \
--include-waiting
```
For more information, see [get-open-cypher-query-status](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/get-open-cypher-query-status.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.get_open_cypher_query_status(
includeWaiting=True
)
print(response)
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher/status \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "includeWaiting=true"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher/status \
--data-urlencode "includeWaiting=true"
```
------
*Response:*
```
{
"acceptedQueryCount" : 0,
"runningQueryCount" : 0,
"queries" : [ ]
}
```
+ **Request for the status of running queries, **not** including those waiting:**:
------
#### [ AWS CLI ]
```
aws neptunedata get-open-cypher-query-status \
--endpoint-url https://your-neptune-endpoint:port
```
For more information, see [get-open-cypher-query-status](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/get-open-cypher-query-status.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.get_open_cypher_query_status()
print(response)
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher/status \
--region us-east-1 \
--service neptune-db
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher/status
```
------
*Response:*
```
{
"acceptedQueryCount" : 0,
"runningQueryCount" : 0,
"queries" : [ ]
}
```
+ **Request for the status of a single query:**
------
#### [ AWS CLI ]
```
aws neptunedata get-open-cypher-query-status \
--endpoint-url https://your-neptune-endpoint:port \
--query-id eadc6eea-698b-4a2f-8554-5270ab17ebee
```
For more information, see [get-open-cypher-query-status](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/get-open-cypher-query-status.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.get_open_cypher_query_status(
queryId='eadc6eea-698b-4a2f-8554-5270ab17ebee'
)
print(response)
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher/status \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "queryId=eadc6eea-698b-4a2f-8554-5270ab17ebee"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher/status \
--data-urlencode "queryId=eadc6eea-698b-4a2f-8554-5270ab17ebee"
```
------
*Response:*
```
{
"queryId" : "eadc6eea-698b-4a2f-8554-5270ab17ebee",
"queryString" : "MATCH (n1)-[:knows]->(n2), (n2)-[:knows]->(n3), (n3)-[:knows]->(n4), (n4)-[:knows]->(n5), (n5)-[:knows]->(n6), (n6)-[:knows]->(n7), (n7)-[:knows]->(n8), (n8)-[:knows]->(n9), (n9)-[:knows]->(n10) RETURN COUNT(n1);",
"queryEvalStats" : {
"waited" : 0,
"elapsed" : 23463,
"cancelled" : false
}
}
```
+ **Requests to cancel a query**
------
#### [ AWS CLI ]
```
aws neptunedata cancel-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--query-id f43ce17b-db01-4d37-a074-c76d1c26d7a9
```
For more information, see [cancel-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/cancel-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.cancel_open_cypher_query(
queryId='f43ce17b-db01-4d37-a074-c76d1c26d7a9'
)
print(response)
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher/status \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "cancelQuery" \
-d "queryId=f43ce17b-db01-4d37-a074-c76d1c26d7a9"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
1. Using `POST`:
```
curl -X POST https://your-neptune-endpoint:port/openCypher/status \
--data-urlencode "cancelQuery" \
--data-urlencode "queryId=f43ce17b-db01-4d37-a074-c76d1c26d7a9"
```
2. Using `GET`:
```
curl -X GET https://your-neptune-endpoint:port/openCypher/status \
--data-urlencode "cancelQuery" \
--data-urlencode "queryId=588af350-cfde-4222-bee6-b9cedc87180d"
```
3. Using `DELETE`:
```
curl -X DELETE \
"https://your-neptune-endpoint:port/openCypher/status?queryId=b9a516d1-d25c-4301-bb80-10b2743ecf0e"
```
------
*Response:*
```
{
"status" : "200 OK",
"payload" : true
}
```
# The Amazon Neptune OpenCypher HTTPS endpoint
**Topics**
+ [
## OpenCypher read and write queries on the HTTPS endpoint
](#access-graph-opencypher-queries-read-write)
+ [
## The default OpenCypher JSON results format
](#access-graph-opencypher-queries-results-simple-JSON)
+ [
## Optional HTTP trailing headers for multi-part OpenCypher responses
](#optional-http-trailing-headers)
**Note**
Neptune does not currently support HTTP/2 for REST API requests. Clients must use HTTP/1.1 when connecting to endpoints.
## OpenCypher read and write queries on the HTTPS endpoint
The OpenCypher HTTPS endpoint supports read and update queries using both the `GET` and the `POST` method. The `DELETE` and `PUT` methods are not supported.
The following instructions walk you through connecting to the OpenCypher endpoint using the `curl` command and HTTPS. You must follow these instructions from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB instance.
The syntax is:
```
HTTPS://(the server):(the port number)/openCypher
```
Here is a sample read query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH (n1) RETURN n1"
```
For more information, see [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='MATCH (n1) RETURN n1'
)
print(response['results'])
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH (n1) RETURN n1"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH (n1) RETURN n1"
```
------
Here is a sample write/update query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "CREATE (n:Person { age: 25 })"
```
For more information, see [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='CREATE (n:Person { age: 25 })'
)
print(response['results'])
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=CREATE (n:Person { age: 25 })"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=CREATE (n:Person { age: 25 })"
```
------
## The default OpenCypher JSON results format
The following JSON format is returned by default, or by setting the request header explicitly to `Accept: application/json`. This format is designed to be easily parsed into objects using native-language features of most libraries.
The JSON document that is returned contains one field, `results`, which contains the query return values. The examples below show the JSON formatting for common values.
**Value response example:**
```
{
"results": [
{
"count(a)": 121
}
]
}
```
**Node response example:**
```
{
"results": [
{
"a": {
"~id": "22",
"~entityType": "node",
"~labels": [
"airport"
],
"~properties": {
"desc": "Seattle-Tacoma",
"lon": -122.30899810791,
"runways": 3,
"type": "airport",
"country": "US",
"region": "US-WA",
"lat": 47.4490013122559,
"elev": 432,
"city": "Seattle",
"icao": "KSEA",
"code": "SEA",
"longest": 11901
}
}
}
]
}
```
**Relationship response example:**
```
{
"results": [
{
"r": {
"~id": "7389",
"~entityType": "relationship",
"~start": "22",
"~end": "151",
"~type": "route",
"~properties": {
"dist": 956
}
}
}
]
}
```
**Path response example:**
```
{
"results": [
{
"p": [
{
"~id": "22",
"~entityType": "node",
"~labels": [
"airport"
],
"~properties": {
"desc": "Seattle-Tacoma",
"lon": -122.30899810791,
"runways": 3,
"type": "airport",
"country": "US",
"region": "US-WA",
"lat": 47.4490013122559,
"elev": 432,
"city": "Seattle",
"icao": "KSEA",
"code": "SEA",
"longest": 11901
}
},
{
"~id": "7389",
"~entityType": "relationship",
"~start": "22",
"~end": "151",
"~type": "route",
"~properties": {
"dist": 956
}
},
{
"~id": "151",
"~entityType": "node",
"~labels": [
"airport"
],
"~properties": {
"desc": "Ontario International Airport",
"lon": -117.600997924805,
"runways": 2,
"type": "airport",
"country": "US",
"region": "US-CA",
"lat": 34.0559997558594,
"elev": 944,
"city": "Ontario",
"icao": "KONT",
"code": "ONT",
"longest": 12198
}
}
]
}
]
}
```
## Optional HTTP trailing headers for multi-part OpenCypher responses
This feature is available starting with Neptune engine release [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml).
The HTTP response to OpenCypher queries and updates is typically returned in multiple chunks. When failures occur after the initial response chunks have been sent (with an HTTP status code of 200), it can be challenging to diagnose the issue. By default, `Neptune reports such failures by appending an error message to the message body, which may be corrupted due to the streaming nature of the response.
**Using trailing headers**
To improve error detection and diagnosis, you can enable trailing headers by including a transfer-encoding (TE) trailers header (te: trailers)in your request. Doing this will cause Neptune to include two new header fields within the trailing headers of the response chunks:
+ `X-Neptune-Status` – contains the response code followed by a short name. For instance, in case of success the trailing header would be: `X-Neptune-Status: 200 OK`. In the case of failure, the response code would be a Neptune engine error code such as `X-Neptune-Status: 500 TimeLimitExceededException`.
+ `X-Neptune-Detail` – is empty for successful requests. In the case of errors, it contains the JSON error message. Because only ASCII characters are allowed in HTTP header values, the JSON string is URL encoded. The error message is also still appended to the response message body.
For more information, see the [MDN page about TE request headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/TE).
**OpenCypher trailing headers usage example**
This example demonstrates how trailing headers help diagnose a query that exceeds its time limit:
```
curl --raw 'https://your-neptune-endpoint:port/openCypher' \
-H 'TE: trailers' \
-d 'query=MATCH(n) RETURN n.firstName'
Output:
< HTTP/1.1 200 OK
< transfer-encoding: chunked
< trailer: X-Neptune-Status, X-Neptune-Detail
< content-type: application/json;charset=UTF-8
<
<
{
"results": [{
"n.firstName": "Hossein"
}, {
"n.firstName": "Jan"
}, {
"n.firstName": "Miguel"
}, {
"n.firstName": "Eric"
},
{"detailedMessage":"Operation terminated (deadline exceeded)",
"code":"TimeLimitExceededException",
"requestId":"a7e9d2aa-fbb7-486e-8447-2ef2a8544080",
"message":"Operation terminated (deadline exceeded)"}
0
X-Neptune-Status: 500 TimeLimitExceededException
X-Neptune-Detail: %7B%22detailedMessage%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%2C%22code%22%3A%22TimeLimitExceededException%22%2C%22requestId%22%3A%22a7e9d2aa-fbb7-486e-8447-2ef2a8544080%22%2C%22message%22%3A%22Operation+terminated+%28deadline+exceeded%29%22%7D
```
**Response breakdown:**
The previous example shows how an OpenCypher response with trailing headers can help diagnose query failures. Here we see four sequential parts: (1) initial headers with a 200 OK status indicating streaming begins, (2) partial (broken) JSON results successfully streamed before the failure, (3) the appended error message showing the timeout, and (4) trailing headers containing the final status (500 TimeLimitExceededException) and detailed error information.
# Using the AWS SDK to run openCypher queries
With the AWS SDK, you can run openCypher queries against your Neptune graph using a programming language of your choice. The Neptune data API SDK (service name `neptunedata`) provides the [ExecuteOpenCypherQuery](https://docs.aws.amazon.com/neptune/latest/data-api/API_ExecuteOpenCypherQuery.html) action for submitting openCypher queries.
You must run these examples from an Amazon EC2 instance in the same virtual private cloud (VPC) as your Neptune DB cluster, or from a location that has network connectivity to your cluster endpoint.
Direct links to the API reference documentation for the `neptunedata` service in each SDK language can be found below:
| Programming language | neptunedata API reference |
| --- | --- |
| C\$1\$1 | [https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-neptunedata/html/annotated.html](https://sdk.amazonaws.com/cpp/api/LATEST/aws-cpp-sdk-neptunedata/html/annotated.html) |
| Go | [https://docs.aws.amazon.com/sdk-for-go/api/service/neptunedata/](https://docs.aws.amazon.com/sdk-for-go/api/service/neptunedata/) |
| Java | [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/neptunedata/package-summary.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/neptunedata/package-summary.html) |
| JavaScript | [https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-neptunedata/](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-neptunedata/) |
| Kotlin | [https://sdk.amazonaws.com/kotlin/api/latest/neptunedata/index.html](https://sdk.amazonaws.com/kotlin/api/latest/neptunedata/index.html) |
| .NET | [https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Neptunedata/NNeptunedata.html](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Neptunedata/NNeptunedata.html) |
| PHP | [https://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.Neptunedata.html](https://docs.aws.amazon.com/aws-sdk-php/v3/api/namespace-Aws.Neptunedata.html) |
| Python | [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/neptunedata.html](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/neptunedata.html) |
| Ruby | [https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Neptunedata.html](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/Neptunedata.html) |
| Rust | [https://crates.io/crates/aws-sdk-neptunedata](https://crates.io/crates/aws-sdk-neptunedata) |
| CLI | [https://docs.aws.amazon.com/cli/latest/reference/neptunedata/](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/) |
## openCypher AWS SDK examples
The following examples show how to set up a `neptunedata` client, run an openCypher query, and print the results. Replace *YOUR\$1NEPTUNE\$1HOST* and *YOUR\$1NEPTUNE\$1PORT* with the endpoint and port of your Neptune DB cluster.
**Client-side timeout and retry configuration**
The SDK client timeout controls how long the *client* waits for a response. It does not control how long the query runs on the server. If the client times out before the server finishes, the query may continue running on Neptune while the client has no way to retrieve the results.
We recommend setting the client-side read timeout to `0` (no timeout) or to a value that is at least a few seconds longer than the server-side [neptune\$1query\$1timeout](parameters.md#parameters-db-cluster-parameters-neptune_query_timeout) setting on your Neptune DB cluster. This lets Neptune control when queries time out.
We also recommend setting the maximum retry attempts to `1` (no retries). If the SDK retries a query that is still running on the server, it can result in duplicate operations. This is especially important for mutation queries, where a retry could cause unintended duplicate writes.
------
#### [ Python ]
1. Follow the [installation instructions](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) to install Boto3.
1. Create a file named `openCypherExample.py` and paste the following code:
```
import boto3
import json
from botocore.config import Config
# Disable the client-side read timeout and retries so that
# Neptune's server-side neptune_query_timeout controls query duration.
client = boto3.client(
'neptunedata',
endpoint_url=f'https://YOUR_NEPTUNE_HOST:YOUR_NEPTUNE_PORT',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='MATCH (n) RETURN n LIMIT 1'
)
print(json.dumps(response['results'], indent=2))
```
1. Run the example: `python openCypherExample.py`
------
#### [ Java ]
1. Follow the [installation instructions](https://docs.aws.amazon.com//sdk-for-java/latest/developer-guide/setup.html) to set up the AWS SDK for Java.
1. Use the following code to set up a `NeptunedataClient`, run an openCypher query, and print the result:
```
import java.net.URI;
import java.time.Duration;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
import software.amazon.awssdk.core.retry.RetryPolicy;
import software.amazon.awssdk.services.neptunedata.NeptunedataClient;
import software.amazon.awssdk.services.neptunedata.model.ExecuteOpenCypherQueryRequest;
import software.amazon.awssdk.services.neptunedata.model.ExecuteOpenCypherQueryResponse;
// Disable the client-side timeout and retries so that
// Neptune's server-side neptune_query_timeout controls query duration.
NeptunedataClient client = NeptunedataClient.builder()
.endpointOverride(URI.create("https://YOUR_NEPTUNE_HOST:YOUR_NEPTUNE_PORT"))
.overrideConfiguration(ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ZERO)
.retryPolicy(RetryPolicy.none())
.build())
.build();
ExecuteOpenCypherQueryRequest request = ExecuteOpenCypherQueryRequest.builder()
.openCypherQuery("MATCH (n) RETURN n LIMIT 1")
.build();
ExecuteOpenCypherQueryResponse response = client.executeOpenCypherQuery(request);
System.out.println(response.results().toString());
```
------
#### [ JavaScript ]
1. Follow the [installation instructions](https://docs.aws.amazon.com//sdk-for-javascript/v3/developer-guide/getting-started-nodejs.html) to set up the AWS SDK for JavaScript. Install the neptunedata client package: `npm install @aws-sdk/client-neptunedata`.
1. Create a file named `openCypherExample.js` and paste the following code:
```
import { NeptunedataClient, ExecuteOpenCypherQueryCommand } from "@aws-sdk/client-neptunedata";
import { NodeHttpHandler } from "@smithy/node-http-handler";
const config = {
endpoint: "https://YOUR_NEPTUNE_HOST:YOUR_NEPTUNE_PORT",
// Disable the client-side request timeout so that
// Neptune's server-side neptune_query_timeout controls query duration.
requestHandler: new NodeHttpHandler({
requestTimeout: 0
}),
maxAttempts: 1
};
const client = new NeptunedataClient(config);
const input = {
openCypherQuery: "MATCH (n) RETURN n LIMIT 1"
};
const command = new ExecuteOpenCypherQueryCommand(input);
const response = await client.send(command);
console.log(JSON.stringify(response, null, 2));
```
1. Run the example: `node openCypherExample.js`
------
# Using the Bolt protocol to make openCypher queries to Neptune
[Bolt](https://boltprotocol.org/) is a statement-oriented client/server protocol initially developed by Neo4j and licensed under the Creative Commons 3.0 [Attribution-ShareAlike](https://creativecommons.org/licenses/by-sa/3.0/) license. It is client-driven, meaning that the client always initiates message exchanges.
To connect to Neptune using Neo4j's Bolt drivers, simply replace the URL and Port number with your cluster endpoints using the `bolt` URI scheme. If you have a single Neptune instance running, use the read\$1write endpoint. If multiple instances are running, then two drivers are recommended, one for the writer and another for all the read replicas. If you have only the default two endpoints, a read\$1write and a read\$1only driver are sufficient, but if you have custom endpoints as well, consider creating a driver instance for each one.
**Note**
Althought the Bolt spec states that Bolt can connect using either TCP or WebSockets, Neptune only supports TCP connections for Bolt.
Neptune allows up to 1000 concurrent Bolt connections on all instance sizes except for t3.medium and t4g.medium. On t3.medium and t4g.medium instances only 512 connections are allowed.
For examples of openCypher queries in various languages that use the Bolt drivers, see the Neo4j [Drivers & Language Guides](https://neo4j.com/developer/language-guides/) documentation.
**Important**
The Neo4j Bolt drivers for Python, .NET, JavaScript, and Golang did not initially support the automatic renewal of AWS Signature v4 authentication tokens. This means that after the signature expired (often in 5 minutes), the driver failed to authenticate, and subsequent requests failed. The Python, .NET, JavaScript, and Go examples below were all affected by this issue.
See [Neo4j Python driver issue \$1834](https://github.com/neo4j/neo4j-python-driver/issues/834), [Neo4j .NET issue \$1664](https://github.com/neo4j/neo4j-dotnet-driver/issues/664), [Neo4j JavaScript driver issue \$1993](https://github.com/neo4j/neo4j-javascript-driver/issues/993), and [Neo4j goLang driver issue \$1429](https://github.com/neo4j/neo4j-go-driver/issues/429) for more information.
As of driver version 5.8.0, a new preview re-authentication API was released for the Go driver (see [v5.8.0 - Feedback wanted on re-authentication](https://github.com/neo4j/neo4j-go-driver/discussions/482)).
## Using Bolt with Java to connect to Neptune
You can download a driver for whatever version you want to use from the Maven [MVN repository](https://mvnrepository.com/artifact/org.neo4j.driver/neo4j-java-driver), or can add this dependency to your project:
```
org.neo4j.driver
neo4j-java-driver
4.3.3
```
Then, to connect to Neptune in Java using one of these Bolt drivers, create a driver instance for the primary/writer instance in your cluster using code like the following:
```
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
final Driver driver =
GraphDatabase.driver("bolt://(your cluster endpoint URL):(your cluster port)",
AuthTokens.none(),
Config.builder().withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
```
If you have one or more reader replicas, you can similarly create a driver instance for them using code like this:
```
final Driver read_only_driver = // (without connection timeout)
GraphDatabase.driver("bolt://(your cluster endpoint URL):(your cluster port)",
Config.builder().withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
```
Or, with a timeout:
```
final Driver read_only_timeout_driver = // (with connection timeout)
GraphDatabase.driver("bolt://(your cluster endpoint URL):(your cluster port)",
Config.builder().withConnectionTimeout(30, TimeUnit.SECONDS)
.withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
```
If you have custom endpoints, it may also be worthwhile to create a driver instance for each one.
## A Python openCypher query example using Bolt
Here is how to make an openCypher query in Python using Bolt:
```
python -m pip install neo4j
```
```
from neo4j import GraphDatabase
uri = "bolt://(your cluster endpoint URL):(your cluster port)"
driver = GraphDatabase.driver(uri, auth=("username", "password"), encrypted=True)
```
Note that the `auth` parameters are ignored.
## A .NET openCypher query example using Bolt
To make an openCypher query in .NET using Bolt, the first step is to install the Neo4j driver using NuHet. To make synchronous calls, use the `.Simple` version, like this:
```
Install-Package Neo4j.Driver.Simple-4.3.0
```
```
using Neo4j.Driver;
namespace hello
{
// This example creates a node and reads a node in a Neptune
// Cluster where IAM Authentication is not enabled.
public class HelloWorldExample : IDisposable
{
private bool _disposed = false;
private readonly IDriver _driver;
private static string url = "bolt://(your cluster endpoint URL):(your cluster port)";
private static string createNodeQuery = "CREATE (a:Greeting) SET a.message = 'HelloWorldExample'";
private static string readNodeQuery = "MATCH(n:Greeting) RETURN n.message";
~HelloWorldExample() => Dispose(false);
public HelloWorldExample(string uri)
{
_driver = GraphDatabase.Driver(uri, AuthTokens.None, o => o.WithEncryptionLevel(EncryptionLevel.Encrypted));
}
public void createNode()
{
// Open a session
using (var session = _driver.Session())
{
// Run the query in a write transaction
var greeting = session.WriteTransaction(tx =>
{
var result = tx.Run(createNodeQuery);
// Consume the result
return result.Consume();
});
// The output will look like this:
// ResultSummary{Query=`CREATE (a:Greeting) SET a.message = 'HelloWorldExample".....
Console.WriteLine(greeting);
}
}
public void retrieveNode()
{
// Open a session
using (var session = _driver.Session())
{
// Run the query in a read transaction
var greeting = session.ReadTransaction(tx =>
{
var result = tx.Run(readNodeQuery);
// Consume the result. Read the single node
// created in a previous step.
return result.Single()[0].As();
});
// The output will look like this:
// HelloWorldExample
Console.WriteLine(greeting);
}
}
public void Dispose()
{
Dispose(true);
GC.SuppressFinalize(this);
}
protected virtual void Dispose(bool disposing)
{
if (_disposed)
return;
if (disposing)
{
_driver?.Dispose();
}
_disposed = true;
}
public static void Main()
{
using (var apiCaller = new HelloWorldExample(url))
{
apiCaller.createNode();
apiCaller.retrieveNode();
}
}
}
}
```
## A Java openCypher query example using Bolt with IAM authentication
The Java code below shows how to make openCypher queries in Java using Bolt with IAM authentication. The JavaDoc comment describes its usage. Once a driver instance is available, you can use it to make multiple authenticated requests.
```
package software.amazon.neptune.bolt;
import com.amazonaws.DefaultRequest;
import com.amazonaws.Request;
import com.amazonaws.auth.AWS4Signer;
import com.amazonaws.auth.AWSCredentialsProvider;
import com.amazonaws.http.HttpMethodName;
import com.google.gson.Gson;
import lombok.Builder;
import lombok.Getter;
import lombok.NonNull;
import org.neo4j.driver.Value;
import org.neo4j.driver.Values;
import org.neo4j.driver.internal.security.InternalAuthToken;
import org.neo4j.driver.internal.value.StringValue;
import java.net.URI;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import static com.amazonaws.auth.internal.SignerConstants.AUTHORIZATION;
import static com.amazonaws.auth.internal.SignerConstants.HOST;
import static com.amazonaws.auth.internal.SignerConstants.X_AMZ_DATE;
import static com.amazonaws.auth.internal.SignerConstants.X_AMZ_SECURITY_TOKEN;
/**
* Use this class instead of `AuthTokens.basic` when working with an IAM
* auth-enabled server. It works the same as `AuthTokens.basic` when using
* static credentials, and avoids making requests with an expired signature
* when using temporary credentials. Internally, it generates a new signature
* on every invocation (this may change in a future implementation).
*
* Note that authentication happens only the first time for a pooled connection.
*
* Typical usage:
*
* NeptuneAuthToken authToken = NeptuneAuthToken.builder()
* .credentialsProvider(credentialsProvider)
* .region("aws region")
* .url("cluster endpoint url")
* .build();
*
* Driver driver = GraphDatabase.driver(
* authToken.getUrl(),
* authToken,
* config
* );
*/
public class NeptuneAuthToken extends InternalAuthToken {
private static final String SCHEME = "basic";
private static final String REALM = "realm";
private static final String SERVICE_NAME = "neptune-db";
private static final String HTTP_METHOD_HDR = "HttpMethod";
private static final String DUMMY_USERNAME = "username";
@NonNull
private final String region;
@NonNull
@Getter
private final String url;
@NonNull
private final AWSCredentialsProvider credentialsProvider;
private final Gson gson = new Gson();
@Builder
private NeptuneAuthToken(
@NonNull final String region,
@NonNull final String url,
@NonNull final AWSCredentialsProvider credentialsProvider
) {
// The superclass caches the result of toMap(), which we don't want
super(Collections.emptyMap());
this.region = region;
this.url = url;
this.credentialsProvider = credentialsProvider;
}
@Override
public Map toMap() {
final Map map = new HashMap<>();
map.put(SCHEME_KEY, Values.value(SCHEME));
map.put(PRINCIPAL_KEY, Values.value(DUMMY_USERNAME));
map.put(CREDENTIALS_KEY, new StringValue(getSignedHeader()));
map.put(REALM_KEY, Values.value(REALM));
return map;
}
private String getSignedHeader() {
final Request request = new DefaultRequest<>(SERVICE_NAME);
request.setHttpMethod(HttpMethodName.GET);
request.setEndpoint(URI.create(url));
// Comment out the following line if you're using an engine version older than 1.2.0.0
request.setResourcePath("/opencypher");
final AWS4Signer signer = new AWS4Signer();
signer.setRegionName(region);
signer.setServiceName(request.getServiceName());
signer.sign(request, credentialsProvider.getCredentials());
return getAuthInfoJson(request);
}
private String getAuthInfoJson(final Request request) {
final Map obj = new HashMap<>();
obj.put(AUTHORIZATION, request.getHeaders().get(AUTHORIZATION));
obj.put(HTTP_METHOD_HDR, request.getHttpMethod());
obj.put(X_AMZ_DATE, request.getHeaders().get(X_AMZ_DATE));
obj.put(HOST, request.getHeaders().get(HOST));
obj.put(X_AMZ_SECURITY_TOKEN, request.getHeaders().get(X_AMZ_SECURITY_TOKEN));
return gson.toJson(obj);
}
}
```
## A Python openCypher query example using Bolt with IAM authentication
The Python class below lets you make openCypher queries in Python using Bolt with IAM authentication:
```
import json
from neo4j import Auth
from botocore.awsrequest import AWSRequest
from botocore.credentials import Credentials
from botocore.auth import (
SigV4Auth,
_host_from_url,
)
SCHEME = "basic"
REALM = "realm"
SERVICE_NAME = "neptune-db"
DUMMY_USERNAME = "username"
HTTP_METHOD_HDR = "HttpMethod"
HTTP_METHOD = "GET"
AUTHORIZATION = "Authorization"
X_AMZ_DATE = "X-Amz-Date"
X_AMZ_SECURITY_TOKEN = "X-Amz-Security-Token"
HOST = "Host"
class NeptuneAuthToken(Auth):
def __init__(
self,
credentials: Credentials,
region: str,
url: str,
**parameters
):
# Do NOT add "/opencypher" in the line below if you're using an engine version older than 1.2.0.0
request = AWSRequest(method=HTTP_METHOD, url=url + "/opencypher")
request.headers.add_header("Host", _host_from_url(request.url))
sigv4 = SigV4Auth(credentials, SERVICE_NAME, region)
sigv4.add_auth(request)
auth_obj = {
hdr: request.headers[hdr]
for hdr in [AUTHORIZATION, X_AMZ_DATE, X_AMZ_SECURITY_TOKEN, HOST]
}
auth_obj[HTTP_METHOD_HDR] = request.method
creds: str = json.dumps(auth_obj)
super().__init__(SCHEME, DUMMY_USERNAME, creds, REALM, **parameters)
```
You use this class to create a driver as follows:
```
authToken = NeptuneAuthToken(creds, REGION, URL)
driver = GraphDatabase.driver(URL, auth=authToken, encrypted=True)
```
## A Node.js example using IAM authentication and Bolt
The Node.js code below uses the AWS SDK for JavaScript version 3 and ES6 syntax to create a driver that authenticates requests:
```
import neo4j from "neo4j-driver";
import { HttpRequest } from "@smithy/protocol-http";
import { defaultProvider } from "@aws-sdk/credential-provider-node";
import { SignatureV4 } from "@smithy/signature-v4";
import crypto from "@aws-crypto/sha256-js";
const { Sha256 } = crypto;
import assert from "node:assert";
const region = "us-west-2";
const serviceName = "neptune-db";
const host = "(your cluster endpoint URL)";
const port = 8182;
const protocol = "bolt";
const hostPort = host + ":" + port;
const url = protocol + "://" + hostPort;
const createQuery = "CREATE (n:Greeting {message: 'Hello'}) RETURN ID(n)";
const readQuery = "MATCH(n:Greeting) WHERE ID(n) = $id RETURN n.message";
async function signedHeader() {
const req = new HttpRequest({
method: "GET",
protocol: protocol,
hostname: host,
port: port,
// Comment out the following line if you're using an engine version older than 1.2.0.0
path: "/opencypher",
headers: {
host: hostPort
}
});
const signer = new SignatureV4({
credentials: defaultProvider(),
region: region,
service: serviceName,
sha256: Sha256
});
return signer.sign(req, { unsignableHeaders: new Set(["x-amz-content-sha256"]) })
.then((signedRequest) => {
const authInfo = {
"Authorization": signedRequest.headers["authorization"],
"HttpMethod": signedRequest.method,
"X-Amz-Date": signedRequest.headers["x-amz-date"],
"Host": signedRequest.headers["host"],
"X-Amz-Security-Token": signedRequest.headers["x-amz-security-token"]
};
return JSON.stringify(authInfo);
});
}
async function createDriver() {
let authToken = { scheme: "basic", realm: "realm", principal: "username", credentials: await signedHeader() };
return neo4j.driver(url, authToken, {
encrypted: "ENCRYPTION_ON",
trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES",
maxConnectionPoolSize: 1,
// logging: neo4j.logging.console("debug")
}
);
}
async function unmanagedTxn(driver) {
const session = driver.session();
const tx = session.beginTransaction();
try {
const created = await tx.run(createQuery);
const matched = await tx.run(readQuery, { id: created.records[0].get(0) });
const msg = matched.records[0].get("n.message");
assert.equal(msg, "Hello");
await tx.commit();
} catch (err) {
// The transaction will be rolled back, now handle the error.
console.log(err);
} finally {
await session.close();
}
}
const driver = await createDriver();
try {
await unmanagedTxn(driver);
} catch (err) {
console.log(err);
} finally {
await driver.close();
}
```
## A .NET openCypher query example using Bolt with IAM authentication
To enable IAM authentication in .NET, you need to sign a request when establishing the connection. The example below shows how to create a `NeptuneAuthToken` helper to generate an authentication token:
```
using Amazon.Runtime;
using Amazon.Util;
using Neo4j.Driver;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Web;
namespace Hello
{
/*
* Use this class instead of `AuthTokens.None` when working with an IAM-auth-enabled server.
*
* Note that authentication happens only the first time for a pooled connection.
*
* Typical usage:
*
* var authToken = new NeptuneAuthToken(AccessKey, SecretKey, Region).GetAuthToken(Host);
* _driver = GraphDatabase.Driver(Url, authToken, o => o.WithEncryptionLevel(EncryptionLevel.Encrypted));
*/
public class NeptuneAuthToken
{
private const string ServiceName = "neptune-db";
private const string Scheme = "basic";
private const string Realm = "realm";
private const string DummyUserName = "username";
private const string Algorithm = "AWS4-HMAC-SHA256";
private const string AWSRequest = "aws4_request";
private readonly string _accessKey;
private readonly string _secretKey;
private readonly string _region;
private readonly string _emptyPayloadHash;
private readonly SHA256 _sha256;
public NeptuneAuthToken(string awsKey = null, string secretKey = null, string region = null)
{
var awsCredentials = awsKey == null || secretKey == null
? FallbackCredentialsFactory.GetCredentials().GetCredentials()
: null;
_accessKey = awsKey ?? awsCredentials.AccessKey;
_secretKey = secretKey ?? awsCredentials.SecretKey;
_region = region ?? FallbackRegionFactory.GetRegionEndpoint().SystemName; //ex: us-east-1
_sha256 = SHA256.Create();
_emptyPayloadHash = Hash(Array.Empty());
}
public IAuthToken GetAuthToken(string url)
{
return AuthTokens.Custom(DummyUserName, GetCredentials(url), Realm, Scheme);
}
/******************** AWS SIGNING FUNCTIONS *********************/
private string Hash(byte[] bytesToHash)
{
return ToHexString(_sha256.ComputeHash(bytesToHash));
}
private static byte[] HmacSHA256(byte[] key, string data)
{
return new HMACSHA256(key).ComputeHash(Encoding.UTF8.GetBytes(data));
}
private byte[] GetSignatureKey(string dateStamp)
{
var kSecret = Encoding.UTF8.GetBytes($"AWS4{_secretKey}");
var kDate = HmacSHA256(kSecret, dateStamp);
var kRegion = HmacSHA256(kDate, _region);
var kService = HmacSHA256(kRegion, ServiceName);
return HmacSHA256(kService, AWSRequest);
}
private static string ToHexString(byte[] array)
{
return Convert.ToHexString(array).ToLowerInvariant();
}
private string GetCredentials(string url)
{
var request = new HttpRequestMessage
{
Method = HttpMethod.Get,
RequestUri = new Uri($"https://{url}/opencypher")
};
var signedrequest = Sign(request);
var headers = new Dictionary
{
[HeaderKeys.AuthorizationHeader] = signedrequest.Headers.GetValues(HeaderKeys.AuthorizationHeader).FirstOrDefault(),
["HttpMethod"] = HttpMethod.Get.ToString(),
[HeaderKeys.XAmzDateHeader] = signedrequest.Headers.GetValues(HeaderKeys.XAmzDateHeader).FirstOrDefault(),
// Host should be capitalized, not like in Amazon.Util.HeaderKeys.HostHeader
["Host"] = signedrequest.Headers.GetValues(HeaderKeys.HostHeader).FirstOrDefault(),
};
return JsonSerializer.Serialize(headers);
}
private HttpRequestMessage Sign(HttpRequestMessage request)
{
var now = DateTimeOffset.UtcNow;
var amzdate = now.ToString("yyyyMMddTHHmmssZ");
var datestamp = now.ToString("yyyyMMdd");
if (request.Headers.Host == null)
{
request.Headers.Host = $"{request.RequestUri.Host}:{request.RequestUri.Port}";
}
request.Headers.Add(HeaderKeys.XAmzDateHeader, amzdate);
var canonicalQueryParams = GetCanonicalQueryParams(request);
var canonicalRequest = new StringBuilder();
canonicalRequest.Append(request.Method + "\n");
canonicalRequest.Append(request.RequestUri.AbsolutePath + "\n");
canonicalRequest.Append(canonicalQueryParams + "\n");
var signedHeadersList = new List();
foreach (var header in request.Headers.OrderBy(a => a.Key.ToLowerInvariant()))
{
canonicalRequest.Append(header.Key.ToLowerInvariant());
canonicalRequest.Append(':');
canonicalRequest.Append(string.Join(",", header.Value.Select(s => s.Trim())));
canonicalRequest.Append('\n');
signedHeadersList.Add(header.Key.ToLowerInvariant());
}
canonicalRequest.Append('\n');
var signedHeaders = string.Join(";", signedHeadersList);
canonicalRequest.Append(signedHeaders + "\n");
canonicalRequest.Append(_emptyPayloadHash);
var credentialScope = $"{datestamp}/{_region}/{ServiceName}/{AWSRequest}";
var stringToSign = $"{Algorithm}\n{amzdate}\n{credentialScope}\n"
+ Hash(Encoding.UTF8.GetBytes(canonicalRequest.ToString()));
var signing_key = GetSignatureKey(datestamp);
var signature = ToHexString(HmacSHA256(signing_key, stringToSign));
request.Headers.TryAddWithoutValidation(HeaderKeys.AuthorizationHeader,
$"{Algorithm} Credential={_accessKey}/{credentialScope}, SignedHeaders={signedHeaders}, Signature={signature}");
return request;
}
private static string GetCanonicalQueryParams(HttpRequestMessage request)
{
var querystring = HttpUtility.ParseQueryString(request.RequestUri.Query);
// Query params must be escaped in upper case (i.e. "%2C", not "%2c").
var queryParams = querystring.AllKeys.OrderBy(a => a)
.Select(key => $"{key}={Uri.EscapeDataString(querystring[key])}");
return string.Join("&", queryParams);
}
}
}
```
Here is how to make an openCypher query in .NET using Bolt with IAM authentication. The example below uses the `NeptuneAuthToken` helper:
```
using Neo4j.Driver;
namespace Hello
{
public class HelloWorldExample
{
private const string Host = "(your hostname):8182";
private const string Url = $"bolt://{Host}";
private const string CreateNodeQuery = "CREATE (a:Greeting) SET a.message = 'HelloWorldExample'";
private const string ReadNodeQuery = "MATCH(n:Greeting) RETURN n.message";
private const string AccessKey = "(your access key)";
private const string SecretKey = "(your secret key)";
private const string Region = "(your AWS region)"; // e.g. "us-west-2"
private readonly IDriver _driver;
public HelloWorldExample()
{
var authToken = new NeptuneAuthToken(AccessKey, SecretKey, Region).GetAuthToken(Host);
// Note that when the connection is reinitialized after max connection lifetime
// has been reached, the signature token could have already been expired (usually 5 min)
// You can face exceptions like:
// `Unexpected server exception 'Signature expired: XXXX is now earlier than YYYY (ZZZZ - 5 min.)`
_driver = GraphDatabase.Driver(Url, authToken, o =>
o.WithMaxConnectionLifetime(TimeSpan.FromMinutes(60)).WithEncryptionLevel(EncryptionLevel.Encrypted));
}
public async Task CreateNode()
{
// Open a session
using (var session = _driver.AsyncSession())
{
// Run the query in a write transaction
var greeting = await session.WriteTransactionAsync(async tx =>
{
var result = await tx.RunAsync(CreateNodeQuery);
// Consume the result
return await result.ConsumeAsync();
});
// The output will look like this:
// ResultSummary{Query=`CREATE (a:Greeting) SET a.message = 'HelloWorldExample".....
Console.WriteLine(greeting.Query);
}
}
public async Task RetrieveNode()
{
// Open a session
using (var session = _driver.AsyncSession())
{
// Run the query in a read transaction
var greeting = await session.ReadTransactionAsync(async tx =>
{
var result = await tx.RunAsync(ReadNodeQuery);
var records = await result.ToListAsync();
// Consume the result. Read the single node
// created in a previous step.
return records[0].Values.First().Value;
});
// The output will look like this:
// HelloWorldExample
Console.WriteLine(greeting);
}
}
}
}
```
This example can be launched by running the code below on `.NET 6` or `.NET 7` with the following packages:
+ **`Neo4j`**`.Driver=4.3.0`
+ **`AWSSDK`**`.Core=3.7.102.1`
```
namespace Hello
{
class Program
{
static async Task Main()
{
var apiCaller = new HelloWorldExample();
await apiCaller.CreateNode();
await apiCaller.RetrieveNode();
}
}
}
```
## A Golang openCypher query example using Bolt with IAM authentication
The Golang package below shows how to make openCypher queries in the Go language using Bolt with IAM authentication:
```
package main
import (
"context"
"encoding/json"
"fmt"
"github.com/aws/aws-sdk-go/aws/credentials"
"github.com/aws/aws-sdk-go/aws/signer/v4"
"github.com/neo4j/neo4j-go-driver/v5/neo4j"
"log"
"net/http"
"os"
"time"
)
const (
ServiceName = "neptune-db"
DummyUsername = "username"
)
// Find node by id using Go driver
func findNode(ctx context.Context, region string, hostAndPort string, nodeId string) (string, error) {
req, err := http.NewRequest(http.MethodGet, "https://"+hostAndPort+"/opencypher", nil)
if err != nil {
return "", fmt.Errorf("error creating request, %v", err)
}
// credentials must have been exported as environment variables
signer := v4.NewSigner(credentials.NewEnvCredentials())
_, err = signer.Sign(req, nil, ServiceName, region, time.Now())
if err != nil {
return "", fmt.Errorf("error signing request: %v", err)
}
hdrs := []string{"Authorization", "X-Amz-Date", "X-Amz-Security-Token"}
hdrMap := make(map[string]string)
for _, h := range hdrs {
hdrMap[h] = req.Header.Get(h)
}
hdrMap["Host"] = req.Host
hdrMap["HttpMethod"] = req.Method
password, err := json.Marshal(hdrMap)
if err != nil {
return "", fmt.Errorf("error creating JSON, %v", err)
}
authToken := neo4j.BasicAuth(DummyUsername, string(password), "")
// +s enables encryption with a full certificate check
// Use +ssc to disable client side TLS verification
driver, err := neo4j.NewDriverWithContext("bolt+s://"+hostAndPort+"/opencypher", authToken)
if err != nil {
return "", fmt.Errorf("error creating driver, %v", err)
}
defer driver.Close(ctx)
if err := driver.VerifyConnectivity(ctx); err != nil {
log.Fatalf("failed to verify connection, %v", err)
}
config := neo4j.SessionConfig{}
session := driver.NewSession(ctx, config)
defer session.Close(ctx)
result, err := session.Run(
ctx,
fmt.Sprintf("MATCH (n) WHERE ID(n) = '%s' RETURN n", nodeId),
map[string]any{},
)
if err != nil {
return "", fmt.Errorf("error running query, %v", err)
}
if !result.Next(ctx) {
return "", fmt.Errorf("node not found")
}
n, found := result.Record().Get("n")
if !found {
return "", fmt.Errorf("node not found")
}
return fmt.Sprintf("+%v\n", n), nil
}
func main() {
if len(os.Args) < 3 {
log.Fatal("Usage: go main.go (region) (host and port)")
}
region := os.Args[1]
hostAndPort := os.Args[2]
ctx := context.Background()
res, err := findNode(ctx, region, hostAndPort, "72c2e8c1-7d5f-5f30-10ca-9d2bb8c4afbc")
if err != nil {
log.Fatal(err)
}
fmt.Println(res)
}
```
## Bolt connection behavior in Neptune
Here are some things to keep in mind about Neptune Bolt connections:
+ Because Bolt connections are created at the TCP layer, you can't use an [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) in front of them, as you can with an HTTP endpoint.
+ The port that Neptune uses for Bolt connections is your DB cluster's port.
+ Based on the Bolt preamble passed to it, the Neptune server selects the highest appropriate Bolt version (1, 2, 3, or 4.0).
+ The maximum number of connections to the Neptune server that a client can have open at any point in time is 1,000.
+ If the client doesn't close a connection after a query, that connection can be used to execute the next query.
+ However, if a connection is idle for 20 minutes, the server closes it automatically.
+ If IAM authentication is not enabled, you can use `AuthTokens.none()` rather than supplying a dummy user name and password. For example, in Java:
```
GraphDatabase.driver("bolt://(your cluster endpoint URL):(your cluster port)", AuthTokens.none(),
Config.builder().withEncryption().withTrustStrategy(TrustStrategy.trustSystemCertificates()).build());
```
+ When IAM authentication is enabled, a Bolt connection is always disconnected a few minutes more than 10 days after it was established if it hasn't already closed for some other reason.
+ If the client sends a query for execution over a connection without having consumed the results of a previous query, the new query is discarded. To discard the previous results instead, the client must send a reset message over the connection.
+ Only one transaction at a time can be created on a given connection.
+ If an exception occurs during a transaction, the Neptune server rolls back the transaction and closes the connection. In this case, the driver creates a new connection for the next query.
+ Be aware that sessions are not thread-safe. Multiple parallel operations must use multiple separate sessions.
# Examples of openCypher parameterized queries
Neptune supports parameterized openCypher queries. This lets you use the same query structure multiple times with different arguments. Since the query structure doesn't change, Neptune can cache its abstract syntax tree (AST) rather than having to parse it multiple times.
## Example of an openCypher parameterized query using the HTTPS endpoint
Below is an example of using a parameterized query with the Neptune openCypher HTTPS endpoint. The query is:
```
MATCH (n {name: $name, age: $age})
RETURN n
```
The parameters are defined as follows:
```
parameters={"name": "john", "age": 20}
```
You can submit the parameterized query like this:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH (n {name: \$name, age: \$age}) RETURN n" \
--parameters '{"name": "john", "age": 20}'
```
For more information, see [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='MATCH (n {name: $name, age: $age}) RETURN n',
parameters='{"name": "john", "age": 20}'
)
print(response['results'])
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH (n {name: \$name, age: \$age}) RETURN n" \
-d 'parameters={"name": "john", "age": 20}'
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
Using `POST`:
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH (n {name: \$name, age: \$age}) RETURN n" \
-d "parameters={\"name\": \"john\", \"age\": 20}"
```
Using `GET` (URL-encoded):
```
curl -X GET \
"https://your-neptune-endpoint:port/openCypher?query=MATCH%20%28n%20%7Bname:\$name,age:\$age%7D%29%20RETURN%20n¶meters=%7B%22name%22:%22john%22,%22age%22:20%7D"
```
Using `DIRECT POST`:
```
curl -H "Content-Type: application/opencypher" \
"https://your-neptune-endpoint:port/openCypher?parameters=%7B%22name%22:%22john%22,%22age%22:20%7D" \
-d "MATCH (n {name: \$name, age: \$age}) RETURN n"
```
------
## Examples of openCypher parameterized queries using Bolt
Here is a Python example of an openCypher parameterized query using the Bolt protocol:
```
from neo4j import GraphDatabase
uri = "bolt://[neptune-endpoint-url]:8182"
driver = GraphDatabase.driver(uri, auth=("", ""))
def match_name_and_age(tx, name, age):
# Parameterized Query
tx.run("MATCH (n {name: $name, age: $age}) RETURN n", name=name, age=age)
with driver.session() as session:
# Parameters
session.read_transaction(match_name_and_age, "john", 20)
driver.close()
```
Here is a Java example of an openCypher parameterized query using the Bolt protocol:
```
Driver driver = GraphDatabase.driver("bolt+s://(your cluster endpoint URL):8182");
HashMap parameters = new HashMap<>();
parameters.put("name", "john");
parameters.put("age", 20);
String queryString = "MATCH (n {name: $name, age: $age}) RETURN n";
Result result = driver.session().run(queryString, parameters);
```
# openCypher data model
The Neptune openCypher engine builds on the same property-graph model as Gremlin. In particular:
+ Every node has one or more labels. If you insert a node without labels, a default label named `vertex` is attached. If you try to delete all of a node's labels, an error is thrown.
+ A relationship is an entity that has exactly one relationship type and that forms a unidirectional connection between two nodes (that is, *from* one of the nodes *to* the other).
+ Both nodes and relationships can have properties, but don't have to. Neptune supports nodes and relationships with zero properties.
+ Neptune does not support metaproperties, which are not included in the openCypher specification either.
+ Properties in your graph can be multi-valued if they were created using Gremlin. That is a node or relationship property can have a set of different values rather than only one. Neptune has extended openCypher semantics to handle multi-valued properties gracefully.
Supported data types are documented in [openCypher data format](bulk-load-tutorial-format-opencypher.md). However, we do not recommend inserting `Array` property values into an openCypher graph at present. Although it is possible to insert an array property value using the bulk loader, the current Neptune openCypher release treats it as a set of multi-valued properties instead of as a single list value.
Below is the list of data types supported in this release:
+ `Bool`
+ `Byte`
+ `Short`
+ `Int`
+ `Long`
+ `Float` (Includes plus and minus Infinity and NaN, but not INF)
+ `Double` (Includes plus and minus Infinity and NaN, but not INF)
+ `DateTime`
+ `String`
# The openCypher `explain` feature
The openCypher `explain` feature is a self-service tool in Amazon Neptune that helps you understand the execution approach taken by the Neptune engine. To invoke explain, you pass a parameter to an openCypher [HTTPS](access-graph-opencypher-queries.md) request with `explain=mode`, where the `mode` value can be one of the following:
****
+ **`static`** – In `static` mode, `explain` prints only the static structure of the query plan. It doesn't actually run the query.
+ **`dynamic`** – In `dynamic` mode, `explain` also runs the query, and includes dynamic aspects of the query plan. These may include the number of intermediate bindings flowing through the operators, the ratio of incoming bindings to outgoing bindings, and the total time taken by each operator.
+ **`details`** – In `details` mode, `explain` prints the information shown in dynamic mode plus additional details, such as the actual openCypher query string and the estimated range count for the pattern underlying a join operator.
For example, using `POST` with `dynamic` mode:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH (n) RETURN n LIMIT 1" \
--explain-mode dynamic
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery='MATCH (n) RETURN n LIMIT 1',
explainMode='dynamic'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH (n) RETURN n LIMIT 1" \
-d "explain=dynamic"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH (n) RETURN n LIMIT 1" \
-d "explain=dynamic"
```
------
## Limitations for openCypher `explain` in Neptune
The current release of openCypher explain has the following limitations:
+ Explain plans are currently only available for queries that perform read-only operations. Queries that perform any sort of mutation, such as `CREATE`, `DELETE`, `MERGE`, `SET` and so on, are not supported.
+ Operators and output for a specific plan may change in future releases.
## DFE operators in openCypher `explain` output
To use the information that the openCypher `explain` feature provides, you need to understand some details about how the [DFE query engine](neptune-dfe-engine.md) works (DFE being the engine that Neptune uses to process openCypher queries).
The DFE engine translates every query into a pipeline of operators. Starting from the first operator, intermediate solutions flow from one operator to the next through this operator pipeline. Each row in the explain table represents a result, up to the point of evaluation.
The operators that can appear in a DFE query plan are as follows:
**DFEApply** – Executes the function specified in the arguments section, on the value stored in the specified variable
**DFEBindRelation** – Binds together variables with the specified names
**DFEChunkLocalSubQuery** – This is a non-blocking operation that acts as a wrapper around subqueries being performed.
**DFEDistinctColumn** – Returns the distinct subset of the input values based on the variable specified.
**DFEDistinctRelation** – Returns the distinct subset of the input solutions based on the variable specified.
**DFEDrain** – Appears at the end of a subquery to act as a termination step for that subquery. The number of solutions is recorded as `Units In`. `Units Out` is always zero.
**DFEForwardValue** – Copies all input chunks directly as output chunks to be passed to its downstream operator.
**DFEGroupByHashIndex** – Performs a group-by operation over the input solutions based on a previously computed hash index (using the `DFEHashIndexBuild` operation). As an output, the given input is extended by a column containing a group key for every input solution.
**DFEHashIndexBuild** – Builds a hash index over a set of variables as a side-effect. This hash index is typically reused in later operations. See `DFEHashIndexJoin` or `DFEGroupByHashIndex` for where this hash index might be used.
**DFEHashIndexJoin** – Performs a join over the incoming solutions against a previously built hash index. See `DFEHashIndexBuild` for where this hash index might be built.
**DFEJoinExists** – Takes a left and right hand input relation, and retains values from the left relation that have a corresponding value in the right relation as defined by the given join variables.
**** – This is a non-blocking operation that acts as a wrapper for a subquery, allowing it to be run repeatedly for use in loops.
**DFEMergeChunks** – This is a blocking operation that combines chunks from its upstream operator into a single chunk of solutions to pass to its downstream operator (inverse of `DFESplitChunks`).
**DFEMinus** – Takes a left and right hand input relation, and retains values from the left relation that do not have a corresponding value in the right relation as defined by the given join variables. If there is no overlap in variables across both relations, then this operator simply returns the left hand input relation.
**DFENotExists** – Takes a left and right hand input relation, and retains values from the left relation that do not have a corresponding value in the right relation as defined by the given join variables. If there is no overlap in variables across both relations, then this operator returns an empty relation.
**DFEOptionalJoin** – Performs a left outer join (also called OPTIONAL join): solutions from the left hand side that have at least one join partner in the right-hand side are joined, and solutions from the left-hand side without join partner in the right-hand side are forwarded as is. This is a blocking operation.
**DFEPipelineJoin** – Joins the input against the tuple pattern defined by the `pattern` argument.
**DFEPipelineRangeCount** – Counts the number of solutions matching a given pattern, and returns a single one-ary solution containing the count value.
**DFEPipelineScan** – Scans the database for the given `pattern` argument, with or without a given filter on column(s).
**DFEProject** – Takes multiple input columns and projects only the desired columns.
**DFEReduce** – Performs the specified aggregation function on specified variables.
**DFERelationalJoin** – Joins the input of the previous operator based on the specified pattern keys using a merge join. This is a blocking operation.
**DFERouteChunks** – Takes input chunks from its singular incoming edge and routes those chunks along its multiple outgoing edges.
**DFESelectRows** – This operator selectively takes rows from its left input relation solutions to forward to its downstream operator. The rows selected based on the row identifiers supplied in the operator's right input relation.
**DFESerialize** – Serializes a query’s final results into a JSON string serialization, mapping each input solution to the appropriate variable name. For node and edge results, these results are serialized into a map of entity properties and metadata.
**DFESort** – Takes an input relation and produces a sorted relation based on the provided sort key.
**DFESplitByGroup** – Splits each single input chunk from one incoming edge into smaller output chunks corresponding to row groups identified by row IDs from the corresponding input chunk from the other incoming edge.
**DFESplitChunks** – Splits each single input chunk into smaller output chunks (inverse of `DFEMergeChunks`).
**DFEStreamingHashIndexBuild** – Streaming version of `DFEHashIndexBuild`.
**DFEStreamingGroupByHashIndex** – Streaming version of `DFEGroupByHashIndex`.
**DFESubquery** – This operator appears at the beginning of all plans and encapsulates the portions of the plan that are run on the [DFE engine](neptune-dfe-engine.md), which is the entire plan for openCypher.
**DFESymmetricHashJoin** – Joins the input of the previous operator based on the specified pattern keys using a hash join. This is a non-blocking operation.
**DFESync** – This operator is a synchronization operator supporting non-blocking plans. It takes solutions from two incoming edges and forwards these solutions to the appropriate downstream edges. For synchronization purposes, the inputs along one of these edges may be buffered internally.
**DFETee** – This is a branching operator that sends the same set of solutions to multiple operators.
**DFETermResolution** – Performs a localize or globalize operation on its inputs, resulting in columns of either localized or globalized identifiers respectively.
**** – Unfolds lists of values from an input column into the output column as individual elements.
**DFEUnion** – Takes two or more input relations and produces a union of those relations using the desired output schema.
**SolutionInjection** – Appears before everything else in the explain output, with a value of 1 in the Units Out column. However, it serves as a no-op, and doesn't actually inject any solutions into the DFE engine.
**TermResolution** – Appears at the end of plans and translates objects from the Neptune engine into openCypher objects.
## Columns in openCypher `explain` output
The query plan information that Neptune generates as openCypher explain output contains tables with one operator per row. The table has the following columns:
**ID** – The numeric ID of this operator in the plan.
**Out \$11** (and **Out \$12**) – The ID(s) of operator(s) that are downstream from this operator. There can be at most two downstream operators.
**Name** – The name of this operator.
**Arguments** – Any relevant details for the operator. This includes things like input schema, output schema, pattern (for `PipelineScan` and `PipelineJoin`), and so on.
**Mode** – A label describing fundamental operator behavior. This column is mostly blank (`-`). One exception is `TermResolution`, where mode can be `id2value_opencypher`, indicating a resolution from ID to openCypher value.
**Units In** – The number of solutions passed as input to this operator. Operators without upstream operators, such as `DFEPipelineScan`, `SolutionInjections`, and a `DFESubquery` with no static value injected, would have zero value.
**Units Out** – The number of solutions produced as output of this operator. `DFEDrain` is a special case, where the number of solutions being drained is recorded in `Units In` and `Units Out` is always zero.
**Ratio** – The ratio of `Units Out` to `Units In`.
**Time (ms)** – The CPU time consumed by this operator, in milliseconds.
## A basic example of openCypher explain output
The following is a basic example of openCypher `explain` output. The query is a single-node lookup in the air routes dataset for a node with the airport code `ATL` that invokes `explain` using the `details` mode in default ASCII output format.
To invoke `explain` for this query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH (n {code: 'ATL'}) RETURN n" \
--explain-mode details
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery="MATCH (n {code: 'ATL'}) RETURN n",
explainMode='details'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH (n {code: 'ATL'}) RETURN n" \
-d "explain=details"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH (n {code: 'ATL'}) RETURN n" \
-d "explain=details"
```
------
The `explain` output:
```
Query:
MATCH (n {code: 'ATL'}) RETURN n
╔════╤════════╤════════╤═══════════════════╤════════════════════╤═════════════════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪════════════════════╪═════════════════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ SolutionInjection │ solutions=[{}] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFESubquery │ subQuery=subQuery1 │ - │ 0 │ 1 │ 0.00 │ 4.00 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ TermResolution │ vars=[?n] │ id2value_opencypher │ 1 │ 1 │ 1.00 │ 2.00 ║
╚════╧════════╧════════╧═══════════════════╧════════════════════╧═════════════════════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery1
╔════╤════════╤════════╤═══════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFEPipelineScan │ pattern=Node(?n) with property 'code' as ?n_code2 and label 'ALL' │ - │ 0 │ 1 │ 0.00 │ 0.21 ║
║ │ │ │ │ inlineFilters=[(?n_code2 IN ["ATL"^^xsd:string])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=1 │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#9d84f97c-c3b0-459a-98d5-955a8726b159/graph_1 │ - │ 1 │ 1 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 3 │ - │ DFEProject │ columns=[?n] │ - │ 1 │ 1 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.03 ║
╚════╧════════╧════════╧═══════════════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#9d84f97c-c3b0-459a-98d5-955a8726b159/graph_1
╔════╤════════╤════════╤══════════════════════╤════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪══════════════════════╪════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFESolutionInjection │ outSchema=[?n, ?n_code2] │ - │ 0 │ 1 │ 0.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ 3 │ DFETee │ - │ - │ 1 │ 2 │ 2.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 4 │ - │ DFEDistinctColumn │ column=?n │ - │ 1 │ 1 │ 1.00 │ 0.20 ║
║ │ │ │ │ ordered=false │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 5 │ - │ DFEHashIndexBuild │ vars=[?n] │ - │ 1 │ 1 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEPipelineJoin │ pattern=Node(?n) with property 'ALL' and label '?n_label1' │ - │ 1 │ 1 │ 1.00 │ 0.25 ║
║ │ │ │ │ patternEstimate=3506 │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ 6 │ 7 │ DFESync │ - │ - │ 2 │ 2 │ 1.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 6 │ 8 │ - │ DFEForwardValue │ - │ - │ 1 │ 1 │ 1.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 7 │ 8 │ - │ DFEForwardValue │ - │ - │ 1 │ 1 │ 1.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 8 │ 9 │ - │ DFEHashIndexJoin │ - │ - │ 2 │ 1 │ 0.50 │ 0.35 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 9 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.02 ║
╚════╧════════╧════════╧══════════════════════╧════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
```
At the top-level, `SolutionInjection` appears before everything else, with 1 unit out. Note that it doesn't actually inject any solutions. You can see that the next operator, `DFESubquery`, has 0 units in.
After `SolutionInjection` at the top-level are `DFESubquery` and `TermResolution` operators. `DFESubquery` encapsulates the parts of the query execution plan that is being pushed to the [DFE engine](neptune-dfe-engine.md) (for openCypher queries, the entire query plan is executed by the DFE). All the operators in the query plan are nested inside `subQuery1` that is referenced by `DFESubquery`. The only exception is `TermResolution`, which materializes internal IDs into fully serialized openCypher objects.
All the operators that are pushed down to the DFE engine have names that start with a `DFE` prefix. As mentioned above, the whole openCypher query plan is executed by the DFE, so as a result, all the operators except the final `TermResolution` operator start with `DFE`.
Inside `subQuery1`, there can be zero or more `DFEChunkLocalSubQuery` or `DFELoopSubQuery` operators that encapsulate a part of the pushed execution plan that is executed in a memory-bounded mechanism. `DFEChunkLocalSubQuery` here contains one `SolutionInjection` that is used as an input to the subquery. To find the table for that subquery in the output, search for the `subQuery=graph URI` specified in the `Arguments` column for the `DFEChunkLocalSubQuery` or `DFELoopSubQuery` operator.
In `subQuery1`, `DFEPipelineScan` with `ID` 0 scans the database for a specified `pattern`. The pattern scans for an entity with property `code` saved as a variable `?n_code2` over all labels (you could filter on a specific label by appending `airport` to `n:airport`). The `inlineFilters` argument shows the filtering for the `code` property equalling `ATL`.
Next, the `DFEChunkLocalSubQuery` operator joins the intermediate results of a subquery that contains `DFEPipelineJoin`. This ensures that `?n` is actually a node, since the previous `DFEPipelineScan` scans for any entity with the `code` property.
# Example of `explain` output for a relationship lookup with a limit
This query looks for relationships between two anonymous nodes with type `route`, and returns at most 10. Again, the `explain` mode is `details` and the output format is the default ASCII format.
Here, `DFEPipelineScan` scans for edges that start from anonymous node `?anon_node7` and end at another anonymous node `?anon_node21`, with a relationship type saved as `?p_type1`. There is a filter for `?p_type1` being `el://route` (where `el` stands for edge label), which corresponds to `[p:route]` in the query string.
`DFEDrain` collects the output solution with a limit of 10, as shown in its `Arguments` column. `DFEDrain` terminates once the limit is reached or the all solutions are produced, whichever happens first.
To invoke `explain` for this query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH ()-[p:route]->() RETURN p LIMIT 10" \
--explain-mode details
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery='MATCH ()-[p:route]->() RETURN p LIMIT 10',
explainMode='details'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH ()-[p:route]->() RETURN p LIMIT 10" \
-d "explain=details"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH ()-[p:route]->() RETURN p LIMIT 10" \
-d "explain=details"
```
------
The `explain` output:
```
Query:
MATCH ()-[p:route]->() RETURN p LIMIT 10
╔════╤════════╤════════╤═══════════════════╤════════════════════╤═════════════════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪════════════════════╪═════════════════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ SolutionInjection │ solutions=[{}] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFESubquery │ subQuery=subQuery1 │ - │ 0 │ 10 │ 0.00 │ 5.00 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ TermResolution │ vars=[?p] │ id2value_opencypher │ 10 │ 10 │ 1.00 │ 1.00 ║
╚════╧════════╧════════╧═══════════════════╧════════════════════╧═════════════════════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery1
╔════╤════════╤════════╤═════════════════╤═══════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═════════════════╪═══════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFEPipelineScan │ pattern=Edge((?anon_node7)-[?p:?p_type1]->(?anon_node21)) │ - │ 0 │ 1000 │ 0.00 │ 0.66 ║
║ │ │ │ │ inlineFilters=[(?p_type1 IN [])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=26219 │ │ │ │ │ ║
╟────┼────────┼────────┼─────────────────┼───────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEProject │ columns=[?p] │ - │ 1000 │ 1000 │ 1.00 │ 0.14 ║
╟────┼────────┼────────┼─────────────────┼───────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ DFEDrain │ limit=10 │ - │ 1000 │ 0 │ 0.00 │ 0.11 ║
╚════╧════════╧════════╧═════════════════╧═══════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
```
# Example of `explain` output for a value expression function
The function is:
```
MATCH (a) RETURN DISTINCT labels(a)
```
In the `explain` output below, `DFEPipelineScan` (ID 0) scans for all the node labels. This corresponds to `MATCH (a`).
`DFEChunkLocalSubquery` (ID 1) aggregates the label of `?a` for each `?a`. This corresponds to `labels(a)`. You can see that through `DFEApply` and `DFEReduce`.
`BindRelation` (ID 2) is used to rename the column generic `?__gen_labelsOfa2` into `?labels(a)`.
`DFEDistinctRelation` (ID 4) retrieves only the distinct labels (multiple :airport nodes would give duplicate labels(a): ["airport"]). This corresponds to `DISTINCT labels(a)`.
To invoke `explain` for this query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH (a) RETURN DISTINCT labels(a)" \
--explain-mode details
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery='MATCH (a) RETURN DISTINCT labels(a)',
explainMode='details'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH (a) RETURN DISTINCT labels(a)" \
-d "explain=details"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH (a) RETURN DISTINCT labels(a)" \
-d "explain=details"
```
------
The `explain` output:
```
Query:
MATCH (a) RETURN DISTINCT labels(a)
╔════╤════════╤════════╤═══════════════════╤════════════════════╤═════════════════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪════════════════════╪═════════════════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ SolutionInjection │ solutions=[{}] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFESubquery │ subQuery=subQuery1 │ - │ 0 │ 5 │ 0.00 │ 81.00 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ TermResolution │ vars=[?labels(a)] │ id2value_opencypher │ 5 │ 5 │ 1.00 │ 1.00 ║
╚════╧════════╧════════╧═══════════════════╧════════════════════╧═════════════════════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery1
╔════╤════════╤════════╤═══════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFEPipelineScan │ pattern=Node(?a) with property 'ALL' and label '?a_label1' │ - │ 0 │ 3750 │ 0.00 │ 26.77 ║
║ │ │ │ │ patternEstimate=3506 │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#8b314f55-2cc7-456a-a48a-c76a0465cfab/graph_1 │ - │ 3750 │ 3750 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 3 │ - │ DFEBindRelation │ inputVars=[?a, ?__gen_labelsOfa2, ?__gen_labelsOfa2] │ - │ 3750 │ 3750 │ 1.00 │ 0.08 ║
║ │ │ │ │ outputVars=[?a, ?__gen_labelsOfa2, ?labels(a)] │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 4 │ - │ DFEProject │ columns=[?labels(a)] │ - │ 3750 │ 3750 │ 1.00 │ 0.05 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEDistinctRelation │ - │ - │ 3750 │ 5 │ 0.00 │ 2.78 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ - │ - │ DFEDrain │ - │ - │ 5 │ 0 │ 0.00 │ 0.03 ║
╚════╧════════╧════════╧═══════════════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#8b314f55-2cc7-456a-a48a-c76a0465cfab/graph_1
╔════╤════════╤════════╤══════════════════════╤════════════════════════════════════════════════════════════╤══════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪══════════════════════╪════════════════════════════════════════════════════════════╪══════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFESolutionInjection │ outSchema=[?a] │ - │ 0 │ 3750 │ 0.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ 3 │ DFETee │ - │ - │ 3750 │ 7500 │ 2.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 4 │ - │ DFEProject │ columns=[?a] │ - │ 3750 │ 3750 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 17 │ - │ DFEOptionalJoin │ - │ - │ 7500 │ 3750 │ 0.50 │ 0.44 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEDistinctRelation │ - │ - │ 3750 │ 3750 │ 1.00 │ 2.23 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ 6 │ - │ DFEDistinctColumn │ column=?a │ - │ 3750 │ 3750 │ 1.00 │ 1.50 ║
║ │ │ │ │ ordered=false │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 6 │ 7 │ - │ DFEPipelineJoin │ pattern=Node(?a) with property 'ALL' and label '?a_label3' │ - │ 3750 │ 3750 │ 1.00 │ 10.58 ║
║ │ │ │ │ patternEstimate=3506 │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 7 │ 8 │ 9 │ DFETee │ - │ - │ 3750 │ 7500 │ 2.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 8 │ 10 │ - │ DFEBindRelation │ inputVars=[?a_label3] │ - │ 3750 │ 3750 │ 1.00 │ 0.04 ║
║ │ │ │ │ outputVars=[?100] │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 9 │ 11 │ - │ DFEBindRelation │ inputVars=[?a, ?a_label3, ?100] │ - │ 7500 │ 3750 │ 0.50 │ 0.07 ║
║ │ │ │ │ outputVars=[?a, ?a_label3, ?100] │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 10 │ 9 │ - │ DFETermResolution │ column=?100 │ id2value │ 3750 │ 3750 │ 1.00 │ 7.60 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 11 │ 12 │ - │ DFEBindRelation │ inputVars=[?a, ?a_label3, ?100] │ - │ 3750 │ 3750 │ 1.00 │ 0.06 ║
║ │ │ │ │ outputVars=[?a, ?100, ?a_label3] │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 12 │ 13 │ - │ DFEApply │ functor=nodeLabel(?a_label3) │ - │ 3750 │ 3750 │ 1.00 │ 0.55 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 13 │ 14 │ - │ DFEProject │ columns=[?a, ?a_label3_alias4] │ - │ 3750 │ 3750 │ 1.00 │ 0.05 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 14 │ 15 │ - │ DFEMergeChunks │ - │ - │ 3750 │ 3750 │ 1.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 15 │ 16 │ - │ DFEReduce │ functor=collect(?a_label3_alias4) │ - │ 3750 │ 3750 │ 1.00 │ 6.37 ║
║ │ │ │ │ segmentationKey=[?a] │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 16 │ 3 │ - │ DFEMergeChunks │ - │ - │ 3750 │ 3750 │ 1.00 │ 0.03 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────────┼──────────┼───────────┼───────┼───────────╢
║ 17 │ - │ - │ DFEDrain │ - │ - │ 3750 │ 0 │ 0.00 │ 0.02 ║
╚════╧════════╧════════╧══════════════════════╧════════════════════════════════════════════════════════════╧══════════╧══════════╧═══════════╧═══════╧═══════════╝
```
# Example of `explain` output for a mathematical value expression function
In this example, `RETURN abs(-10)` performs a simple evaluation, taking the absolute value of a constant, `-10`.
`DFEChunkLocalSubQuery` (ID 1) performs a solution injection for the static value `-10`, which is stored in the variable, `?100`.
`DFEApply` (ID 2) is the operator that executes the absolute value function `abs()` on the static value stored in `?100` variable.
Here is the query and resulting `explain` output.
To invoke `explain` for this query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "RETURN abs(-10)" \
--explain-mode details
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery='RETURN abs(-10)',
explainMode='details'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=RETURN abs(-10)" \
-d "explain=details"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=RETURN abs(-10)" \
-d "explain=details"
```
------
The `explain` output:
```
Query:
RETURN abs(-10)
╔════╤════════╤════════╤═══════════════════╤═══════════════════════╤═════════════════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪═══════════════════════╪═════════════════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ SolutionInjection │ solutions=[{}] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼───────────────────┼───────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFESubquery │ subQuery=subQuery1 │ - │ 0 │ 1 │ 0.00 │ 4.00 ║
╟────┼────────┼────────┼───────────────────┼───────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ TermResolution │ vars=[?_internalVar1] │ id2value_opencypher │ 1 │ 1 │ 1.00 │ 1.00 ║
╚════╧════════╧════════╧═══════════════════╧═══════════════════════╧═════════════════════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery1
╔════╤════════╤════════╤═══════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFESolutionInjection │ outSchema=[] │ - │ 0 │ 1 │ 0.00 │ 0.01 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#c4cc6148-cce3-4561-93c0-deb91f257356/graph_1 │ - │ 1 │ 1 │ 1.00 │ 0.03 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 3 │ - │ DFEApply │ functor=abs(?100) │ - │ 1 │ 1 │ 1.00 │ 0.26 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 4 │ - │ DFEBindRelation │ inputVars=[?_internalVar2, ?_internalVar2] │ - │ 1 │ 1 │ 1.00 │ 0.04 ║
║ │ │ │ │ outputVars=[?_internalVar2, ?_internalVar1] │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEProject │ columns=[?_internalVar1] │ - │ 1 │ 1 │ 1.00 │ 0.06 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.05 ║
╚════╧════════╧════════╧═══════════════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#c4cc6148-cce3-4561-93c0-deb91f257356/graph_1
╔════╤════════╤════════╤══════════════════════╤═════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪══════════════════════╪═════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFESolutionInjection │ solutions=[?100 -> [-10^^]] │ - │ 0 │ 1 │ 0.00 │ 0.01 ║
║ │ │ │ │ outSchema=[?100] │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼─────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 3 │ - │ DFERelationalJoin │ joinVars=[] │ - │ 2 │ 1 │ 0.50 │ 0.18 ║
╟────┼────────┼────────┼──────────────────────┼─────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 1 │ - │ DFESolutionInjection │ outSchema=[] │ - │ 0 │ 1 │ 0.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼─────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.02 ║
╚════╧════════╧════════╧══════════════════════╧═════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
```
# Example of `explain` output for a variable-length path (VLP) query
This is an example of a more complex query plan for handling a variable-length path query. This example only shows part of the `explain` output, for clarity.
In `subQuery1`, `DFEPipelineScan` (ID 0) and `DFEChunkLocalSubQuery` (ID 1), which injects the `...graph_1` subquery, are responsible for scanning for a node with the `YPO` code.
In `subQuery1`, `DFEChunkLocalSubQuery` (ID 2), which injects the `...graph_2` subquery, is responsible for scanning for a node with the `LAX` code.
In `subQuery1`, `DFEChunkLocalSubQuery` (ID 3) injects the `...graph3` subquery, which contains `DFELoopSubQuery` (ID 17), which in turn injects the `...graph5` subquery. This operation is responsible for resolving the `-[*2]->` variable-length pattern in the query string between two nodes.
To invoke `explain` for this query:
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-explain-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "MATCH p=(a {code: 'YPO'})-[*2]->(b{code: 'LAX'}) return p" \
--explain-mode details
```
For more information, see [execute-open-cypher-explain-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-explain-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_explain_query(
openCypherQuery="MATCH p=(a {code: 'YPO'})-[*2]->(b{code: 'LAX'}) return p",
explainMode='details'
)
print(response['results'].read().decode('utf-8'))
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=MATCH p=(a {code: 'YPO'})-[*2]->(b{code: 'LAX'}) return p" \
-d "explain=details"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=MATCH p=(a {code: 'YPO'})-[*2]->(b{code: 'LAX'}) return p" \
-d "explain=details"
```
------
The `explain` output:
```
Query:
MATCH p=(a {code: 'YPO'})-[*2]->(b{code: 'LAX'}) return p
╔════╤════════╤════════╤═══════════════════╤════════════════════╤═════════════════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════╪════════════════════╪═════════════════════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ SolutionInjection │ solutions=[{}] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFESubquery │ subQuery=subQuery1 │ - │ 0 │ 0 │ 0.00 │ 84.00 ║
╟────┼────────┼────────┼───────────────────┼────────────────────┼─────────────────────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ - │ - │ TermResolution │ vars=[?p] │ id2value_opencypher │ 0 │ 0 │ 0.00 │ 0 ║
╚════╧════════╧════════╧═══════════════════╧════════════════════╧═════════════════════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery1
╔════╤════════╤════════╤═══════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFEPipelineScan │ pattern=Node(?a) with property 'code' as ?a_code7 and label 'ALL' │ - │ 0 │ 1 │ 0.00 │ 0.68 ║
║ │ │ │ │ inlineFilters=[(?a_code7 IN ["YPO"^^xsd:string])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=1 │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_1 │ - │ 1 │ 1 │ 1.00 │ 0.03 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 3 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_2 │ - │ 1 │ 1 │ 1.00 │ 0.02 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 4 │ - │ DFEChunkLocalSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_3 │ - │ 1 │ 0 │ 0.00 │ 0.04 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEBindRelation │ inputVars=[?__gen_path6, ?anon_rel26, ?b_code8, ?b, ?a_code7, ?a, ?__gen_path6] │ - │ 0 │ 0 │ 0.00 │ 0.10 ║
║ │ │ │ │ outputVars=[?__gen_path6, ?anon_rel26, ?b_code8, ?b, ?a_code7, ?a, ?p] │ │ │ │ │ ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ 6 │ - │ DFEProject │ columns=[?p] │ - │ 0 │ 0 │ 0.00 │ 0.05 ║
╟────┼────────┼────────┼───────────────────────┼──────────────────────────────────────────────────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 6 │ - │ - │ DFEDrain │ - │ - │ 0 │ 0 │ 0.00 │ 0.02 ║
╚════╧════════╧════════╧═══════════════════════╧══════════════════════════════════════════════════════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_1
╔════╤════════╤════════╤══════════════════════╤════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪══════════════════════╪════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFESolutionInjection │ outSchema=[?a, ?a_code7] │ - │ 0 │ 1 │ 0.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ 3 │ DFETee │ - │ - │ 1 │ 2 │ 2.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 4 │ - │ DFEDistinctColumn │ column=?a │ - │ 1 │ 1 │ 1.00 │ 0.25 ║
║ │ │ │ │ ordered=false │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 5 │ - │ DFEHashIndexBuild │ vars=[?a] │ - │ 1 │ 1 │ 1.00 │ 0.05 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ 5 │ - │ DFEPipelineJoin │ pattern=Node(?a) with property 'ALL' and label '?a_label1' │ - │ 1 │ 1 │ 1.00 │ 0.47 ║
║ │ │ │ │ patternEstimate=3506 │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 5 │ 6 │ 7 │ DFESync │ - │ - │ 2 │ 2 │ 1.00 │ 0.04 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 6 │ 8 │ - │ DFEForwardValue │ - │ - │ 1 │ 1 │ 1.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 7 │ 8 │ - │ DFEForwardValue │ - │ - │ 1 │ 1 │ 1.00 │ 0.01 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 8 │ 9 │ - │ DFEHashIndexJoin │ - │ - │ 2 │ 1 │ 0.50 │ 0.26 ║
╟────┼────────┼────────┼──────────────────────┼────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 9 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.02 ║
╚════╧════════╧════════╧══════════════════════╧════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_2
╔════╤════════╤════════╤══════════════════════╤═══════════════════════════════════════════════════════════════════╤══════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪══════════════════════╪═══════════════════════════════════════════════════════════════════╪══════╪══════════╪═══════════╪═══════╪═══════════╣
║ 0 │ 1 │ - │ DFEPipelineScan │ pattern=Node(?b) with property 'code' as ?b_code8 and label 'ALL' │ - │ 0 │ 1 │ 0.00 │ 0.38 ║
║ │ │ │ │ inlineFilters=[(?b_code8 IN ["LAX"^^xsd:string])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=1 │ │ │ │ │ ║
╟────┼────────┼────────┼──────────────────────┼───────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 1 │ 2 │ - │ DFEMergeChunks │ - │ - │ 1 │ 1 │ 1.00 │ 0.02 ║
╟────┼────────┼────────┼──────────────────────┼───────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 2 │ 4 │ - │ DFERelationalJoin │ joinVars=[] │ - │ 2 │ 1 │ 0.50 │ 0.19 ║
╟────┼────────┼────────┼──────────────────────┼───────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 3 │ 2 │ - │ DFESolutionInjection │ outSchema=[?a, ?a_code7] │ - │ 0 │ 1 │ 0.00 │ 0 ║
╟────┼────────┼────────┼──────────────────────┼───────────────────────────────────────────────────────────────────┼──────┼──────────┼───────────┼───────┼───────────╢
║ 4 │ - │ - │ DFEDrain │ - │ - │ 1 │ 0 │ 0.00 │ 0.01 ║
╚════╧════════╧════════╧══════════════════════╧═══════════════════════════════════════════════════════════════════╧══════╧══════════╧═══════════╧═══════╧═══════════╝
subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_3
╔════╤════════╤════════╤═══════════════════════╤══════════════════════════════════════════════════════════════════════════════════════════════════════════════╤══════════╤══════════╤═══════════╤═══════╤═══════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠════╪════════╪════════╪═══════════════════════╪══════════════════════════════════════════════════════════════════════════════════════════════════════════════╪══════════╪══════════╪═══════════╪═══════╪═══════════╣
...
║ 17 │ 18 │ - │ DFELoopSubQuery │ subQuery=http://aws.amazon.com/neptune/vocab/v01/dfe/past/graph#cc05129f-d07e-4622-bbe3-9e99558eca46/graph_5 │ - │ 1 │ 2 │ 2.00 │ 0.31 ║
...
```
# Transactions in Neptune openCypher
The openCypher implementation in Amazon Neptune uses the [transaction semantics defined by Neptune](transactions-neptune.md) However, isolation levels provided by the Bolt driver have some specific implications for Bolt transaction semantics, as described in the sections below.
## Read-only Bolt transaction queries
There are various ways that read-only queries can be processed, with different transaction models and isolation levels, as follows:
### Implicit read-only transaction queries
Here is an example of a read-only implicit transaction:
```
public void executeReadImplicitTransaction()
{
// end point
final String END_POINT = "(End Point URL)";
// read query
final String READ_QUERY = "MATCH (n) RETURN n limit 10";
// create the driver
final Driver driver = GraphDatabase.driver(END_POINT, AuthTokens.none(),
Config.builder().withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
// create the session config
SessionConfig sessionConfig = SessionConfig.builder()
.withFetchSize(1000)
.withDefaultAccessMode(AccessMode.READ)
.build();
// run the query as access mode read
driver.session(sessionConfig).readTransaction(new TransactionWork()
{
final StringBuilder resultCollector = new StringBuilder();
@Override
public String execute(final Transaction tx)
{
// execute the query
Result queryResult = tx.run(READ_QUERY);
// Read the result
for (Record record : queryResult.list())
{
for (String key : record.keys())
{
resultCollector.append(key)
.append(":")
.append(record.get(key).asNode().toString());
}
}
return resultCollector.toString();
}
}
);
// close the driver.
driver.close();
}
```
Because read-replicas only accept read-only queries, all queries against read-replicas execute as read-implicit transactions regardless of the access mode set in the session configuration. Neptune evaluates read-implicit transactions as [read-only queries](transactions-neptune.md#transactions-neptune-read-only) under `SNAPSHOT` isolation semantics.
In case of failure, read-implicit transactions are retried by default.
### Autocommit read-only transaction queries
Here is an example of a read-only autocommit transaction:
```
public void executeAutoCommitTransaction()
{
// end point
final String END_POINT = "(End Point URL)";
// read query
final String READ_QUERY = "MATCH (n) RETURN n limit 10";
// Create the session config.
final SessionConfig sessionConfig = SessionConfig
.builder()
.withFetchSize(1000)
.withDefaultAccessMode(AccessMode.READ)
.build();
// create the driver
final Driver driver = GraphDatabase.driver(END_POINT, AuthTokens.none(),
Config.builder()
.withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
// result collector
final StringBuilder resultCollector = new StringBuilder();
// create a session
final Session session = driver.session(sessionConfig);
// run the query
final Result queryResult = session.run(READ_QUERY);
for (final Record record : queryResult.list())
{
for (String key : record.keys())
{
resultCollector.append(key)
.append(":")
.append(record.get(key).asNode().toString());
}
}
// close the session
session.close();
// close the driver
driver.close();
}
```
If the access mode is set to `READ` in the session configuration, Neptune evaluates autocommit transaction queries as [read-only queries](transactions-neptune.md#transactions-neptune-read-only) under `SNAPSHOT` isolation semantics. Note that read-replicas only accept read-only queries.
If you don't pass in a session configuration, autocommit queries are processed by default with mutation query isolation, so it is important to pass in a session configuration that explicitly sets the access mode to `READ`.
In case of failure, read-only autocommit queries are not re-tried.
### Explicit read-only transaction queries
Here is an example of an explicit read-only transaction:
```
public void executeReadExplicitTransaction()
{
// end point
final String END_POINT = "(End Point URL)";
// read query
final String READ_QUERY = "MATCH (n) RETURN n limit 10";
// Create the session config.
final SessionConfig sessionConfig = SessionConfig
.builder()
.withFetchSize(1000)
.withDefaultAccessMode(AccessMode.READ)
.build();
// create the driver
final Driver driver = GraphDatabase.driver(END_POINT, AuthTokens.none(),
Config.builder()
.withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
// result collector
final StringBuilder resultCollector = new StringBuilder();
// create a session
final Session session = driver.session(sessionConfig);
// begin transaction
final Transaction tx = session.beginTransaction();
// run the query on transaction
final List list = tx.run(READ_QUERY).list();
// read the result
for (final Record record : list)
{
for (String key : record.keys())
{
resultCollector
.append(key)
.append(":")
.append(record.get(key).asNode().toString());
}
}
// commit the transaction and for rollback we can use beginTransaction.rollback();
tx.commit();
// close the driver
driver.close();
}
```
If the access mode is set to `READ` in the session configuration, Neptune evaluates explicit read-only transactions as [read-only queries](transactions-neptune.md#transactions-neptune-read-only) under `SNAPSHOT` isolation semantics. Note that read-replicas only accept read-only queries.
If you don't pass in a session configuration, explicit read-only transactions are processed by default with mutation query isolation, so it is important to pass in a session configuration that explicitly sets the access mode to `READ`.
In case of failure, read-only explicit queries are retried by default.
## Mutation Bolt transaction queries
As with read-only queries, there are various ways that mutation queries can be processed, with different transaction models and isolation levels, as follows:
### Implicit mutation transaction queries
Here is an example of an implicit mutation transaction:
```
public void executeWriteImplicitTransaction()
{
// end point
final String END_POINT = "(End Point URL)";
// create node with label as label and properties.
final String WRITE_QUERY = "CREATE (n:label {name : 'foo'})";
// Read the vertex created with label as label.
final String READ_QUERY = "MATCH (n:label) RETURN n";
// create the driver
final Driver driver = GraphDatabase.driver(END_POINT, AuthTokens.none(),
Config.builder()
.withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
// create the session config
SessionConfig sessionConfig = SessionConfig
.builder()
.withFetchSize(1000)
.withDefaultAccessMode(AccessMode.WRITE)
.build();
final StringBuilder resultCollector = new StringBuilder();
// run the query as access mode write
driver.session(sessionConfig).writeTransaction(new TransactionWork()
{
@Override
public String execute(final Transaction tx)
{
// execute the write query and consume the result.
tx.run(WRITE_QUERY).consume();
// read the vertex written in the same transaction
final List list = tx.run(READ_QUERY).list();
// read the result
for (final Record record : list)
{
for (String key : record.keys())
{
resultCollector
.append(key)
.append(":")
.append(record.get(key).asNode().toString());
}
}
return resultCollector.toString();
}
}); // at the end, the transaction is automatically committed.
// close the driver.
driver.close();
}
```
Reads made as part of mutation queries are executed under `READ COMMITTED` isolation with the usual guarantees for [Neptune mutation transactions](transactions-neptune.md#transactions-neptune-mutation).
Whether or not you specifically pass in a session configuration, the transaction is always treated as a write transaction.
For conflicts, see [Conflict Resolution Using Lock-Wait Timeouts](transactions-neptune.md#transactions-neptune-conflicts).
### Autocommit mutation transaction queries
Mutation autocommit queries inherit the same behavior as mutation implicit transactions.
If you do not pass in a session configuration, the transaction is treated as a write transaction by default.
In case of failure, mutation autocommit queries are not automatically retried.
### Explicit mutation transaction queries
Here is an example of an explicit mutation transaction:
```
public void executeWriteExplicitTransaction()
{
// end point
final String END_POINT = "(End Point URL)";
// create node with label as label and properties.
final String WRITE_QUERY = "CREATE (n:label {name : 'foo'})";
// Read the vertex created with label as label.
final String READ_QUERY = "MATCH (n:label) RETURN n";
// create the driver
final Driver driver = GraphDatabase.driver(END_POINT, AuthTokens.none(),
Config.builder()
.withEncryption()
.withTrustStrategy(TrustStrategy.trustSystemCertificates())
.build());
// create the session config
SessionConfig sessionConfig = SessionConfig
.builder()
.withFetchSize(1000)
.withDefaultAccessMode(AccessMode.WRITE)
.build();
final StringBuilder resultCollector = new StringBuilder();
final Session session = driver.session(sessionConfig);
// run the query as access mode write
final Transaction tx = driver.session(sessionConfig).beginTransaction();
// execute the write query and consume the result.
tx.run(WRITE_QUERY).consume();
// read the result from the previous write query in a same transaction.
final List list = tx.run(READ_QUERY).list();
// read the result
for (final Record record : list)
{
for (String key : record.keys())
{
resultCollector
.append(key)
.append(":")
.append(record.get(key).asNode().toString());
}
}
// commit the transaction and for rollback we can use tx.rollback();
tx.commit();
// close the session
session.close();
// close the driver.
driver.close();
}
```
Explicit mutation queries inherit the same behavior as implicit mutation transactions.
If you do not pass in a session configuration, the transaction is treated as a write transaction by default.
For conflicts, see [Conflict Resolution Using Lock-Wait Timeouts](transactions-neptune.md#transactions-neptune-conflicts).
# openCypher query hints
**Important**
openCypher query hint is only available from engine release [1.3.2.0](https://docs.aws.amazon.com//neptune/latest/userguide/engine-releases-1.3.2.0.html) and later.
In Amazon Neptune, you can use the `USING` clause to specify query hints for openCypher queries. These hints allow you to control optimization and evaluation strategies.
The syntax for query hints is:
```
USING {scope}:{hint} {value}
```
1. `{scope}` defines the scope in which the hint applies to: `Query` or `Clause`.
A scope value of `Query` means that the query hint applies to the whole query (query-level).
A scope value of `Clause` means that the query hint applies to the clause the hint precedes (clause-level).
1. `{hint}` is the name of the query hint being applied.
1. `{value}` is the argument for the `{hint}`.
The values can be case-insensitive.
For example, to enable the query plan cache for a query:
```
Using QUERY:PLANCACHE "enabled"
MATCH (a:Person {firstName: "Erin", lastName: $lastName})
RETURN a
```
**Note**
Currently, the **Query** scope query hints **PLANCACHE**, **TIMEOUTMILLISECONDS**, and **assumeConsistentDataTypes** are supported. Supported query hints are listed below.
**Topics**
+ [
# openCypher query plan cache hint
](opencypher-query-hints-qpc-hint.md)
+ [
# AssumeConsistentDataTypes hint
](opencypher-query-hints-AssumeConsistentDataTypes.md)
+ [
# openCypher query timeout hint
](opencypher-query-hints-timeout-hint.md)
# openCypher query plan cache hint
Query plan cache behavior can be overridden on a per-query (parameterized or not) basis by query-level query hint `QUERY:PLANCACHE`. It needs to be used with the `USING` clause. The query hint accepts `enabled` or `disabled` as a value. For more information on query plan cache, see [Query plan cache in Amazon Neptune](access-graph-qpc.md).
------
#### [ AWS CLI ]
Forcing plan to be cached or reused:
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"
```
With parameters:
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
--parameters '{"arg": 123}'
```
Forcing plan to be neither cached nor reused:
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "Using QUERY:PLANCACHE \"disabled\" MATCH(n) RETURN n LIMIT 1"
```
For more information, see [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
# Forcing plan to be cached or reused
response = client.execute_open_cypher_query(
openCypherQuery='Using QUERY:PLANCACHE "enabled" MATCH(n) RETURN n LIMIT 1'
)
print(response['results'])
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
Forcing plan to be cached or reused:
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
Forcing plan to be cached or reused:
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=Using QUERY:PLANCACHE \"enabled\" MATCH(n) RETURN n LIMIT 1"
```
With parameters:
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=Using QUERY:PLANCACHE \"enabled\" RETURN \$arg" \
-d "parameters={\"arg\": 123}"
```
Forcing plan to be neither cached nor reused:
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=Using QUERY:PLANCACHE \"disabled\" MATCH(n) RETURN n LIMIT 1"
```
------
# AssumeConsistentDataTypes hint
openCypher follows a paradigm where matches of numerical datatypes (e.g., int, byte, short, long, etc.) are carried out under type promotion semantics. For instance, when looking up all properties with an input value 10 with short type, under type promotion semantics, it would also match properties that have 10 as a long value. In some cases, type casting can induce overhead and result in query plans that are less efficient than they could be if no type casting was performed. In particular in cases where datatypes are used consistently in the data (e.g., if all person’s ages are stored as long value) performing type promotions causes overhead without impacting the query result.
To allow optimization for cases when it is known that numeric property data values stored in the database are of consistent type, a query hint called `assumeConsistentDataTypes` (with value `true/false`, with the default being `false`) can be used. When this query hint is supplied with a value of `true`, the engine assumes the only property values are always long or double and will skip the type promotion semantics. Numerical values specified in the query are considered to be either long values (for non-floating point values) and double (for floating point values).
If the data is consistently using a single datatype (e.g. all ages are stored as `long`), then using the `assumeConsistentDataTypes` hint can optimize the query by skipping unnecessary equality checks for different numeric types. However, if the data has inconsistent datatypes for the same property, then using the hint may cause some results to be missed, as the query will only match the single datatype that the hint assumes.
```
# Database loaded with following openCypher CSV's
# File 1
:ID,age:Int
n1,20
n2,25
# File 2
:ID,age:Long
n3,25
# Example (no hint)
MATCH (n:Person)
WHERE n.age >= 25
RETURN n
# Result
n2
n3
Returns all person whose age is >= 25 and the values >= 25 can be with any of these datatypes
i.e. byte, short, int, long, double or float
-----------------------------------------------------------------------------------
# Example (with hint present)
USING QUERY:assumeConsistentDataTypes "true"
MATCH (n:Person)
WHERE n.age >= 25
RETURN n
# Result
n3
Returns only "n3" and not "n2". The reason is that even though the numerical value
matches (25), the datatype is "int" and is considered a non-match.
```
The difference can also be validated via the explain.
Without the explain:
```
# Query
MATCH (n)
WHERE n.age = 20
RETURN n
# Explain Snippet
╔═════╤══════════╤══════════╤══════════════════════════════╤═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╤════════╤════════════╤══════════════╤═════════╤══════════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠═════╪══════════╪══════════╪══════════════════════════════╪═══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╪════════╪════════════╪══════════════╪═════════╪══════════════╣
║ 0 │ 1 │ - │ DFEPipelineScan (DFX) │ pattern=Node(?n) with property 'age' as ?n_age2 and label 'ALL' │ - │ 0 │ 1 │ 0.00 │ 0.10 ║
║ │ │ │ │ inlineFilters=[(?n_age2 IN ["20"^^xsd:byte, "20"^^xsd:int, "20"^^xsd:long, "20"^^xsd:short, "20.0"^^xsd:double, "20.0"^^xsd:float])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=1 │ │ │ │ │ ║
╟─────┼──────────┼──────────┼──────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼────────┼────────────┼──────────────┼─────────┼──────────────╢
# The inFilters field contains all numeric types
```
With the hint:
```
# Query
MATCH (n)
WHERE n.age = 20
RETURN n
# Explain Snippet
╔═════╤══════════╤══════════╤══════════════════════════════╤═════════════════════════════════════════════════════════════════════════════════╤════════╤════════════╤══════════════╤═════════╤══════════════╗
║ ID │ Out #1 │ Out #2 │ Name │ Arguments │ Mode │ Units In │ Units Out │ Ratio │ Time (ms) ║
╠═════╪══════════╪══════════╪══════════════════════════════╪═════════════════════════════════════════════════════════════════════════════════╪════════╪════════════╪══════════════╪═════════╪══════════════╣
║ 0 │ 1 │ - │ DFEPipelineScan (DFX) │ pattern=Node(?n) with property 'age' as ?n_age2 and label 'ALL' │ - │ 0 │ 1 │ 0.00 │ 0.07 ║
║ │ │ │ │ inlineFilters=[(?n_age2 IN ["20"^^xsd:long])] │ │ │ │ │ ║
║ │ │ │ │ patternEstimate=1 │ │ │ │ │ ║
╟─────┼──────────┼──────────┼──────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────┼────────┼────────────┼──────────────┼─────────┼──────────────╢
# The inFilters field only contains long datatype
```
# openCypher query timeout hint
Query timeout behavior can be configured on a per-query basis by query-level query hint `QUERY:TIMEOUTMILLISECONDS`. It must be used with the `USING` clause. The query hint accepts non-negative long as a value.
------
#### [ AWS CLI ]
```
aws neptunedata execute-open-cypher-query \
--endpoint-url https://your-neptune-endpoint:port \
--open-cypher-query "USING QUERY:TIMEOUTMILLISECONDS 100 MATCH(n) RETURN n LIMIT 1"
```
For more information, see [execute-open-cypher-query](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/execute-open-cypher-query.html) in the AWS CLI Command Reference.
------
#### [ SDK ]
```
import boto3
from botocore.config import Config
client = boto3.client(
'neptunedata',
endpoint_url='https://your-neptune-endpoint:port',
config=Config(read_timeout=None, retries={'total_max_attempts': 1})
)
response = client.execute_open_cypher_query(
openCypherQuery='USING QUERY:TIMEOUTMILLISECONDS 100 MATCH(n) RETURN n LIMIT 1'
)
print(response['results'])
```
For AWS SDK examples in other languages, see [AWS SDK](access-graph-opencypher-sdk.md).
------
#### [ awscurl ]
```
awscurl https://your-neptune-endpoint:port/openCypher \
--region us-east-1 \
--service neptune-db \
-X POST \
-d "query=USING QUERY:TIMEOUTMILLISECONDS 100 MATCH(n) RETURN n LIMIT 1"
```
**Note**
This example assumes that your AWS credentials are configured in your environment. Replace *us-east-1* with the Region of your Neptune cluster.
------
#### [ curl ]
```
curl https://your-neptune-endpoint:port/openCypher \
-d "query=USING QUERY:TIMEOUTMILLISECONDS 100 MATCH(n) RETURN n LIMIT 1"
```
------
Query timeout behavior will consider the minimum of cluster-level timeout and query-level timeout. Please see below examples to understand query timeout behavior. For more information on cluster-level query timeout, see [neptune\$1query\$1timeout](https://docs.aws.amazon.com/neptune/latest/userguide/parameters.html#parameters-db-cluster-parameters-neptune_query_timeout).
```
# Suppose `neptune_query_timeout` is 10000 ms and query-level timeout is set to 100 ms
# It will consider 100 ms as the final timeout
curl https://your-neptune-endpoint:port/openCypher \
-d "query=USING QUERY:TIMEOUTMILLISECONDS 100 MATCH(n) RETURN n LIMIT 1"
# Suppose `neptune_query_timeout` is 100 ms and query-level timeout is set to 10000 ms
# It will still consider 100 ms as the final timeout
curl https://your-neptune-endpoint:port/openCypher \
-d "query=USING QUERY:TIMEOUTMILLISECONDS 10000 MATCH(n) RETURN n LIMIT 1"
```
# Neptune openCypher restrictions
The Amazon Neptune release of openCypher still does not support everything that is specified in the [Cypher Query Language Reference, Version 9](https://s3.amazonaws.com/artifacts.opencypher.org/openCypher9.pdf), as is detailed in [openCypher specification compliance](feature-opencypher-compliance.md). Future releases are expected to address many of those limitations.
# Neptune openCypher exceptions
When working with openCypher on Amazon Neptune, a variety of exceptions may occur. Below are common exceptions you may receive, either from the HTTPS endpoint or from the Bolt driver (all exceptions from the Bolt driver are reported as Server State Exceptions):
| HTTP code | Error message | Retriable? | Remedy |
| --- | --- | --- | --- |
| 400 | *(syntax error, propagated directly from the openCypher parser)* | No | Correct query syntax, then retry. |
| 500 | `Operation terminated (out of memory)` | Yes | Rework the query to add additional filtering criteria to reduce required memory |
| 500 | Operation terminated (deadline exceeded) | Yes | Increase the query timeout in the DB cluster parameter group, or [retry the request](https://docs.aws.amazon.com/general/latest/gr/api-retries.html). |
| 500 | Operation terminated (cancelled by user) | Yes | Retry the request. |
| 500 | Database reset is in progress. Please retry the query after the cluster is available. | Yes | Retry when the reset is completed. |
| 500 | Operation failed due to conflicting concurrent operations (please retry). Transactions are currently rolling back. | Yes | Retry using an [exponential backoff and retry strategy](best-practices-opencypher-retry-logic.md). |
| 400 | *(operation name)* operation/feature unsupported Exception | No | The specified operation is not supported. |
| 400 | openCypher update attempted on a read-only replica | No | Change the target end point to the writer end point. |
| 400 | MalformedQueryException (Neptune does not show the internal parser state) | No | Correct query syntax and retry. |
| 400 | Cannot delete node, because it still has relationships. To delete this node, you must first delete its relationships. | No | Instead of using `MATCH (n) DELETE n` use `MATCH(n) DETACH DELETE(n)` |
| 400 | Invalid operation: attempting to remove the last label of a node. A node must have at least one label. | No | Neptune requires all nodes to have at least one label, and if nodes are created without an explicit label, a default label `vertex` is assigned. Change the query and/or application logic so as not to delete the last label. A singleton label of a node can be updated by setting a new label and then removing the old label. |
| 500 | Max number of request have breached, ConfiguredQueueCapacity=\$1\$1 for connId = \$1\$1 | Yes | Currently only 8,192 concurrent requests can be processed, regardless of the stack and protocol. |
| 500 | Max connection limit breached. | Yes | Only 1000 concurrent Bolt connections per instance are allowed (for HTTP there is no limit). |
| 400 | Expected a [one of: Node, Relationship or Path] and got a Literal | No | Check that you are passing the correct argument(s), correct query syntax, and retry. |
| 400 | Property value must be a simple literal. Or: Expected Map for Set properties but didn't find one. | No | A SET clause only accepts simple literals, not composite types. |
| 400 | Entity found passed for deletion is not found | No | Check that the entity you are trying to delete exists in the database. |
| 400 | User does not have access to the database. | No | Check the policy on the IAM role being used. |
| 400 | There is no token passed as part of the request | No | A properly signed token must be passed as part of the query request on an IAM enabled cluster. |
| 400 | Error message is propagated. | No | Contact AWS Support with the Request Id. |
| 500 | Operation terminated (internal error) | Yes | Contact AWS Support with the Request Id. |
# openCypher extensions in Amazon Neptune
Amazon Neptune supports the openCypher specification reference version 9. Please refer to [openCypher specification compliance in Amazon Neptune](feature-opencypher-compliance.md) in Amazon Neptune for details. Additionally, Amazon Neptune supports the features listed here. Unless specific versions are mentioned, the features are available in Neptune Database and Neptune Analytics.
## Query-time S3 data access
Available in Neptune Database 1.4.7.0 and up.
Neptune supports the `neptune.read()` function to read CSV or Parquet data from Amazon S3 directly within openCypher queries. Unlike the bulk loader which imports data before querying, `neptune.read()` accesses Amazon S3 data at query execution time.
For complete documentation, see [neptune.read()](access-graph-opencypher-21-extensions-s3-read.md).
## The Neptune-specific `join()` function
Available in Neptune Database and Neptune Analytics.
Neptune implements a `join()` function that is not present in the openCypher specification. It creates a string literal from a list of string literals and a string delimiter. It takes two arguments:
+ The first argument is a list of string literals.
+ The second argument is the delimiter string, which can consist of zero, one, or more than one characters.
Example:
```
join(["abc", "def", "ghi"], ", ") // Returns "abc, def, ghi"
```
## The Neptune-specific `removeKeyFromMap()` function
Available in Neptune Database and Neptune Analytics.
Neptune implements a `removeKeyFromMap()` function that is not present in the openCypher specification. It removes a specified key from a map and returns the resulting new map.
The function takes two arguments:
+ The first argument is the map from which to remove the key.
+ The second argument is the key to remove from the map.
The `removeKeyFromMap()` function is particularly useful in situations where you want to set values for a node or relationship by unwinding a list of maps. For example:
```
UNWIND [{`~id`: 'id1', name: 'john'}, {`~id`: 'id2', name: 'jim'}] as val
CREATE (n {`~id`: val.`~id`})
SET n = removeKeyFromMap(val, '~id')
```
## Custom ID values for node and relationship properties
Available in Neptune Database 1.2.0.2 and up, and Neptune Analytics.
Starting in [engine release 1.2.0.2](engine-releases-1.2.0.2.md), Neptune has extended the openCypher specification so that you can now specify the `id` values for nodes and relationships in `CREATE`, `MERGE`, and `MATCH` clauses. This lets you assign user-friendly strings instead of system-generated UUIDs to identify nodes and relationships.
In Neptune Analytics, custom id values are not available for edges.
**Warning**
This extension to the openCypher specification is backward incompatible, because `~id` is now considered a reserved property name. If you are already using `~id` as a property in your data and queries, you will need to migrate the existing property to a new property key and remove the old one. See [What to do if you're currently using `~id` as a property](#opencypher-compliance-custom-ids-migrating).
Here is an example showing how to create nodes and relationships that have custom IDS:
```
CREATE (n {`~id`: 'fromNode', name: 'john'})
-[:knows {`~id`: 'john-knows->jim', since: 2020}]
->(m {`~id`: 'toNode', name: 'jim'})
```
If you try to create a custom ID that is already in use, Neptune throws a `DuplicateDataException` error.
Here is an example of using a custom ID in a `MATCH` clause:
```
MATCH (n {`~id`: 'id1'})
RETURN n
```
Here is an example of using custom IDs in a `MERGE` clause:
```
MATCH (n {name: 'john'}), (m {name: 'jim'})
MERGE (n)-[r {`~id`: 'john->jim'}]->(m)
RETURN r
```
### What to do if you're currently using `~id` as a property
With [engine release 1.2.0.2](engine-releases-1.2.0.2.md), the `~id` key in openCypher clauses is now treated as `id` instead of as a property. This means that if you have a property named `~id`, accessing it becomes impossible.
If you're using an `~id` property, what you have to do before upgrading to engine release `1.2.0.2` or above is first to migrate the existing `~id` property to a new property key, and then remove the `~id` property. For example, the query below:
+ Creates a new property named 'newId' for all nodes,
+ copies over the value of the '\$1id' property into the 'newId' property,
+ and removes the '\$1id' property from the data
```
MATCH (n)
WHERE exists(n.`~id`)
SET n.newId = n.`~id`
REMOVE n.`~id`
```
The same thing needs to be done for any relationships in the data that have an `~id` property.
You will also have to change any queries you're using that reference an `~id` property. For example, this query:
```
MATCH (n)
WHERE n.`~id` = 'some-value'
RETURN n
```
...would change to this:
```
MATCH (n)
WHERE n.newId = 'some-value'
RETURN n
```
## CALL subquery support in Neptune
Available in Neptune Database 1.4.1.0 and up, and Neptune Analytics.
Amazon Neptune supports `CALL` subqueries. A `CALL` subquery is a part of the main query that runs in an isolated scope for each input to the `CALL` subquery.
For example, suppose a graph contains data about persons, their friends, and cities they lived in. We can retrieve the two largest cities where each friend of someone lived in by using a `CALL` subquery:
```
MATCH (person:Person)-[:knows]->(friend)
CALL {
WITH friend
MATCH (friend)-[:lived_in]->(city)
RETURN city
ORDER BY city.population DESC
LIMIT 2
}
RETURN person, friend, city
```
In this example, the query part inside `CALL { ... }` is executed for each `friend` that is matched by the preceding MATCH clause. When the inner query is executed the `ORDER` and `LIMIT` clauses are local to the cities where a specific friend lived in, so we obtain (at most) two cities per friend.
All query clauses are available inside `CALL` subqueries. This includes nested `CALL` subqueries as well. Some restrictions for the first `WITH` clause and the emitted variables exist and are explained below.
### Scope of variables inside CALL subquery
The variables from the clauses before the `CALL` subquery that are used inside it must be imported by the initial `WITH` clause. Unlike regular `WITH` clauses it can only contain a list of variables but doesn't allow aliasing and can't be used together with `DISTINCT`, `ORDER BY`, `WHERE`, `SKIP`, or `LIMIT`.
### Variables returned from CALL subquery
The variables that are emitted from the `CALL` subquery are specified with the final `RETURN` clause. Note that the emitted variables cannot overlap with variables before the `CALL` subquery.
### Limitations
As of now, updates inside of a `CALL` subquery are not supported.
## Neptune openCypher functions
Available in Neptune Database 1.4.1.0 and up, and Neptune Analytics.
**textIndexOf**
`textIndexOf(text :: STRING, lookup :: STRING, from = 0 :: INTEGER?, to = -1 :: INTEGER?) :: (INTEGER?)`
Returns the index of the first occurrence of `lookup` in the range of `text` starting at offset `from` (inclusive), through offset `to` (exclusive). If `to` is -1, the range continues to the end of `text`. Indexing is zero-based, and is expressed in Unicode scalar values (non-surrogate code points).
```
RETURN textIndexOf('Amazon Neptune', 'e')
{
"results": [{
"textIndexOf('Amazon Neptune', 'e')": 8
}]
}
```
**collToSet**
`collToSet(values :: LIST OF ANY?) :: (LIST? OF ANY?)`
Returns a new list containing only the unique elements from the original list. The order of the original list is **maintained** (e.g `[1, 6, 5, 1, 5]` returns `[1, 6, 5]`).
```
RETURN collToSet([1, 6, 5, 1, 1, 5])
{
"results": [{
"collToSet([1, 6, 5, 1, 1, 5])": [1, 6, 5]
}]
}
```
**collSubtract**
`collSubtract(first :: LIST OF ANY?, second :: LIST OF ANY?) :: (LIST? OF ANY?)`
Returns a new list containing all the unique elements of `first` excluding elements from `second`.
```
RETURN collSubtract([2, 5, 1, 0], [1, 5])
{
"results": [{
"collSubtract([2, 5, 1, 0], [1, 5])": [0, 2]
}]
}
```
**collIntersection**
`collIntersection(first :: LIST? OF ANY?, second :: LIST? OF ANY?) :: (LIST? OF ANY?)`
Returns a new list containing all the unique elements of the intersection of `first` and `second`.
```
RETURN collIntersection([2, 5, 1, 0], [1, 5])
{
"results": [{
"collIntersection([2, 5, 1, 0], [1, 5])": [1, 5]
}]
}
```
## Sorting functions
The following sections define functions to sort collections. These functions take (in some cases optional) `config` map arguments, or a list of multiple such maps, that define the sort key and/or the sort direction:
```
{ key: STRING, order: STRING }
```
Here `key` is either a map or node property whose value is to be used for sorting. `order` is either "`asc`" or "`desc`" (case insensitive) to specify an ascending or descending sort, respectively. By default, sorting will be performed in ascending order.
**collSort**
`collSort(coll :: LIST OF ANY, config :: MAP?) :: (LIST? OF ANY?)`
Returns a new sorted list containing the elements from the `coll` input list.
```
RETURN collSort([5, 3, 1], {order: 'asc'})
{
"results": [{
"collSort([5, 3, 1])": [1, 3, 5]
}]
}
```
**collSortMaps**
`collSortMaps(coll :: LIST OF MAP, config :: MAP) :: (LIST? OF ANY?)`
Returns a list of maps sorted by the value of the specified `key` property.
```
RETURN collSortMaps([{name: 'Alice', age: 25}, {name: 'Bob', age: 35}, {name: 'Charlie', age: 18}], {key: 'age', order: 'desc'})
{
"results": [{
"x": [{
"age": 35,
"name": "Bob"
}, {
"age": 25,
"name": "Alice"
}, {
"age": 18,
"name": "Charlie"
}]
}]
}
```
**collSortMulti**
```
collSortMulti(coll :: LIST OF MAP?,
configs = [] :: LIST OF MAP,
limit = -1 :: INTEGER?,
skip = 0 :: INTEGER?) :: (LIST? OF ANY?)
```
Returns a list of maps sorted by the value of the specified `key` properties, optionally applying limit and skip.
```
RETURN collSortMulti([{name: 'Alice', age: 25}, {name: 'Bob', age: 35}, {name: 'Charlie', age: 18}], [{key: 'age', order: 'desc'}, {key:'name'}]) as x
{
"results": [{
"x": [{
"age": 35,
"name": "Bob"
}, {
"age": 25,
"name": "Alice"
}, {
"age": 18,
"name": "Charlie"
}]
}]
}
```
**collSortNodes**
`collSortNodes(coll :: LIST OF NODE, config :: MAP) :: (LIST? OF NODE?)`
Returns a sorted version of the `coll` input list, sorting the node elements by the values of their respective `key` properties.
```
create (n:person {name: 'Alice', age: 23}), (m:person {name: 'Eve', age: 21}), (o:person {name:'Bob', age:25})
{"results":[]}
match (n:person) with collect(n) as people return collSortNodes(people, {key: 'name', order: 'desc'})
{
"results": [{
"collSortNodes(people, 'name')": [{
"~id": "e599240a-8c23-4337-8aa8-f603c8fb5488",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 21,
"name": "Eve"
}
}, {
"~id": "8a6ef785-59e3-4a0b-a0ff-389655a9c4e6",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 25,
"name": "Bob"
}
}, {
"~id": "466bc826-f47f-452c-8a27-6b7bdf7ae9b4",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 23,
"name": "Alice"
}
}]
}]
}
match (n:person) with collect(n) as people return collSortNodes(people, {key: 'age'})
{
"results": [{
"collSortNodes(people, '^age')": [{
"~id": "e599240a-8c23-4337-8aa8-f603c8fb5488",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 21,
"name": "Eve"
}
}, {
"~id": "466bc826-f47f-452c-8a27-6b7bdf7ae9b4",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 23,
"name": "Alice"
}
}, {
"~id": "8a6ef785-59e3-4a0b-a0ff-389655a9c4e6",
"~entityType": "node",
"~labels": ["person"],
"~properties": {
"age": 25,
"name": "Bob"
}
}]
}]
}
```
## Temporal functions
Temporal functions are available from Neptune version [1.4.5.0](https://docs.aws.amazon.com/releases/release-1.4.5.0.xml) and up.
### day
`day(temporal :: (datetime | date)) :: (LONG)`
Returns the `day` of the month from a `datetime` or `date` value. For `datetime`: values are normalized to UTC based on input before extracting the day. For `date`: day is extracted based on the timezone.
The `datetime` input is available in both Neptune Database and Neptune Analytics:
```
RETURN day(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"day(datetime('2021-06-03T01:48:14Z'))": 3
}]
}
```
Here, the `datetime` is normalized to UTC, so \$108:00 shifts back to June 2.
```
RETURN day(datetime('2021-06-03T00:00:00+08:00'))
{
"results": [{
"day(datetime('2021-06-03T00:00:00+08:00'))": 2
}]
}
```
The `date` input is available only in Neptune Analytics:
```
RETURN day(date('2021-06-03Z'))
{
"results": [{
"day(date('2021-06-03Z'))": 3
}]
}
```
The `date` preserves timezone, keeping June 3.
```
RETURN day(date('2021-06-03+08:00'))
{
"results": [{
"day(date('2021-06-03+08:00'))": 3
}]
}
```
### month
`month(temporal :: (datetime | date)) :: (LONG)`
Returns the month from a `datetime` or `date` value (1-12). For `datetime`: values are normalized to UTC based on input before extracting the month. For `date`: month is extracted based on the timezone.
The `datetime` input is available in both Neptune Database and Neptune Analytics:
```
RETURN month(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"month(datetime('2021-06-03T01:48:14Z'))": 6
}]
}
```
Here, the `datetime` is normalized to UTC, so \$108:00 shifts back to May 31.
```
RETURN month(datetime('2021-06-01T00:00:00+08:00'))
{
"results": [{
"month(datetime('2021-06-01T00:00:00+08:00'))": 5
}]
}
```
The `date` input is available only in Neptune Analytics:
```
RETURN month(date('2021-06-03Z'))
{
"results": [{
"month(date('2021-06-03Z'))": 6
}]
}
```
The `date` preserves timezone, keeping June 1.
```
RETURN month(date('2021-06-01+08:00'))
{
"results": [{
"month(date('2021-06-01+08:00'))": 6
}]
}
```
### year
`year(temporal :: (datetime | date)) :: (LONG)`
Returns the year from a `datetime` or `date` value. For `datetime`: the values are normalized to UTC based on input before extracting the year. For `date`: the year is extracted based on the timezone.
The `datetime` input is available in both Neptune Database and Neptune Analytics:
```
RETURN year(datetime('2021-06-03T01:48:14Z'))
{
"results": [{
"year(datetime('2021-06-03T01:48:14Z'))": 2021
}]
}
```
Here, the `datetime` is normalized to UTC, so \$108:00 shifts back to December 31, 2020.
```
RETURN year(datetime('2021-01-01T00:00:00+08:00'))
{
"results": [{
"year(datetime('2021-01-01T00:00:00+08:00'))": 2020
}]
}
```
The `date` input is available only in Neptune Analytics:
```
RETURN year(date('2021-06-03Z'))
{
"results": [{
"year(date('2021-06-03Z'))": 2021
}]
}
```
The `date` preserves timezone, keeping June 2021.
```
RETURN year(date('2021-01-01+08:00'))
{
"results": [{
"year(date('2021-01-01+08:00'))": 2021
}]
}
```
### Neptune openCypher functions
Available in Neptune Database 1.4.6.0 and up, and Neptune Analytics.
#### reduce()
Reduce sequentially processes each list element by combining it with a running total or ‘accumulator.’ Starting with an initial value, it updates the accumulator after each operation and uses that updated value in the next iteration.
`for i in (0, ..., n) acc = acc X list[I], where X denotes any binary operator`
Once all elements have been processed, it returns the final accumulated result.
A typical reduce() structure would be - `reduce(accumulator = initial , variable IN list | expression)`
**Type specifications:**
`- initial: starting value for the accumulator :: (Long | FLOAT | STRING | LIST? OF (STRING, LONG, FLOAT)) - list: the input list :: LIST OF T where T matches initial type - variable :: represents each element in the input list - expression :: Only supports '+' and '*' operator - return :: Same type as initial `
**Restrictions:**
Currently, the `reduce()` expression only supports :
+ Numeric Multiplication
+ Numeric Addition
+ String Concatenation
+ List Concatenation
They are represented by the `+` or `*` operator. The expression should be a binary expression as specified below - `expression pattern: accumulator + any variable or accumulator * any variable`
**Overflow handling:**
Neptune detects numeric overflow during the `reduce()` evaluation and responds differently based on the data type:
```
LONG (signed 64‑bit)
--------------------
• Valid range: –9 223 372 036 854 775 808 … 9 223 372 036 854 775 807
• If any intermediate or final value falls outside this range,
Neptune aborts the query with long overflow error message.
FLOAT (IEEE‑754 double)
-----------------------
• Largest finite value ≈ 1.79 × 10^308
• Larger results overflow to INF
Once `INF` is produced, it propagates through the remainder
of the reduction.
```
**Examples:**
See the following examples for the reduce() function.
```
1. Long Addition:
RETURN reduce(sum = 0, n IN [1, 2, 3] | sum + n)
{
"results": [{
"reduce(sum = 0, n IN [1, 2, 3] | sum + n)": 6
}]
}
2. String Concatenation:
RETURN reduce(str = "", x IN ["A", "B", "C"] | str + x)
{
"results": [{
"reduce(str = "", x IN ["A", "B", "C"] | str + x)": "ABC"
}]
}
3. List Combination:
RETURN reduce(lst = [], x IN [1, 2, 3] | lst + x)
{
"results": [{
"reduce(lst = [], x IN [1, 2, 3] | lst + x)": [1, 2, 3]
}]
}
4. Float Addition:
RETURN reduce(total = 0.0, x IN [1.5, 2.5, 3.5] | total + x)
{
"results": [{
"reduce(total = 0.0, x IN [1.5, 2.5, 3.5] | total + x)": 7.5
}]
}
5. Long Multiplication:
RETURN reduce(product = 1, n IN [1, 2, 3] | product * n)
{
"results": [{
"reduce(product = 0, n IN [1, 2, 3] | product * n)": 6
}]
}
6. Float Multiplication:
RETURN reduce(product = 1.0, n IN [1.5, 2.5, 3.5] | product * n)
{
"results": [{
"reduce(product = 1.0, n IN [1.5, 2.5, 3.5] | product * n)": 13.125
}]
}
7. Long Overflow (Exception):
RETURN reduce(s = 9223372036854775807, x IN [2, 3] | s * x) AS result
{
"results": [{
"reduce(s = 9223372036854775807, x IN [2, 3] | s * x) AS result": long overflow
}]
}
8. Float Overflow:
RETURN reduce(s = 9.0e307, x IN [8.0e307, 1.0e307] | s + x) AS result
{
"results": [{
"reduce(s = 9.0e307, x IN [8.0e307, 1.0e307] | s + x) AS result": INF
}]
}
```
# neptune.read()
Neptune supports a `CALL` procedure `neptune.read` to read data from Amazon S3 and then run an openCypher query (read, insert, update) using the data. The procedure yields each row in the file as a declared result variable row. It uses the IAM credentials of the caller to access the data in Amazon S3. See [Managing permissions for neptune.read()](access-graph-opencypher-21-extensions-s3-read-permissions.md) to set up the permissions. The AWS region of the Amazon S3 bucket must be in the same region where instance is located. Currently, cross-region reads are not supported.
**Syntax**
```
CALL neptune.read(
{
source: "string",
format: "parquet/csv",
concurrency: 10
}
)
YIELD row
...
```
**Inputs**
+ **source** (required) - Amazon S3 URI to a **single** object. Amazon S3 prefix to multiple objects is not supported.
+ **format** (required) - `parquet` and `csv` are supported.
+ More details on the supported Parquet format can be found in [Supported Parquet column types](access-graph-opencypher-21-extensions-s3-read-parquet.md#access-graph-opencypher-21-extensions-s3-read-parquet-column-types).
+ For more information on the supported csv format, see [Gremlin load data format](bulk-load-tutorial-format-gremlin.md).
+ **concurrency** (optional) - Type: 0 or greater integer. Default: 0. Specifies the number of threads to be used for reading the file. If the value is 0, the maximum number of threads allowed by the resource will be used. For Parquet, it is recommended to be set to a number of row groups.
**Outputs**
The neptune.read returns:
+ **row** - type:Map
+ Each row in the file, where the keys are the columns and the values are the data found in each column.
+ You can access each column's data like a property access (`row.col`).
## Best practices for neptune.read()
Neptune S3 read operations can be memory-intensive. Please use instance types well-suited for production workloads as outlined in [Choosing instance types for Amazon Neptune](instance-types.md).
Memory usage and performance of `neptune.read()` requests are affected by a variety of factors like file size, number of columns, number of rows, and file format. Depending on structure, small files (e.g., CSV files 100MB or under, Parquet files 20MB or under) may work reliably on most production-suited instance types, whereas larger files may require substantial memory that smaller instance types cannot provide.
When testing this feature, it is recommended to start with small files and scale gradually to ensure your read workload can be accommodated by your instance size. If you notice `neptune.read()` requests leading to out-of-memory exceptions or instance restarts, consider splitting your files into smaller chunks, reducing file complexity, or upgrading to larger instance types.
# Query examples using parquet
The following example query returns the number of rows in a given Parquet file:
```
CALL neptune.read(
{
source: "",
format: "parquet"
}
)
YIELD row
RETURN count(row)
```
You can run the query example using the `execute-open-cypher-query` operation in the AWS CLI by executing the following code:
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN count(row)" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
A query can be flexible in what it does with rows read from a Parquet file. For example, the following query creates a node with a field being set to data found in the Parquet file:
```
CALL neptune.read(
{
source: "",
format: "parquet"
}
)
YIELD row
CREATE (n {someField: row.someCol})
RETURN n
```
**Warning**
It is not considered good practice to use a large results-producing clause like `MATCH(n)` prior to a `CALL` clause. This would lead to a long-running query, due to cross product between incoming solutions from prior clauses and the rows read by neptune.read. It's recommended to start the query with `CALL` neptune.read.
## Supported Parquet column types
**Parquet Data Types:**
+ NULL
+ BOOLEAN
+ FLOAT
+ DOUBLE
+ STRING
+ SIGNED INTEGER: UINT8, UINT16, UINT32, UINT64
+ MAP: Only supports one-level. Does not support nested.
+ LIST: Only supports one-level. Does not support nested.
**Neptune-specific data types:**
Unlike the property column headers of the CSV format, the property column headers of the Parquet format only need to have the property names, so there is no need to have the type names nor the cardinality.
There are however, some special column types in the Parquet format that require annotation in the metadata, including the Any type, Date type, dateTime type, and Geometry type. The following object is an example of the required metadata annotation for files containing columns of these special types:
```
"metadata": {
"anyTypeColumns": ["UserCol1"],
"dateTypeColumns": ["UserCol2"],
"dateTimeTypeColumns": ["UserCol3"],
"geometryTypeColumns": ["UserCol4"]
}
```
Below are details on the expected payload associated with these types:
+ A column type Any is supported in the user columns. An Any type is a type "syntactic sugar" for all of the other types we support. It is extremely useful if a user column has multiple types in it. The payload of an Any type value is a list of json strings as follows: `{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, which has a value field and a type field in each individual json string. The cardinality value of an Any column is set, meaning that the column can accept multiple values.
+ Neptune supports the following types in an Any type: Bool (or Boolean), Byte, Short, Int, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, Float, Double, Date, dateTime, String, and Geometry.
+ Vector type is not supported in Any type.
+ Nested Any type is not supported. For example, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`.
+ Columns of type Date and Datetime are supported in the user columns. The payload of these columns must be provided as strings following the XSD format or one of the formats below:
+ yyyy-MM-dd
+ yyyy-MM-ddTHH:mm
+ yyyy-MM-ddTHH:mm:ss
+ yyyy-MM-ddTHH:mm:ssZ
+ yyyy-MM-ddTHH:mm:ss.SSSZ
+ yyyy-MM-ddTHH:mm:ss[\$1\$1-]hhmm
+ yyyy-MM-ddTHH:mm:ss.SSS[\$1\$1-]hhmm
+ A Geometry column type is supported in the user columns. The payload of these columns must only contain Geometry primitives of type Point, provided as strings in Well-known text (WKT) format. For example, POINT (30 10) would be a valid Geometry value.
## Sample parquet output
Given a Parquet file like this:
```
Parquet Type:
int8 int16 int32 int64 float double string
+--------+---------+-------------+----------------------+------------+------------+----------+
| Byte | Short | Int | Long | Float | Double | String |
|--------+---------+-------------+----------------------+------------+------------+----------|
| -128 | -32768 | -2147483648 | -9223372036854775808 | 1.23456 | 1.23457 | first |
| 127 | 32767 | 2147483647 | 9223372036854775807 | nan | nan | second |
| 0 | 0 | 0 | 0 | -inf | -inf | third |
| 0 | 0 | 0 | 0 | inf | inf | fourth |
+--------+---------+-------------+----------------------+------------+------------+----------+
```
Here is an example of the output returned by neptune.read using the following query:
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'parquet'}) YIELD row RETURN row" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
```
{
"results": [{
"row": {
"Float": 1.23456,
"Byte": -128,
"Int": -2147483648,
"Long": -9223372036854775808,
"String": "first",
"Short": -32768,
"Double": 1.2345678899999999
}
}, {
"row": {
"Float": "NaN",
"Byte": 127,
"Int": 2147483647,
"Long": 9223372036854775807,
"String": "second",
"Short": 32767,
"Double": "NaN"
}
}, {
"row": {
"Float": "-INF",
"Byte": 0,
"Int": 0,
"Long": 0,
"String": "third",
"Short": 0,
"Double": "-INF"
}
}, {
"row": {
"Float": "INF",
"Byte": 0,
"Int": 0,
"Long": 0,
"String": "fourth",
"Short": 0,
"Double": "INF"
}
}]
}
```
Currently, there is no way to set a node or edge label to a data field coming from a Parquet file. It is recommended that you partition the queries into multiple queries, one for each label/Type.
```
CALL neptune.read({source: '', format: 'parquet'})
YIELD row
WHERE row.`~label` = 'airport'
CREATE (n:airport)
CALL neptune.read({source: '', format: 'parquet'})
YIELD row
WHERE row.`~label` = 'country'
CREATE (n:country)
```
# Query examples using CSV
In this example, the query returns the number of rows in a given CSV file:
```
CALL neptune.read(
{
source: "",
format: "csv"
}
)
YIELD row
RETURN count(row)
```
You can run the query example using the execute-open-cypher-query operation in the AWS CLI by executing the following code:
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN count(row)" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
A query can be flexible in what it does with rows read from a CSV file. For instance, the following query creates a node with a field set to data from a CSV file:
```
CALL neptune.read(
{
source: "",
format: "csv"
}
)
YIELD row
CREATE (n {someField: row.someCol})
RETURN n
```
**Warning**
It is not considered good practice use a large results-producing clause like MATCH(n) prior to a CALL clause. This would lead to a long-running query due to cross product between incoming solutions from prior clauses and the rows read by neptune.read. It is recommended to start the query with CALL neptune.read.
## Property column headers
You can specify a column (`:`) for a property by using the following syntax. The type names are not case sensitive. If a colon appears within a property name, it must be escaped by preceding it with a backslash: `\:`.
```
propertyname:type
```
**Note**
Space, comma, carriage return and newline characters are not allowed in the column headers, so property names cannot include these characters.
You can specify a column for an array type by adding `[]` to the type:
```
propertyname:type[]
```
Edge properties can only have a single value and will cause an error if an array type is specified or a second value is specified. The following example shows the column header for a property named age of type Int:
```
age:Int
```
Every row in the file would be required to have an integer in that position or be left empty. Arrays of strings are allowed, but strings in an array cannot include the semicolon (`;`) character unless it is escaped using a backslash (`\;`).
## Supported CSV column types
+ **BOOL (or BOOLEAN)** - Allowed values: true, false. Indicates a Boolean field. Any value other than true will be treated as false.
+ **FLOAT** - Range: 32-bit IEEE 754 floating point including Infinity, INF, -Infinity, -INF and NaN (not-a-number).
+ **DOUBLE** - Range: 64-bit IEEE 754 floating point including Infinity, INF, -Infinity, -INF and NaN (not-a-number).
+ **STRING** -
+ Quotation marks are optional. Commas, newline, and carriage return characters are automatically escaped if they are included in a string surrounded by double quotation marks ("). Example: "Hello, World".
+ To include quotation marks in a quoted string, you can escape the quotation mark by using two in a row: Example: "Hello ""World""".
+ Arrays of strings are allowed, but strings in an array cannot include the semicolon (;) character unless it is escaped using a backslash (\$1;).
+ If you want to surround strings in an array with quotation marks, you must surround the whole array with one set of quotation marks. Example: "String one; String 2; String 3".
+ **DATE, DATETIME** - The datetime values can be provided in either the XSD format, or one of the following formats:
+ yyyy-MM-dd
+ yyyy-MM-ddTHH:mm
+ yyyy-MM-ddTHH:mm:ss
+ yyyy-MM-ddTHH:mm:ssZ
+ yyyy-MM-ddTHH:mm:ss.SSSZ
+ yyyy-MM-ddTHH:mm:ss[\$1\$1-]hhmm
+ yyyy-MM-ddTHH:mm:ss.SSS[\$1\$1-]hhmm
+ **SIGNED INTEGER** -
+ Byte: -128 to 127
+ Short: -32768 to 32767
+ Int: -2^31 to 2^31-1
+ Long: -2^63 to 2^63-1
**Neptune-specific column types:**
+ A column type Any is supported in the user columns. An Any type is a type "syntactic sugar" for all of the other types we support. It is extremely useful if a user column has multiple types in it. The payload of an Any type value is a list of json strings as follows: `{"value": "10", "type": "Int"};{"value": "1.0", "type": "Float"}`, which has a value field and a type field in each individual json string. The column header of an Any type is propertyname:Any. The cardinality value of an Any column is set, meaning that the column can accept multiple values.
+ Neptune supports the following types in an Any type: Bool (or Boolean), Byte, Short, Int, Long, UnsignedByte, UnsignedShort, UnsignedInt, UnsignedLong, Float, Double, Date, dateTime, String, and Geometry.
+ Vector type is not supported in Any type.
+ Nested Any type is not supported. For example, `{"value": {"value": "10", "type": "Int"}, "type": "Any"}`.
+ A Geometry column type is supported in the user columns. The payload of these columns must only contain Geometry primitives of type Point, provided as strings in Well-known text (WKT) format. For example, POINT (30 10) would be a valid Geometry value.
## Sample CSV output
Given the following CSV file:
```
colA:byte,colB:short,colC:int,colD:long,colE:float,colF:double,colG:string
-128,-32768,-2147483648,-9223372036854775808,1.23456,1.23457,first
127,32767,2147483647,9223372036854775807,nan,nan,second
0,0,0,0,-inf,-inf,third
0,0,0,0,inf,inf,fourth
```
This example shows the output returned by neptune.read using the following query:
```
aws neptunedata execute-open-cypher-query \
--open-cypher-query "CALL neptune.read({source: '', format: 'csv'}) YIELD row RETURN row" \
--endpoint-url https://my-cluster-name.cluster-abcdefgh1234.us-east-1.neptune.amazonaws.com:8182
```
```
{
"results": [{
"row": {
"colD": -9223372036854775808,
"colC": -2147483648,
"colE": 1.23456,
"colB": -32768,
"colF": 1.2345699999999999,
"colG": "first",
"colA": -128
}
}, {
"row": {
"colD": 9223372036854775807,
"colC": 2147483647,
"colE": "NaN",
"colB": 32767,
"colF": "NaN",
"colG": "second",
"colA": 127
}
}, {
"row": {
"colD": 0,
"colC": 0,
"colE": "-INF",
"colB": 0,
"colF": "-INF",
"colG": "third",
"colA": 0
}
}, {
"row": {
"colD": 0,
"colC": 0,
"colE": "INF",
"colB": 0,
"colF": "INF",
"colG": "fourth",
"colA": 0
}
}]
}
```
Currently, there is no way to set a node or edge label to a data field coming from a CSV file. It is recommended that you partition the queries into multiple queries, one for each label/type.
```
CALL neptune.read({source: '', format: 'csv'})
YIELD row
WHERE row.`~label` = 'airport'
CREATE (n:airport)
CALL neptune.read({source: '', format: 'csv'})
YIELD row
WHERE row.`~label` = 'country'
CREATE (n:country)
```
# Managing permissions for neptune.read()
## Required IAM Policies
To execute openCypher queries that use `neptune.read()`, you must have the appropriate permissions to access data in your Neptune database. Read-only queries require the `ReadDataViaQuery` action. Queries that modify data require `WriteDataViaQuery` for insertions or `DeleteDataViaQuery` for deletions. The example below grants all three actions on the specified cluster.
Additionally, you need permissions to access the S3 bucket containing your data files. The NeptuneS3Access policy statement grants the required S3 permissions:
+ **`s3:ListBucket`**: Required to verify bucket existence and list contents.
+ **`s3:GetObject`**: Required to access the specified object so its content can be read for integration into openCypher queries.
If your S3 bucket uses server-side encryption with AWS KMS, you must also grant KMS permissions. The NeptuneS3KMSAccess policy statement allows Neptune to decrypt data and generate data keys when accessing encrypted S3 objects. The condition restricts KMS operations to requests originating from S3 and RDS services in your region.
+ **`kms:Decrypt`**: Required to perform decryption of the encrypted object so its data can be read by Neptune.
+ **`kms:GenerateDataKey`**: Also required by the S3 API used to retrieve objects to be read.
```
{
"Sid": "NeptuneQueryAccess",
"Effect": "Allow",
"Action": [
"neptune-db:ReadDataViaQuery",
"neptune-db:WriteDataViaQuery",
"neptune-db:DeleteDataViaQuery"
],
"Resource": "arn:aws:neptune-db:::/*"
},
{
"Sid": "NeptuneS3Access",
"Effect": "Allow",
"Action": [
"s3:ListBucket",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::neptune-read-bucket",
"arn:aws:s3:::neptune-read-bucket/*"
]
},
{
"Sid": "NeptuneS3KMSAccess",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:::key/",
"Condition": {
"StringEquals": {
"kms:ViaService": [
"s3..amazonaws.com",
"rds..amazonaws.com"
]
}
}
}
```
## Important prerequisites
These permissions and prerequisites ensure secure and reliable integration of S3 data into openCypher queries, while maintaining proper access controls and data protection measures.
+ **IAM authentication**: This feature is only supported for Neptune clusters with IAM authentication enabled. See [Securing your Amazon Neptune database](security.md) for detailed instructions on how to create and connect to IAM authentication-enabled clusters.
+ **VPC endpoint**:
+ A Gateway-type VPC endpoint for Amazon S3 is required to allow Neptune to communicate with Amazon S3.
+ To use custom AWS KMS encryption in the query, an Interface-type VPC endpoint for AWS KMS is required to allow Neptune to communicate with AWS KMS.
+ For detailed instructions for how to configure this endpoint, see [Creating the Amazon S3 VPC Endpoint](bulk-load-tutorial-IAM.md).
# Spatial Data
Amazon Neptune now supports spatial queries, allowing you to store and analyze geometric data in your graph. While commonly used for geographic locations (like coordinates on a map), spatial features work with any two-dimensional data where position and proximity matter. Use this feature to answer questions like "Which stores are within 5 miles of this customer?", "Find all delivery routes that intersect with this service area," or "Which components in this floor plan overlap with the HVAC zone?" Neptune implements spatial support using industry-standard Spatial Types functions that work with points, polygons, and other geometric shapes. You can store spatial data as properties on nodes and edges, then use spatial functions to calculate distances, check if points fall within boundaries, or find overlapping regions, all within your openCypher queries.
**Common use cases**:
+ **Geographic applications**: Location-based recommendations, geofencing, route planning, and territory analysis
+ **Facility and space management**: Floor plan layouts, equipment placement, and zone coverage
+ **Network topology**: Physical infrastructure mapping, coverage areas, and service boundaries
+ **Design and CAD**: Component positioning, collision detection, and spatial relationships in 2D designs
+ **Game development**: Character positioning, collision detection, and area-of-effect calculations
The Spatial Types implementation in Amazon Neptune follows the ISO/IEC 13249-3:2016 directives, like other databases. The [Spatial Functions](access-graph-opencypher-22-spatial-functions.md) are available in the openCypher query language.
## Coordinate system
Neptune has one Spatial Reference Identifier (SRID) for an entire database. Homogeneity of the coordinate system reduce user errors in querying and improves the database performance. The first release (1.4.7.0) supports the Cartesian coordinate system, also referred as SRID 0.
The Neptune implementation of SRID 0 is compatible with longitude and latitude values. Use `ST_DistanceSpheroid` to calculate distances based on WGS84/SRID 4326.
The current implementation supports storing 3-dimensional coordinates. The Spatial Functions currently only support using the x- and y-axis (2-dimensional) coordinates. The z-axis coordinates are currently not supported by the available Spatial Functions.
## Storing location data
Store location data on nodes and edges using the Geometry property type. Create Geometry values from Well-Known Text (WKT) format, a standard way to represent geographic shapes as text. For example, to store a point location:
```
CREATE (n:airport {code: 'ATL', location: ST_GeomFromText('POINT (-84.4281 33.6367)')})
```
When working with geographic coordinates, the first argument (x) represents longitude and the second argument (y) represents latitude. This follows the standard coordinate order used in spatial databases and the ISO 19125 standard.
**Note**
Neptune now supports a new data type called "Geometry". The Geometry property of a node or an edge can be created from a WKT string using the `ST_GeomFromText` function.
Neptune will automatically store Points data in a specialized spatial index to improve the performance of the Spatial Types functions. For instance, `ST_Contains` used to find the points within a polygon is accelerated by the specialized spatial index.
[ Wikipedia page for Well-Known Text representation of geometry ](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry)
## Loading spatial data in bulk
When bulk loading data, specify the Geometry type in your CSV header. Neptune will parse WKT strings and create the appropriate Geometry properties:
```
:ID,:LABEL,code:String,city:String,location:Geometry
21,airport,ATL,Atlanta,POINT (-84.42810059 33.63669968)
32,airport,ANC,Anchorage,POINT (-149.9960022 61.17440033)
43,airport,AUS,Austin,POINT (-97.66989899 30.19449997)
```
For complete CSV format details, see [openCypher bulk load format](bulk-load-tutorial-format-opencypher.md).
## Querying spatial data
The following query examples use the [air-routes dataset](https://github.com/krlawrence/graph/tree/main/sample-data) to demonstrate how to use Spatial Functions in Neptune.
If your data has separate latitude and longitude properties instead of a Geometry property, you can convert them to points at query time. Find the 10 nearest airports to a given location:
```
MATCH (a:airport)
WITH a, ST_GeomFromText('POINT (' + a.lon + ' ' + a.lat + ')') AS airportLocation
WITH a, airportLocation, ST_Distance(ST_GeomFromText('POINT (-84.4281 33.6367)'), airportLocation) AS distance
WHERE distance IS NOT NULL
RETURN a.code, a.city, distance
ORDER BY distance ASC
LIMIT 10
```
If you already have locations stored as `ST_Point` then you can use those location values directly:
1. Set the property
```
MATCH (a:airport)
SET a.location = ST_GeomFromText('POINT (' + a.lon + ' ' + a.lat + ')')
```
1. Query using ST\$1Distance:
```
MATCH (a:airport)
WHERE a.location IS NOT NULL
WITH a, ST_Distance(ST_GeomFromText('POINT (-84.4281 33.6367)'), a.location) AS distance
RETURN a.code, a.city, distance
ORDER BY distance ASC
LIMIT 10
```
### Using the Bolt driver
Most query methods return Geometry values as WKT strings, which are human-readable. If you're using the Bolt driver, Geometry values are returned in WKB (Well-Known Binary) format for efficiency. Convert WKB to a Geometry object in your application:
```
try (Session session = driver.session()) {
Result result = session.run("MATCH (n:airport {code: 'ATL'}) RETURN n.location as geom");
Record record = result.single();
byte[] wkbBytes = record.get("geom").asByteArray();
// Convert WKB to Geometry object using JTS library
WKBReader wkbReader = new WKBReader();
Geometry geom = wkbReader.read(wkbBytes);
}
```
# Spatial Functions
The following spatial functions are available in Neptune openCypher for working with geometry data types:
+ [ST\$1Point](access-graph-opencypher-22-spatial-functions-st-point.md)
+ [ST\$1GeomFromText](access-graph-opencypher-22-spatial-functions-st-geomfromtext.md)
+ [ST\$1AsText](access-graph-opencypher-22-spatial-functions-st-astext.md)
+ [ST\$1GeometryType](access-graph-opencypher-22-spatial-functions-st-geometrytype.md)
+ [ST\$1Equals](access-graph-opencypher-22-spatial-functions-st-equals.md)
+ [ST\$1Contains](access-graph-opencypher-22-spatial-functions-st-contains.md)
+ [ST\$1Intersects](access-graph-opencypher-22-spatial-functions-st-intersect.md)
+ [ST\$1Distance](access-graph-opencypher-22-spatial-functions-st-distance.md)
+ [ST\$1DistanceSpheroid](access-graph-opencypher-22-spatial-functions-st-distancespheroid.md)
+ [ST\$1Envelope](access-graph-opencypher-22-spatial-functions-st-envelope.md)
+ [ST\$1Buffer](access-graph-opencypher-22-spatial-functions-st-buffer.md)
# ST\$1Point
ST\$1Point returns a point from the input coordinate values.
**Syntax**
```
ST_Point(x, y, z)
```
**Arguments**
+ `x` - A value of data type DOUBLE PRECISION that represents a first coordinate.
+ `y` - A value of data type DOUBLE PRECISION that represents a second coordinate.
+ `z` - (optional)
**Coordinate order**
When working with geographic coordinates, the first argument (`x`) represents **longitude** and the second argument (`y`) represents **latitude**. This follows the standard coordinate order used in spatial databases and the ISO 19125 standard.
```
// Correct: longitude first, latitude second
ST_Point(-84.4281, 33.6367) // Atlanta airport
// Incorrect: latitude first, longitude second
ST_Point(33.6367, -84.4281) // This will return NaN in distance calculations
```
**Valid coordinate ranges**
For geographic data, ensure coordinates fall within valid ranges:
+ Longitude (`x`): -180 to 180
+ Latitude (`y`): -90 to 90
Coordinates outside these ranges will return `NaN` (Not a Number) when used with distance calculation functions like `ST_DistanceSpheroid`.
**Return type**
GEOMETRY of subtype POINT
If x or y is null, then null is returned.
**Examples**
The following constructs a point geometry from the input coordinates.
```
RETURN ST_Point(5.0, 7.0);
POINT(5 7)
```
# ST\$1GeomFromText
ST\$1GeomFromText constructs a geometry object from a well-known text (WKT) representation of an input geometry.
**Syntax**
```
ST_GeomFromText(wkt_string)
```
**Arguments**
+ `wkt_string` - A value of data type STRING that is a WKT representation of a geometry.
**Return type**
GEOMETRY
If wkt\$1string is null, then null is returned.
If wkt\$1string is not valid, then a BadRequestException is returned.
**Examples**
```
RETURN ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))')
POLYGON((0 0,0 1,1 1,1 0,0 0))
```
# ST\$1AsText
ST\$1AsText returns the well-known text (WKT) representation of an input geometry.
**Syntax**
```
ST_AsText(geo)
```
**Arguments**
+ `geo` - A value of data type GEOMETRY, or an expression that evaluates to a GEOMETRY.
**Return type**
STRING
If geo is null, then null is returned.
If the input parameter is not a Geometry, then a BadRequestException is returned.
If the result is larger than a 64-KB STRING, then an error is returned.
**Examples**
```
RETURN ST_AsText(ST_GeomFromText('POLYGON((0 0,0 1,1 1,1 0,0 0))'))
POLYGON((0 0,0 1,1 1,1 0,0 0))
```
# ST\$1GeometryType
ST\$1GeometryType returns the type of the geometry as a string.
**Syntax**
```
ST_GeometryType(geom)
```
**Arguments**
+ `geom` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
**Return type**
STRING
If geom is null, then null is returned.
If the input parameter is not a Geometry, then a BadRequestException is returned.
**Examples**
```
RETURN ST_GeometryType(ST_GeomFromText('LINESTRING(77.29 29.07,77.42 29.26,77.27 29.31,77.29 29.07)'));
ST_LineString
```
# ST\$1Equals
ST\$1Equals returns true if the 2D projections of the input geometries are topologically equal. Geometries are considered topologically equal if they have equal point sets. In topologically equal geometries, the order of vertices may differ while maintaining this equality.
**Syntax**
```
ST_Equals(geom1, geom2)
```
**Arguments**
+ `geom1` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
+ `geom2` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type. This value is compared with geom1 to determine if it is equal to geom1.
**Return type**
BOOLEAN
If geom1 or geom2 is null, then null is returned.
If geom1 or geom2 are not Geometries, then a BadRequestException is returned.
**Examples**
```
RETURN ST_Equals(
ST_GeomFromText('POLYGON ((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
false
```
The following checks if the two linestrings are geometrically equal.
```
RETURN ST_Equals(
ST_GeomFromText('LINESTRING (1 0, 10 0)'),
ST_GeomFromText('LINESTRING(1 0,5 0,10 0)'));
true
```
# ST\$1Contains
ST\$1Contains returns true if the 2D projection of the first input geometry contains the 2D projection of the second input geometry. Geometry A contains geometry B if every point in B is a point in A, and their interiors have nonempty intersection. ST\$1Contains(A, B) is equivalent to ST\$1Within(B, A).
**Syntax**
```
ST_Contains(geom1, geom2)
```
**Arguments**
+ `geom1` - A value of type GEOMETRY or an expression that evaluates to a GEOMETRY type.
+ `geom2` - A value of type GEOMETRY or an expression that evaluates to a GEOMETRY type. This value is compared with geom1 to determine if it is contained within geom1.
**Return type**
BOOLEAN
If geom1 or geom2 is null, then null is returned.
If the input parameter is not a Geometry, then a BadRequestException is returned.
**Examples**
```
RETURN ST_Contains(
ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 3,2 1,0 -3,-1 3))'));
false
```
# ST\$1Intersects
ST\$1Intersects returns true if the 2D projections of the two input geometries have at least one point in common.
**Syntax**
```
ST_Intersects(geom1, geom2)
```
**Arguments**
+ `geom1` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
+ `geom2` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
**Return type**
BOOLEAN
If geom1 or geom2 is null, then null is returned.
If the input parameter is not a Geometry, then a BadRequestException is returned.
**Examples**
```
RETURN ST_Intersects(
ST_GeomFromText('POLYGON((0 0,10 0,10 10,0 10,0 0),(2 2,2 5,5 5,5 2,2 2))'),
ST_GeomFromText('MULTIPOINT((4 4),(6 6))'));
true
```
# ST\$1Distance
For input geometries, ST\$1Distance returns the minimum Euclidean distance between the 2D projections of the two input geometry values.
**Syntax**
```
ST_Distance(geo1, geo2)
```
**Arguments**
+ `geo1` - A value of data type GEOMETRY, or an expression that evaluates to a GEOMETRY type.
+ `geo2` - A value of data type GEOMETRY, or an expression that evaluates to a GEOMETRY.
**Return type**
DOUBLE PRECISION in the same units as the input geometries.
If geo1 or geo2 is null, then null is returned.
If the input parameter is not a Geometry, then a BadRequestException is returned.
**Examples**
```
RETURN ST_Distance(
ST_GeomFromText('POLYGON((0 2,1 1,0 -1,0 2))'),
ST_GeomFromText('POLYGON((-1 -3,-2 -1,0 -3,-1 -3))'));
1.4142135623731
```
# ST\$1DistanceSpheroid
Returns the minimum distance in meters between two lon/lat geometries. The spheroid is WGS84/SRID 4326.
**Syntax**
```
ST_DistanceSpheroid(geom1, geom2);
```
**Arguments**
+ `geom1` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
+ `geom2` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
**Return type**
FLOAT
If geom is null, then null is returned.
**Examples**
```
RETURN ST_DistanceSpheroid(
ST_GeomFromText('POINT(-110 42)'),
ST_GeomFromText('POINT(-118 38)'))
814278.77
```
# ST\$1Envelope
ST\$1Envelope returns the minimum bounding box of the input geometry, as follows:
+ If the input geometry is empty, the returned geometry will be POINT EMPTY.
+ If the minimum bounding box of the input geometry degenerates to a point, the returned geometry is a point.
+ If none of the preceding is true, the function returns a counter-clockwise-oriented polygon whose vertices are the corners of the minimum bounding box.
For all nonempty input, the function operates on the 2D projection of the input geometry.
**Syntax**
```
ST_Envelope(geom)
```
**Arguments**
+ `geom` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
**Return type**
GEOMETRY
If geom is null, then null is returned.
**Examples**
```
RETURN ST_Envelope(ST_GeomFromText("POLYGON ((2 1, 4 3, 6 1, 5 5, 3 4, 2 1))"))
POLYGON ((2 1, 6 1, 6 5, 2 5, 2 1))
```
# ST\$1Buffer
ST\$1Buffer returns 2D geometry that represents all points whose distance from the input geometry projected on the xy-Cartesian plane is less than or equal to the input distance.
**Syntax**
```
ST_Buffer(geom, distance, number_of_segments_per_quarter_circle)
```
**Arguments**
+ `geom` - A value of data type GEOMETRY or an expression that evaluates to a GEOMETRY type.
+ `distance` - A value of data type DOUBLE PRECISION that represents distance (or radius) of the buffer.
+ `number_of_segments_per_quarter_circle` - A value of data type INTEGER (should be larger or equal to 0). This value determines the number of points to approximate a quarter circle around each vertex of the input geometry. Negative values default to zero. The default is 8.
**Return type**
GEOMETRY
The ST\$1Buffer function returns two-dimensional (2D) geometry in the xy-Cartesian plane.
**Examples**
```
RETURN ST_Buffer(ST_GeomFromText('LINESTRING (1 2,5 2,5 8)'), 2, 4);
POLYGON ((3 4, 3 8, 3.1522409349774265 8.76536686473018,
3.585786437626905 9.414213562373096, 4.234633135269821 9.847759065022574,
5 10, 5.765366864730179 9.847759065022574,
6.414213562373095 9.414213562373096, 6.847759065022574 8.76536686473018,
7 8, 7 2, 6.847759065022574 1.2346331352698203,
6.414213562373095 0.5857864376269051, 5.765366864730179 0.1522409349774265,
5 0, 1 0, 0.2346331352698193 0.152240934977427,
-0.4142135623730954 0.5857864376269051,
-0.8477590650225737 1.2346331352698208, -1 2.0000000000000004,
-0.8477590650225735 2.7653668647301797,
-0.4142135623730949 3.414213562373095,
0.2346331352698206 3.8477590650225735, 1 4, 3 4))
```
The following returns the buffer of the input point geometry which approximates a circle. Because the command specifies 3 as the number of segments per quarter circle, the function uses three segments to approximate the quarter circle.
```
RETURN ST_Buffer(ST_GeomFromText('POINT (1 1)'), 1.0, 8));
POLYGON ((2 1, 1.9807852804032304 0.8049096779838718,
1.9238795325112867 0.6173165676349102, 1.8314696123025453 0.4444297669803978,
1.7071067811865475 0.2928932188134525, 1.5555702330196022 0.1685303876974548,
1.3826834323650898 0.0761204674887133, 1.1950903220161284 0.0192147195967696,
1 0, 0.8049096779838718 0.0192147195967696, 0.6173165676349103 0.0761204674887133,
0.444429766980398 0.1685303876974545, 0.2928932188134525 0.2928932188134524,
0.1685303876974546 0.4444297669803978, 0.0761204674887133 0.6173165676349102,
0.0192147195967696 0.8049096779838714, 0 0.9999999999999999,
0.0192147195967696 1.1950903220161284, 0.0761204674887132 1.3826834323650896,
0.1685303876974545 1.555570233019602, 0.2928932188134523 1.7071067811865475,
0.4444297669803978 1.8314696123025453, 0.6173165676349097 1.9238795325112865,
0.8049096779838714 1.9807852804032304, 0.9999999999999998 2,
1.1950903220161284 1.9807852804032304, 1.38268343236509 1.9238795325112865,
1.5555702330196017 1.8314696123025453, 1.7071067811865475 1.7071067811865477,
1.8314696123025453 1.5555702330196022, 1.9238795325112865 1.3826834323650905,
1.9807852804032304 1.1950903220161286, 2 1))
```