AWS neptune documentation change
Summary
Restructured and expanded documentation for Gremlin query status API, splitting into two operations (listing all active queries and getting specific query status), adding detailed examples for AWS CLI, SDK, awscurl, and curl with proper authentication notes.
Security assessment
The changes are documentation improvements that clarify API usage and add examples. While there's no evidence of addressing a specific security vulnerability, the documentation now includes explicit references to IAM authentication when using awscurl, which enhances security awareness. The changes improve operational visibility into running queries but don't indicate any security incident response.
Diff
diff --git a/neptune/latest/userguide/gremlin-api-status.md b/neptune/latest/userguide/gremlin-api-status.md index 935ce1aaf..bcfc2060a 100644 --- a//neptune/latest/userguide/gremlin-api-status.md +++ b//neptune/latest/userguide/gremlin-api-status.md @@ -5 +5 @@ -Request parametersResponse syntaxResponse valuesExample +Listing queriesSingle query status @@ -9 +9 @@ Request parametersResponse syntaxResponse valuesExample -To get the status of Gremlin queries, use HTTP `GET` or `POST` to make a request to the `https://`your-neptune-endpoint`:`port`/gremlin/status` endpoint. +You can list all active Gremlin queries or get the status of a specific query. The underlying HTTP endpoint for both operations is `https://`your-neptune-endpoint`:`port`/gremlin/status`. @@ -11 +11 @@ To get the status of Gremlin queries, use HTTP `GET` or `POST` to make a request -## Gremlin query status request parameters +## Listing active Gremlin queries @@ -13 +13 @@ To get the status of Gremlin queries, use HTTP `GET` or `POST` to make a request - * **queryId** (_optional_) – The ID of a running Gremlin query. Only displays the status of the specified query. +To list all active Gremlin queries, call the endpoint with no `queryId` parameter. @@ -15 +15 @@ To get the status of Gremlin queries, use HTTP `GET` or `POST` to make a request - * **includeWaiting** (_optional_) – Returns the status of all waiting queries. +### Request parameters @@ -17 +17 @@ To get the status of Gremlin queries, use HTTP `GET` or `POST` to make a request -Normally, only running queries are included in the response, but when the `includeWaiting` parameter is specified, the status of all waiting queries is also returned. + * **includeWaiting** (_optional_) – If set to `TRUE`, the response includes waiting queries in addition to running queries. @@ -22 +22 @@ Normally, only running queries are included in the response, but when the `inclu -## Gremlin query status response syntax +### Response syntax @@ -31,2 +31 @@ Normally, only running queries are included in the response, but when the `inclu - "queryEvalStats": - { + "queryEvalStats": { @@ -42,2 +40,0 @@ Normally, only running queries are included in the response, but when the `inclu -## Gremlin query status response values - @@ -50 +46,0 @@ Normally, only running queries are included in the response, but when the `inclu - * **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.html)). @@ -52 +47,0 @@ Normally, only running queries are included in the response, but when the `inclu - * **queryEvalStats** – Statistics for this query. @@ -54 +48,0 @@ Normally, only running queries are included in the response, but when the `inclu - * **subqueries** – The number of subqueries in this query. @@ -56 +50 @@ Normally, only running queries are included in the response, but when the `inclu - * **elapsed** – The number of milliseconds the query has been running so far. +### Example @@ -58 +52 @@ Normally, only running queries are included in the response, but when the `inclu - * **cancelled** – True indicates that the query was cancelled. +AWS CLI @@ -60 +53,0 @@ Normally, only running queries are included in the response, but when the `inclu - * **queryString** – The submitted query. This is truncated to 1024 characters if it is longer than that. @@ -62 +54,0 @@ Normally, only running queries are included in the response, but when the `inclu - * **waited** – Indicates how long the query waited, in milliseconds. @@ -63,0 +56,19 @@ Normally, only running queries are included in the response, but when the `inclu + aws neptunedata list-gremlin-queries \ + --endpoint-url https://your-neptune-endpoint:port + +For more information, see [list-gremlin-queries](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/list-gremlin-queries.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.list_gremlin_queries() @@ -64,0 +76 @@ Normally, only running queries are included in the response, but when the `inclu + print(response) @@ -65,0 +78 @@ Normally, only running queries are included in the response, but when the `inclu +For AWS SDK examples in other languages like Java, .NET, and more, see [AWS SDK](./access-graph-gremlin-sdk.html). @@ -67 +80,15 @@ Normally, only running queries are included in the response, but when the `inclu -## Gremlin query status example +awscurl + + + + awscurl https://your-neptune-endpoint:port/gremlin/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. + +For more information about using **awscurl** with IAM authentication, see [Using awscurl with temporary credentials to securely connect to a DB cluster with IAM authentication enabled](./iam-auth-connect-command-line.html#iam-auth-connect-awscurl). + +curl @@ -69 +95,0 @@ Normally, only running queries are included in the response, but when the `inclu -The following is an example of the status command using `curl` and HTTP `GET`. @@ -74 +100 @@ The following is an example of the status command using `curl` and HTTP `GET`. -This output shows a single running query. +The following output shows a single running query. @@ -83,2 +109 @@ This output shows a single running query. - "queryEvalStats": - { + "queryEvalStats": { @@ -93,0 +119,100 @@ This output shows a single running query. +## Getting the status of a specific Gremlin query + +To get the status of a specific Gremlin query, provide the `queryId` parameter. + +### Request parameters + + * **queryId** (_required_) – The ID of the Gremlin query. Neptune automatically assigns this ID value to each query, or you can assign your own ID (see [Inject a Custom ID Into a Neptune Gremlin or SPARQL Query](./features-query-id.html)). + + + + +### Response syntax + + + { + "queryId": "guid", + "queryString": "string", + "queryEvalStats": { + "waited": integer, + "elapsed": integer, + "cancelled": boolean, + "subqueries": document + } + } + + * **queryId** – The ID of the query. + + * **queryString** – The submitted query. This is truncated to 1024 characters if it is longer than that. + + * **queryEvalStats** – Statistics for the query, including `waited` (wait time in milliseconds), `elapsed` (run time in milliseconds), `cancelled` (whether the query was cancelled), and `subqueries` (the number of subqueries). + + + + +### Example + +AWS CLI + + + + aws neptunedata get-gremlin-query-status \ + --endpoint-url https://your-neptune-endpoint:port \ + --query-id "fb34cd3e-f37c-4d12-9cf2-03bb741bf54f" + +For more information, see [get-gremlin-query-status](https://docs.aws.amazon.com/cli/latest/reference/neptunedata/get-gremlin-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_gremlin_query_status( + queryId='fb34cd3e-f37c-4d12-9cf2-03bb741bf54f' + ) + + print(response) + +For AWS SDK examples in other languages like Java, .NET, and more, see [AWS SDK](./access-graph-gremlin-sdk.html). + +awscurl + + + + awscurl https://your-neptune-endpoint:port/gremlin/status/fb34cd3e-f37c-4d12-9cf2-03bb741bf54f \ + --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. + +For more information about using **awscurl** with IAM authentication, see [Using awscurl with temporary credentials to securely connect to a DB cluster with IAM authentication enabled](./iam-auth-connect-command-line.html#iam-auth-connect-awscurl). + +curl + + + + curl https://your-neptune-endpoint:port/gremlin/status/fb34cd3e-f37c-4d12-9cf2-03bb741bf54f + +The following is an example response. + + + { + "queryId": "fb34cd3e-f37c-4d12-9cf2-03bb741bf54f", + "queryString": "g.V().out().count()", + "queryEvalStats": { + "waited": 0, + "elapsed": 23, + "cancelled": false + } + } +