# Query APIs The Neptune Analytics data API provides support for data operations including query execution, query status checking, query cancellation, and graph summarizing via the HTTPS endpoint, the AWS CLI, and the SDK. **Topics** + [ExecuteQuery](query-APIs-execute-query.md) + [ListQueries](query-APIs-list-queries.md) + [GetQuery](query-APIs-get-query.md) + [CancelQuery](query-APIs-cancel-query.md) + [GraphSummary](query-APIs-graph-summary.md) + [IAM role mappings](query-APIs-IAM-role-mappings.md) # ExecuteQuery ExecuteQuery runs queries against a Neptune Analytics graph. Supported language: openCypher. ## ExecuteQuery inputs + graph-identifier (required) Type: `String` The identifier representing a graph. + region (required) Type: `String` The region where the graph is present. + query-string (required) Type: `String` Default: none A string representing a query. + language (required) Type: `Enum` Default: none The query language the query is written in. Currently, only `OPEN_CYPHER` is supported. + parameters (optional) Type: `Map` A map from `String` to `String` where the key is the parameter name and the value is the parameter value. + plan-cache (optional) Type: `Enum` Query plan cache is a feature that saves the query plan and reuses it on successive executions of the same query, reducing query latency. Query plan cache works for both read-only and mutation queries. The plan cache is an LRU cache with a five minute TTL and a capacity of 1000. It supports the following values: + `AUTO`: The engine will automatically decide to cache the query plan. If the query is parameterized and the runtime is shorter than 100ms, the query plan is automatically cached. + `ENABLED`: The query plan is cached regardless of the query runtime. The plan cache uses the query string as the key, this means that if a query is slightly different (i.e. different constants), it will not be able to reuse the plan cache of similar queries. + `DISABLED`: The query plan cache is not used. For more information on the query plan cache, see [Query plan cache](query-plan-cache.md). + explain-mode (optional) Type: `Enum` The explain mode parameters allow getting a query explain instead of the actual query results. A query explain can be used to gather insights about the query execution such as planning decisions, time spent on each operator, number of records flowing etc. If this parameter is not set the query is executed normally and the result is returned. The acceptable values for query explain are: + `STATIC`: Returns a query explain without executing the query. This can give an estimate on what the query plan looks like without actually executing the query. The static query plan may differ from the actual query plan. Actual queries may make planning decisions based on runtime statistics, which may not be considered when fetching a static query plan. A static query plan is useful when it is necessary to observe a plan for a query that either does not complete or runs for too long. + `DETAILS`: Returns a detailed query plan that shows what the running query did. This includes information such as operators runtime, number of records flowing through the plan, runtime planning decisions and more. If a query does not succeed in `NONE` mode, it will not succeed in `DETAILS` mode either. In this instance, you would want to use `STATIC` mode. For more information on query explain and its output, see [Query explain](query-explain.md). + query-timeout-milliseconds (optional) Type: `Enum` If specified, provides an upper bound to the query run time. This parameter will override the graph default timeout (30 minutes). Neptune Analytics graph have a maximum query runtime of 60 minutes. If the specified timeout is greater than the maximum query runtime, the query will only run for the maximum query runtime. + Using the default settings, any CLI or SDK request will timeout in 60 seconds and attempt a retry. For the cases where you are running queries that can take longer than 60 seconds, it is recommended to set the CLI/SDK timeout to `0` (no timeout), or a much larger value to avoid unnecesssary retries. It is also recommended to set `MAX_ATTEMPTS` for CLI/SDK to `1` for `execute_query` to avoid any retries by CLI/SDK. For the Boto client, set the `read_timeout` to `None`, and the `total_max_attempts` to `1`. ``` import boto3 from botocore.config import Config n = boto3.client('neptune-graph', config=(Config(retries={"total_max_attempts": 1, "mode": "standard"}, read_timeout=None))) ``` For the CLI, set the `--cli-read-timeout` parameter to `0` for no timeout, and set the environment variable `AWS_MAX_ATTEMPTS` to `1` to prevent retries. ``` export AWS_MAX_ATTEMPTS=1 ``` ``` aws neptune-graph execute-query \ --graph-identifier \ --region \ --query-string "MATCH (p:Person)-[r:KNOWS]->(p1) RETURN *;" \ --cli-read-timeout 0 --language open_cypher /tmp/out.txt ``` ## ExecuteQuery examples ------ #### [ AWS CLI ] ``` # Sample query aws neptune-graph execute-query \ --graph-identifier \ --region \ --query-string "MATCH (p:Person)-[r:KNOWS]->(p1) RETURN *;" \ --language open_cypher \ /tmp/out.txt # Sample query that prints directly to the console. aws neptune-graph execute-query \ --graph-identifier \ --region \ --query-string "MATCH (p:Person)-[r:KNOWS]->(p1) RETURN *;" \ --language open_cypher \ /dev/stdout # parameters supported query-string [REQUIRED] : String language [REQUIRED] : open_cypher explain-mode [OPTIONAL] : static | details query-timeout-milliseconds [OPTIONAL] : Integer plan-cache [OPTIONAL] : enabled | disabled | auto parameters [OPTIONAL] : Map ``` ------ #### [ AWSCURL ] ``` # Sample query awscurl -X POST "https://./queries" \ -H "Content-Type: application/x-www-form-urlencoded" \ --region \ --service neptune-graph \ -d "query=MATCH (p:Person)-[r:KNOWS]->(p1) RETURN *;" ``` ------ ## ExecuteQuery output ``` { "results": [{ "p": { "~id": "fa1ef9b0-fa32-4b37-8051-78f2bf0e0d63", "~entityType": "node", "~labels": ["Person"], "~properties": { "name": "Simone" } }, "p1": { "~id": "edaded10-b22b-4818-a22e-ddebfcf37acb", "~entityType": "node", "~labels": ["Person"], "~properties": { "name": "Mirro" } }, "r": { "~id": "neptune_reserved_1_1154145192329347075", "~entityType": "relationship", "~start": "fa1ef9b0-fa32-4b37-8051-78f2bf0e0d63", "~end": "edaded10-b22b-4818-a22e-ddebfcf37acb", "~type": "KNOWS", "~properties": {} } }] } ``` ## Parameterized queries Neptune Analytics supports parameterized openCypher queries. This allows you to use the same query structure multiple times with different arguments. Since the query structure doesn't change, Neptune Analytics tries to cache the plan for these parameterized queries that run in less than 100 milliseconds. The following 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 definied as follows: ``` parameters={"name": "john", "age": 20} ``` ------ #### [ AWS CLI ] ``` # Sample query aws neptune-graph execute-query \ --graph-identifier \ --region \ --query-string "MATCH (n {name: \$name, age: \$age}) RETURN n" \ --parameters "{\"name\": \"john\", \"age\": 20}" --language open_cypher /tmp/out.txt ``` ------ #### [ AWSCURL ] ``` # Sample query awscurl -X POST "https://[graph-id]./queries" \ -H "Content-Type: application/x-www-form-urlencoded" \ --region \ --service neptune-graph \ -d "query=MATCH (n {name: \$name, age: \$age}) RETURN n;¶meters={\"name\": \"john\", \"age\": 20}" ``` ------ # ListQueries ListQueries API fetches the list of running/waiting/cancelling queries on the graph. ## ListQueries syntax ``` aws neptune-graph list-queries \ --graph-identifier \ --region \ --max-results --state [all | running | waiting | cancelling] ``` ## ListQueries inputs + graph-identifier (required) Type: `String` Identifier representing your graph. + region (required) Type: `String` Region where the graph is present. + max-results (required) Type: `Integer` The maximum number of results to be fetched by the API. + state (optional) Type: `String` Supported values: all \$1 running \$1 waiting \$1 cancelling If `state` parameter is not specified, the API fetches all types. ## ListQueries outputs ``` # Sample Response { "queries": [ { "id": "130ab841-8b4b-46c3-afbe-af00274c7fd9", "queryString": "MATCH p=(n)-[*]-(m) RETURN p;", "waited": 0, "elapsed": 1686, "state": "RUNNING" } ] } ``` The output contains a list of query objects, each containing: + id: `String` - representing the unique identifier of the query. + queryString: `String` - The actual query text. The queryString may be truncated if the actual query string is too long. + waited: `Integer` - The time in milliseconds for which the query has waited in the waiting queue before being picked up by a worker thread. + elapsed: `Integer` - The time in milliseconds representing the running time of the query. + state: Current state of the query (running \$1 waiting \$1 cancelling). The default list order is queries that are `running`, followed by `waiting` and `cancelling`. ## ListQueries Examples ------ #### [ AWS CLI ] ``` aws neptune-graph list-queries \ --graph-identifier \ --region us-east-1 \ --max-results 200 --state waiting ``` ------ #### [ AWSCURL ] ``` awscurl -X GET "https://./queries?state=WAITING&maxResults=200" \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 \ --service neptune-graph ``` ------ # GetQuery The GetQuery API can be used to get the status of a specific query request. ## GetQuery inputs + graph-identifier (required) Type: `String` The identifier representing a graph. + region (required) Type: `String` The region where the graph is present. + query-id (required) Type: `String` The id of the query request for which you want to get information. ## GetQuery outputs + id: The same id used in this request. + queryString: Non-truncated query string associated to this `query-id`. + waited: Time in milliseconds this query request had to wait to be executed. + elapsed: Time in milliseconds the query spent while in execution. + state: Current state of the query - running \$1 waiting \$1 cancelling. ``` { "id" : "d6873456-40a7-44d7-be5c-46b4acfdc171", "queryString" : "UNWIND range(1,100000) AS i MATCH (n) RETURN i, n", "waited" : 1, "elapsed" : 8645, "state" : "RUNNING" } ``` ## GetQuery examples ------ #### [ AWS CLI ] ``` aws neptune-graph get-query \ --graph-identifier \ --region \ --query-id ``` ------ #### [ AWSCURL ] ``` awscurl -X GET "https://./queries/" \ -H "Content-Type: application/x-www-form-urlencoded" \ --region us-east-1 \ --service neptune-graph ``` ------ # CancelQuery CancelQuery cancels a specific query request. ## CancelQuery inputs + graph-identifier (required) Type: `String` The identifier representing a graph. + region (required) Type: `String` The region where the graph is present. + query-id (required) Type: `String` The id of the query request for which you want to cancel. ## CancelQuery outputs CancelQuery does not have any output. ## CancelQuery examples ------ #### [ AWS CLI ] ``` aws neptune-graph cancel-query \ --graph-identifier \ --region \ --query-id ``` ------ #### [ AWSCURL ] ``` awscurl -X DELETE "https://./queries/" --region us-east-1 --service neptune-graph ``` ------ # GraphSummary You can use the GetGraphSummary API to quickly gain a high-level understanding of your graph data, size and content. In a graph application, this API can be used to improve the search results by providing discovered node or edge labels as part of the search. The GetGraphSummary API retrieves a read-only list of node and edge labels and property keys, along with counts of nodes, edges, and properties. The API also accepts an optional parameter named mode, which can take one of two values, namely basic (the default) and detailed. The detailed graph summary response contains two additional fields, nodeStructures and edgeStructures. ## GetGraphSummary inputs GetGraphSummary accepts two inputs: + graph-identifier (required) - The unique identifier of the graph. + mode (optional) - Can be `basic` or `detailed`. ## GetGraphSummary outputs The response contains the following fields: + `version` - The version of this graph summary response. + `lastStatisticsComputationTime` - The timestamp, in ISO 8601 format, of the time at which Neptune Analytics last computed statistics. + `graphSummary` + `numNodes` - The number of nodes in the graph. + `numEdges` - The number of edges in the graph. + `numNodeLabels` - The number of distinct node labels in the graph. + `numEdgeLabels` - The number of disctinct edge labels in the graph. + `nodeLabels` - List of distinct node labels in the graph. + `edgeLabels` - List of distinct edge labels in the graph. + `numNodeProperties` - The number of distinct node properties in the graph. + `numEdgeProperites` - The number of distinct edge properties in the graph. + `nodeProperties` - List of distinct node properties in the graph along with the count of nodes where each property is used. + `edgeProperties` - List of distinct edge properties in the graph along with the count of edges where each property is used. + `totalNodePropertyValues` - Total number of usages of all node properties. + `totalEdgePropertyValues` - Total number of usages of all edge properties. + `nodeStructures` (only present for mode=detailed) - Contains a list of node structures, each containing the following fields: + `count` - Number of nodes that have this specific structure. + `nodeProperties` - List of node properties present in this specific structure. + `distinctOutgoingEdgeLabels` - List of distinct outgoing edge labels present in this specific structure. + `edgeStructures` (only present for mode=detailed) - Contains a list of edge structures each containing the following fields: + `count` - Number of edges that have this specific structure. + `edgeProperties` - List of edge properties present in this specific structure. ## GetGraphSummary examples ------ #### [ AWS CLI ] ``` # Sample query aws neptune-graph get-graph-summary \ --graph-identifier \ --region --mode detailed # parmeters supported mode [Optional] : basic | detailed ``` ------ #### [ AWSCURL ] ``` # Sample query awscurl "https://./summary" \ --region \ --service neptune-graph ``` ------ Sample output payload: ``` # this is the graph summary with "mode=detailed" { "version": "v1", "lastStatisticsComputationTime": "2024-01-25T19:50:42+00:00", "graphSummary": { "numNodes": 3749, "numEdges": 57645, "numNodeLabels": 4, "numEdgeLabels": 2, "nodeLabels": [ "continent", "country", "version", "airport" ], "edgeLabels": [ "contains", "route" ], "numNodeProperties": 14, "numEdgeProperties": 1, "nodeProperties": [ { "code": 3749 }, { "desc": 3749 }, { "type": 3749 }, { "city": 3504 }, { "country": 3504 }, { "elev": 3504 }, { "icao": 3504 }, { "lat": 3504 }, { "lon": 3504 }, { "longest": 3504 }, { "region": 3504 }, { "runways": 3504 }, { "author": 1 }, { "date": 1 } ], "edgeProperties": [ { "dist": 50637 } ], "totalNodePropertyValues": 42785, "totalEdgePropertyValues": 50637, "nodeStructures": [ // will not be present with mode=basic { "count": 3475, "nodeProperties": [ "city", "code", "country", "desc", "elev", "icao", "lat", "lon", "longest", "region", "runways", "type" ], "distinctOutgoingEdgeLabels": [ "route" ] }, { "count": 238, "nodeProperties": [ "code", "desc", "type" ], "distinctOutgoingEdgeLabels": [ "contains" ] }, { "count": 29, "nodeProperties": [ "city", "code", "country", "desc", "elev", "icao", "lat", "lon", "longest", "region", "runways", "type" ], "distinctOutgoingEdgeLabels": [] }, { "count": 6, "nodeProperties": [ "code", "desc", "type" ], "distinctOutgoingEdgeLabels": [] }, { "count": 1, "nodeProperties": [ "author", "code", "date", "desc", "type" ], "distinctOutgoingEdgeLabels": [] } ], "edgeStructures": [ //will not be present with mode=basic { "count": 50637, "edgeProperties": [ "dist" ] } ] } } ``` # IAM role mappings When you're calling Neptune Analytics API methods on a cluster, you require an IAM policy attached to the user or role making the calls that provides permissions for the actions you want to make. You set those permissions in the policy using corresponding IAM actions. You can also restrict the actions that can be taken using [IAM condition keys](https://docs.aws.amazon.com//neptune/latest/userguide/iam-data-condition-keys.html). Most IAM actions have the same name as the API methods that they correspond to, but some methods in the data API have different names, because some are shared by more than one method. The table below lists data methods and their corresponding IAM actions. | Data API operation name | IAM correspondences | | --- | --- | | ListQueries | Action: ListQueries | | GetQuery | Action: GetQueryStatus | | Cancel Query | Action: CancelQuery | | GetGraphSummary | Action: GetGraphSummary | | ExecuteQuery | Action: ReadDataViaQuery Action: WriteDataViaQuery Action: DeleteDataViaQuery | For more information, see [ Actions, resources and condition keys for Neptune Analytics](https://docs.aws.amazon.com//service-authorization/latest/reference/list_amazonneptuneanalytics.html).