本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# Neptune 查询 API
<a name="data-api-dp-queries"></a>

**Gremlin 查询操作：**
+ [ExecuteGremlinQuery（操作）](#ExecuteGremlinQuery)
+ [ExecuteGremlinExplainQuery（操作）](#ExecuteGremlinExplainQuery)
+ [ExecuteGremlinProfileQuery（操作）](#ExecuteGremlinProfileQuery)
+ [ListGremlinQueries（操作）](#ListGremlinQueries)
+ [GetGremlinQueryStatus（操作）](#GetGremlinQueryStatus)
+ [CancelGremlinQuery（操作）](#CancelGremlinQuery)

**openCypher 查询操作：**
+ [ExecuteOpenCypherQuery（操作）](#ExecuteOpenCypherQuery)
+ [ExecuteOpenCypherExplainQuery（操作）](#ExecuteOpenCypherExplainQuery)
+ [ListOpenCypherQueries（操作）](#ListOpenCypherQueries)
+ [GetOpenCypherQueryStatus（操作）](#GetOpenCypherQueryStatus)
+ [CancelOpenCypherQuery（操作）](#CancelOpenCypherQuery)

**查询结构：**
+ [QueryEvalStats（结构）](#QueryEvalStats)
+ [GremlinQueryStatus（结构）](#GremlinQueryStatus)
+ [GremlinQueryStatusAttributes（结构）](#GremlinQueryStatusAttributes)

## ExecuteGremlinQuery（操作）
<a name="ExecuteGremlinQuery"></a>

         此 API 的 AWS CLI 名称为：`execute-gremlin-query`。

此命令执行一个 Gremlin 查询。Amazon Neptune 与 Apache TinkerPop3 和 Gremlin 兼容，因此，您可以使用 Gremlin 遍历语言来查询图形，正如 Apache TinkerPop3 文档的[图形](https://tinkerpop.apache.org/docs/current/reference/#graph)中所述。更多详细信息也可以在[使用 Gremlin 访问 Neptune 图形](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-gremlin.html)中找到。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加一个策略，该策略允许在该集群中执行以下 IAM 操作之一，具体取决于查询：
+ [neptune-db:ReadDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#readdataviaquery)
+ [neptune-db:WriteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#writedataviaquery)
+ [neptune-db:DeleteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#deletedataviaquery)

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:Gremlin](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 Gremlin 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **gremlinQuery**（在 CLI 中：`--gremlin-query`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  使用此 API，您可以像使用 HTTP 端点一样以字符串格式运行 Gremlin 查询。该接口与您的数据库集群使用的任何 Gremlin 版本兼容（请参阅 [Tinkerpop 客户端部分](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-gremlin-client.html#best-practices-gremlin-java-latest)以确定您的引擎版本支持哪些 Gremlin 版本）。
+ **serializer**（在 CLI 中：`--serializer`）– 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  如果不为 null，则在以该参数指定的格式序列化的响应消息中返回查询结果。有关当前支持的格式列表，请参阅 TinkerPop 文档中的 [GraphSON](https://tinkerpop.apache.org/docs/current/reference/#_graphson) 部分。

**响应**
+ **meta** – 文档，类型为：`document`（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  有关 Gremlin 查询的元数据。
+ **requestId** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  Gremlin 查询的唯一标识符。
+ **result** – 文档，类型为：`document`（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  来自服务器的 Gremlin 查询输出。
+ **status** – 一个 [GremlinQueryStatusAttributes](#GremlinQueryStatusAttributes) 对象。

  Gremlin 查询的状态。

**错误**
+ [QueryTooLargeException](data-api-dp-errors.md#QueryTooLargeException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [QueryLimitExceededException](data-api-dp-errors.md#QueryLimitExceededException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [QueryLimitException](data-api-dp-errors.md#QueryLimitException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [CancelledByUserException](data-api-dp-errors.md#CancelledByUserException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [MemoryLimitExceededException](data-api-dp-errors.md#MemoryLimitExceededException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [MalformedQueryException](data-api-dp-errors.md#MalformedQueryException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## ExecuteGremlinExplainQuery（操作）
<a name="ExecuteGremlinExplainQuery"></a>

         此 API 的 AWS CLI 名称为：`execute-gremlin-explain-query`。

执行 Gremlin Explain 查询。

Amazon Neptune 添加了一项名为 `explain` 的 Gremlin 特征，该特征提供了一种自助服务工具，用于了解 Neptune 引擎为查询所采用的执行方法。您可以通过将 `explain` 参数添加到提交 Gremlin 查询的 HTTP 调用来调用它。

Explain 特征提供了有关查询执行计划的逻辑结构的信息。您可以使用这些信息来识别潜在的评估和执行瓶颈，并调整查询，如[调试 Gremlin 查询](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-traversal-tuning.html)中所述。您还可以使用查询提示来改进查询执行计划。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加一个策略，该策略允许在该集群中执行以下 IAM 操作之一，具体取决于查询：
+ [neptune-db:ReadDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#readdataviaquery)
+ [neptune-db:WriteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#writedataviaquery)
+ [neptune-db:DeleteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#deletedataviaquery)

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:Gremlin](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 Gremlin 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **gremlinQuery**（在 CLI 中：`--gremlin-query`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  Gremlin explain 查询字符串。

**响应**
+ **output** – 一个 ReportAsText，类型为：`blob`（未解释的二进制数据块）。

  包含 Gremlin explain 结果的文本 blob，如[调整 Gremlin 查询](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-traversal-tuning.html)中所述。

**错误**
+ [QueryTooLargeException](data-api-dp-errors.md#QueryTooLargeException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [QueryLimitExceededException](data-api-dp-errors.md#QueryLimitExceededException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [QueryLimitException](data-api-dp-errors.md#QueryLimitException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [CancelledByUserException](data-api-dp-errors.md#CancelledByUserException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [MemoryLimitExceededException](data-api-dp-errors.md#MemoryLimitExceededException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [MalformedQueryException](data-api-dp-errors.md#MalformedQueryException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## ExecuteGremlinProfileQuery（操作）
<a name="ExecuteGremlinProfileQuery"></a>

         此 API 的 AWS CLI 名称为：`execute-gremlin-profile-query`。

执行 Gremlin Profile 查询，该查询运行指定的遍历，收集有关运行的各种指标，并生成分析报告作为输出。有关详细信息，请参阅 [Neptune 中的 Gremlin profile API](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-profile-api.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:ReadDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#readdataviaquery) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:Gremlin](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 Gremlin 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **chop**（在 CLI 中：`--chop`）– 一个整数，类型为：`integer`（带符号的 32 位整数）。

  如果不为零，结果字符串将在该字符数处截断。如果设置为零，字符串将包含所有结果。
+ **gremlinQuery**（在 CLI 中：`--gremlin-query`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  要分析的 Gremlin 查询字符串。
+ **indexOps**（在 CLI 中：`--index-ops`）– 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  如果此标志设置为 `TRUE`，则结果包含在查询执行和序列化期间发生的所有索引操作的详细报告。
+ **results**（在 CLI 中：`--results`）– 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  如果此标志设置为 `TRUE`，则收集查询结果并在分析报告中显示。如果为 `FALSE`，则仅显示结果计数。
+ **serializer**（在 CLI 中：`--serializer`）– 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  如果不为空，则在以该参数指定的格式序列化的响应消息中返回收集的结果。有关更多信息，请参阅 [Neptune 中的 Gremlin profile API](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-profile-api.html)。

**响应**
+ **output** – 一个 ReportAsText，类型为：`blob`（未解释的二进制数据块）。

  包含 Gremlin Profile 结果的文本 blob。有关详细信息，请参阅 [Neptune 中的 Gremlin profile API](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-profile-api.html)。

**错误**
+ [QueryTooLargeException](data-api-dp-errors.md#QueryTooLargeException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [QueryLimitExceededException](data-api-dp-errors.md#QueryLimitExceededException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [QueryLimitException](data-api-dp-errors.md#QueryLimitException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [CancelledByUserException](data-api-dp-errors.md#CancelledByUserException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [MemoryLimitExceededException](data-api-dp-errors.md#MemoryLimitExceededException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [MalformedQueryException](data-api-dp-errors.md#MalformedQueryException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## ListGremlinQueries（操作）
<a name="ListGremlinQueries"></a>

         此 API 的 AWS CLI 名称为：`list-gremlin-queries`。

列出活动的 Gremlin 查询。有关输出的详细信息，请参阅 [Gremlin 查询状态 API](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:GetQueryStatus](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#getquerystatus) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:Gremlin](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 Gremlin 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **includeWaiting**（在 CLI 中：`--include-waiting`）– 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  如果设置为 `TRUE`，则返回的列表包括等待的查询。默认值为 `FALSE`；

**响应**
+ **acceptedQueryCount** – 一个整数，类型为：`integer`（带符号的 32 位整数）。

  已接受但尚未完成的查询数，包括队列中的查询。
+ **queries** – [GremlinQueryStatus](#GremlinQueryStatus) 对象的数组。

  当前查询的列表。
+ **runningQueryCount** – 一个整数，类型为：`integer`（带符号的 32 位整数）。

  当前正在运行的 Gremlin 查询的数量。

**错误**
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [AccessDeniedException](data-api-dp-errors.md#AccessDeniedException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ReadOnlyViolationException](data-api-dp-errors.md#ReadOnlyViolationException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## GetGremlinQueryStatus（操作）
<a name="GetGremlinQueryStatus"></a>

         此 API 的 AWS CLI 名称为：`get-gremlin-query-status`。

获取指定的 Gremlin 查询的状态。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:GetQueryStatus](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#getquerystatus) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:Gremlin](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 Gremlin 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **queryId**（在 CLI 中：`--query-id`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  标识 Gremlin 查询的唯一标识符。

**响应**
+ **queryEvalStats** – 一个 [QueryEvalStats](#QueryEvalStats) 对象。

  Gremlin 查询的评估状态。
+ **queryId** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  正在返回其状态的查询的 ID。
+ **queryString** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  Gremlin 查询字符串。

**错误**
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [AccessDeniedException](data-api-dp-errors.md#AccessDeniedException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ReadOnlyViolationException](data-api-dp-errors.md#ReadOnlyViolationException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## CancelGremlinQuery（操作）
<a name="CancelGremlinQuery"></a>

         此 API 的 AWS CLI 名称为：`cancel-gremlin-query`。

取消 Gremlin 查询。有关更多信息，请参阅 [Gremlin 查询取消](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status-cancel.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:CancelQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#cancelquery) IAM 操作的策略。

**请求**
+ **queryId**（在 CLI 中：`--query-id`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  标识要取消的查询的唯一标识符。

**响应**
+ **status** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  取消的状态

**错误**
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## *openCypher 查询操作：*
<a name="data-api-dp-queries-opencypher-query-actions-spacer"></a>

## ExecuteOpenCypherQuery（操作）
<a name="ExecuteOpenCypherQuery"></a>

         此 API 的 AWS CLI 名称为：`execute-open-cypher-query`。

执行 openCypher 查询。有关更多信息，请参阅[使用 openCypher 访问 Neptune 图形](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher.html)。

Neptune 支持使用 openCypher 构建图形应用程序，openCypher 是目前使用图形数据库的开发人员最常用的查询语言之一。开发人员、业务分析师和数据科学家都喜欢 openCypher 的声明式、受 SQL 启发的语法，因为它为查询属性图提供了一种熟悉的结构。

openCypher 语言最初由 Neo4j 开发，然后于 2015 年开源，并在 Apache 2 开源许可证下为 [openCypher 项目](https://opencypher.org/)做出了贡献。

请注意，在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加一个策略，该策略允许在该集群中执行以下 IAM 操作之一，具体取决于查询：
+ [neptune-db:ReadDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#readdataviaquery)
+ [neptune-db:WriteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#writedataviaquery)
+ [neptune-db:DeleteDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#deletedataviaquery)

另请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:OpenCypher](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 openCypher 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **openCypherQuery**（在 CLI 中：`--open-cypher-query`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  要执行的 openCypher 查询字符串。
+ **parameters**（在 CLI 中：`--parameters`）– 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  用于查询执行的 openCypher 查询参数。有关更多信息，请参阅 [openCypher 参数化查询示例](https://docs.aws.amazon.com/neptune/latest/userguide/opencypher-parameterized-queries.html)。

**响应**
+ **results** – *必需：*文档，类型为：`document`（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  openCypher 查询结果。

**错误**
+ [QueryTooLargeException](data-api-dp-errors.md#QueryTooLargeException)
+ [InvalidNumericDataException](data-api-dp-errors.md#InvalidNumericDataException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [QueryLimitExceededException](data-api-dp-errors.md#QueryLimitExceededException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [QueryLimitException](data-api-dp-errors.md#QueryLimitException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [CancelledByUserException](data-api-dp-errors.md#CancelledByUserException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [MemoryLimitExceededException](data-api-dp-errors.md#MemoryLimitExceededException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [MalformedQueryException](data-api-dp-errors.md#MalformedQueryException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## ExecuteOpenCypherExplainQuery（操作）
<a name="ExecuteOpenCypherExplainQuery"></a>

         此 API 的 AWS CLI 名称为：`execute-open-cypher-explain-query`。

执行 openCypher `explain` 请求。有关更多信息，请参阅 [openCypher explain 特征](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-explain.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:ReadDataViaQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#readdataviaquery) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:OpenCypher](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 openCypher 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **explainMode**（在 CLI 中：`--explain-mode`）– *必需：*OpenCypherExplainMode，类型为：`string`（UTF-8 编码的字符串）。

  openCypher `explain` 模式。可以为以下值之一：`static`、`dynamic` 或 `details`。
+ **openCypherQuery**（在 CLI 中：`--open-cypher-query`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  openCypher 查询字符串。
+ **parameters**（在 CLI 中：`--parameters`）– 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  openCypher 查询参数。

**响应**
+ **results** – *必需：*Blob，类型为：`blob`（未解释的二进制数据块）。

  一个包含 openCypher `explain` 结果的文本 blob。

**错误**
+ [QueryTooLargeException](data-api-dp-errors.md#QueryTooLargeException)
+ [InvalidNumericDataException](data-api-dp-errors.md#InvalidNumericDataException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [QueryLimitExceededException](data-api-dp-errors.md#QueryLimitExceededException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [QueryLimitException](data-api-dp-errors.md#QueryLimitException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [CancelledByUserException](data-api-dp-errors.md#CancelledByUserException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [MemoryLimitExceededException](data-api-dp-errors.md#MemoryLimitExceededException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [MalformedQueryException](data-api-dp-errors.md#MalformedQueryException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## ListOpenCypherQueries（操作）
<a name="ListOpenCypherQueries"></a>

         此 API 的 AWS CLI 名称为：`list-open-cypher-queries`。

列出活动的 openCypher 查询。有关更多信息，请参阅 [Neptune openCypher 状态端点](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-status.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:GetQueryStatus](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#getquerystatus) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:OpenCypher](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 openCypher 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **includeWaiting**（在 CLI 中：`--include-waiting`）– 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

   如果设置为 `TRUE` 且其它参数不存在，则会导致为等待的查询和正在运行的查询返回状态信息。

**响应**
+ **acceptedQueryCount** – 一个整数，类型为：`integer`（带符号的 32 位整数）。

  已接受但尚未完成的查询数，包括队列中的查询。
+ **queries** – [GremlinQueryStatus](#GremlinQueryStatus) 对象的数组。

  当前 openCypher 查询的列表。
+ **runningQueryCount** – 一个整数，类型为：`integer`（带符号的 32 位整数）。

  当前正在运行的 openCypher 查询的数量。

**错误**
+ [InvalidNumericDataException](data-api-dp-errors.md#InvalidNumericDataException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [AccessDeniedException](data-api-dp-errors.md#AccessDeniedException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ReadOnlyViolationException](data-api-dp-errors.md#ReadOnlyViolationException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## GetOpenCypherQueryStatus（操作）
<a name="GetOpenCypherQueryStatus"></a>

         此 API 的 AWS CLI 名称为：`get-open-cypher-query-status`。

检索指定的 openCypher 查询的状态。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:GetQueryStatus](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#getquerystatus) IAM 操作的策略。

请注意，可以在策略文档中使用 [neptune-db:QueryLanguage:OpenCypher](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html#iam-neptune-condition-keys) IAM 条件键来限制 openCypher 查询的使用（请参阅 [Neptune IAM 数据访问策略声明中提供的条件键](https://docs.aws.amazon.com/neptune/latest/userguide/iam-data-condition-keys.html)）。

**请求**
+ **queryId**（在 CLI 中：`--query-id`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  要检索其查询状态的 openCypher 查询的唯一 ID。

**响应**
+ **queryEvalStats** – 一个 [QueryEvalStats](#QueryEvalStats) 对象。

  openCypher 查询评估状态。
+ **queryId** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  正在返回其状态的查询的唯一 ID。
+ **queryString** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  openCypher 查询字符串。

**错误**
+ [InvalidNumericDataException](data-api-dp-errors.md#InvalidNumericDataException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [AccessDeniedException](data-api-dp-errors.md#AccessDeniedException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ReadOnlyViolationException](data-api-dp-errors.md#ReadOnlyViolationException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## CancelOpenCypherQuery（操作）
<a name="CancelOpenCypherQuery"></a>

         此 API 的 AWS CLI 名称为：`cancel-open-cypher-query`。

取消指定的 openCypher 查询。有关更多信息，请参阅 [Neptune openCypher 状态端点](https://docs.aws.amazon.com/neptune/latest/userguide/access-graph-opencypher-status.html)。

在启用了 IAM 身份验证的 Neptune 集群中调用此操作时，发出请求的 IAM 用户或角色必须附加允许在该集群中执行 [neptune-db:CancelQuery](https://docs.aws.amazon.com/neptune/latest/userguide/iam-dp-actions.html#cancelquery) IAM 操作的策略。

**请求**
+ **queryId**（在 CLI 中：`--query-id`）– *必需：*一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  要取消的 openCypher 查询的唯一ID。
+ **silent**（在 CLI 中：`--silent`）– 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  如果设置为 `TRUE`，则会导致以静默方式取消 openCypher 查询。

**响应**
+ **payload** - 一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  openCypher 查询的取消有效负载。
+ **status** – 一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  openCypher 查询的取消状态。

**错误**
+ [InvalidNumericDataException](data-api-dp-errors.md#InvalidNumericDataException)
+ [BadRequestException](data-api-dp-errors.md#BadRequestException)
+ [InvalidParameterException](data-api-dp-errors.md#InvalidParameterException)
+ [ClientTimeoutException](data-api-dp-errors.md#ClientTimeoutException)
+ [IllegalArgumentException](data-api-dp-errors.md#IllegalArgumentException)
+ [TooManyRequestsException](data-api-dp-errors.md#TooManyRequestsException)
+ [UnsupportedOperationException](data-api-dp-errors.md#UnsupportedOperationException)
+ [FailureByQueryException](data-api-dp-errors.md#FailureByQueryException)
+ [PreconditionsFailedException](data-api-dp-errors.md#PreconditionsFailedException)
+ [ParsingException](data-api-dp-errors.md#ParsingException)
+ [ConstraintViolationException](data-api-dp-errors.md#ConstraintViolationException)
+ [TimeLimitExceededException](data-api-dp-errors.md#TimeLimitExceededException)
+ [InvalidArgumentException](data-api-dp-errors.md#InvalidArgumentException)
+ [MissingParameterException](data-api-dp-errors.md#MissingParameterException)
+ [ConcurrentModificationException](data-api-dp-errors.md#ConcurrentModificationException)

## *查询结构：*
<a name="data-api-dp-queries-query-structures-spacer"></a>

## QueryEvalStats（结构）
<a name="QueryEvalStats"></a>

用于捕获查询统计数据的结构，例如正在运行、接受或等待的查询数量及其详细信息。

**Fields**
+ **cancelled** - 这是一个布尔值，类型为：`boolean` [布尔值（true 或 false）]。

  如果查询已取消，则设置为 `TRUE`，否则设置为 FALSE。
+ **elapsed** – 这是一个整数，类型为：`integer`（带符号的 32 位整数）。

  到目前为止，查询已运行的毫秒数。
+ **subqueries** – 这是一个文档，类型为：`document`（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  此查询中的子查询数。
+ **waited** – 这是一个整数，类型为：`integer`（带符号的 32 位整数）。

  表示查询等待了多长时间（以毫秒为单位）。

## GremlinQueryStatus（结构）
<a name="GremlinQueryStatus"></a>

捕获 Gremlin 查询的状态（请参阅 [Gremlin 查询状态 API](https://docs.aws.amazon.com/neptune/latest/userguide/gremlin-api-status.html) 页面）。

**Fields**
+ **queryEvalStats** –这是一个 [QueryEvalStats](#QueryEvalStats) 对象。

  Gremlin 查询的查询统计信息。
+ **queryId** – 这是一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  Gremlin 查询的 ID。
+ **queryString** – 这是一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  Gremlin 查询的查询字符串。

## GremlinQueryStatusAttributes（结构）
<a name="GremlinQueryStatusAttributes"></a>

包含 Gremlin 查询的状态组件。

**Fields**
+ **attributes** – 这是一个文档，类型为：`document`（由类似 JSON 的数据模型表示的与协议无关的开放内容）。

  Gremlin 查询状态的属性。
+ **code** – 这是一个整数，类型为：`integer`（带符号的 32 位整数）。

  从 Gremlin 查询请求返回的 HTTP 响应代码。
+ **message** – 这是一个字符串，类型为：`string`（UTF-8 编码的字符串）。

  状态消息。