在笔记本中使用 Neptune Workbench 魔术命令 - Amazon Neptune
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

在笔记本中使用 Neptune Workbench 魔术命令

Neptune Workbench 在笔记本中提供了许多所谓的魔术命令,可以节省大量的时间和精力。它们分为两类:行魔术命令单元格魔术命令

行魔术命令是指前面有单个百分号 (%) 的命令。它们只接受行输入,而不接受来自单元格正文其余部分的输入。Neptune Workbench 提供了以下行魔术命令:

单元格魔术命令前面有两个百分号 (%%),而不是一个百分号,它们使用单元格内容作为输入,尽管它们也可以将行内容作为输入。Neptune Workbench 提供以下单元格魔术命令:

还有两种魔术命令(行魔术命令和单元格魔术命令)可用来处理Neptune 机器学习

注意

使用 Neptune 魔术命令时,您通常可以使用 --help-h 参数获取帮助文本。有了单元格魔术命令,正文就不可能为空,所以在寻求帮助时,在正文内放上填充文字,甚至是单个字符。例如:

%%gremlin --help x

单元格或行魔术命令中的变量注入

可以在笔记本中的任何单元格或行魔术命令中使用以下格式引用笔记本中定义的变量:${VAR_NAME}

例如,假设您定义了以下变量:

c = 'code' my_edge_labels = '{"route":"dist"}'

然后,单元格魔术命令中的这一 Gremlin 查询:

%%gremlin -de $my_edge_labels g.V().has('${c}','SAF').out('route').values('${c}')

等同于:

%%gremlin -de {"route":"dist"} g.V().has('code','SAF').out('route').values('code')

适用于所有查询语言的查询参数

以下查询参数可与 Neptune Workbench 中的 %%gremlin%%opencypher%%sparql 魔术命令一起使用:

常用查询参数
  • --store-to(或 -s)- 指定用于存储查询结果的变量的名称。

  • --silent – 如果存在,则查询完成后不显示任何输出。

  • --group-by(或 -g)- 指定用于对节点进行分组的属性(例如 codeT.region)。顶点根据其分配的组进行着色。

  • --ignore-groups – 如果存在,则忽略所有分组选项。

  • --display-property(或 -d)- 指定应为每个顶点显示其值的属性。

    每种查询语言的默认值如下:

    • 对于 Gremlin:T.label

    • 对于 openCypher:~labels

    • 对于 SPARQL:type

  • --edge-display-property(或 -t)- 指定应为每个边缘显示其值的属性。

    每种查询语言的默认值如下:

    • 对于 Gremlin:T.label

    • 对于 openCypher:~labels

    • 对于 SPARQL:type

  • --tooltip-property(或 -de)- 指定一个属性,其值应显示为每个节点的工具提示。

    每种查询语言的默认值如下:

    • 对于 Gremlin:T.label

    • 对于 openCypher:~labels

    • 对于 SPARQL:type

  • --edge-tooltip-property(或 -te)- 指定一个属性,其值应显示为每个边缘的工具提示。

    每种查询语言的默认值如下:

    • 对于 Gremlin:T.label

    • 对于 openCypher:~labels

    • 对于 SPARQL:type

  • --label-max-length (或 -l)- 指定任何顶点标签的最大字符长度。默认值为 10。

  • --edge-label-max-length (或 -le)- 指定任何边缘标签的最大字符长度。默认值为 10。

    仅就 openCypher 而言,这是 --rel-label-max-length,或改而为 -rel

  • --simulation-duration(或 -sd)- 指定可视化物理模拟的最大持续时间。默认值为 1500 毫秒。

  • --stop-physics(或 -sp)- 在初始模拟稳定后禁用可视化物理特性。

这些参数的属性值可以由单个属性键组成,也可以由可以为每种标签类型指定不同属性的 JSON 字符串组成。JSON 字符串只能使用变量注入来指定。

%seed 行魔术命令

%seed 行魔术命令是一种向 Neptune 端点添加数据的便捷方式,可以用它来探索和体验 Gremlin、openCypher 或 SPARQL 查询。它提供了一个表单,您可以在其中选择要浏览的数据模型(属性图或 RDF),然后从 Neptune 提供的许多不同的样本数据集中进行选择。

%load 行魔术命令

%load 行魔术命令生成一个表单,您可以使用该表单向 Neptune 提交批量加载请求(请参阅Neptune 加载程序命令)。来源必须是与 Neptune 集群位于同一区域的 Amazon S3 路径。

%load_ids 行魔术命令

%load_ids 行魔术命令检索已提交到笔记本主机端点的负载 ID(请参阅Neptune 加载程序获取状态请求参数)。请求采用以下形式:

GET https://your-neptune-endpoint:port/loader

%load_status 行魔术命令

%load_status 行魔术命令检索已提交到笔记本主机端点的特定加载任务的加载状态,由行输入指定(请参阅Neptune 加载程序获取状态请求参数)。请求采用以下形式:

GET https://your-neptune-endpoint:port/loader?loadId=loadId

该行魔术命令如下所示:

%load_status load id

%cancel_load 行魔术命令

%cancel_load 行魔术命令取消特定的加载任务(请参阅Neptune 加载程序取消任务)。请求采用以下形式:

DELETE https://your-neptune-endpoint:port/loader?loadId=loadId

该行魔术命令如下所示:

%cancel_load load id

%status 行魔术命令

从笔记本的主机端点(%graph_notebook_config显示主机端点)检索状态信息

%gremlin_status 行魔术命令

检索 Gremlin 查询状态信息

%opencypher_status 行魔术命令(也为 %oc_status

检索 opencypher 查询的查询状态。此行魔术命令接受以下可选参数:

  • --queryId-q – 指定要显示其状态的正在运行的特定查询的 ID。

  • --cancel_query-c – 取消正在运行的查询。不取值。

  • --silent-s – 如果在取消查询时 --silent 设置为 true,则取消正在运行的查询,HTTP 响应代码为 200。否则,HTTP 响应代码将是 500

  • --store-to – 指定用于存储查询结果的变量的名称。

%sparql_status 行魔术命令

检索 SPARQL 查询状态信息

%stream_viewer 行魔术命令

如果在 Neptune 集群上启用了流,则 %stream_viewer 行魔术命令显示一个界面,允许交互式浏览 Neptune 流中记录的条目。它接受以下可选参数:

  • language – 流数据的查询语言:gremlinsparql。如果您不提供此参数,则默认值为 gremlin

  • --limit – 指定每页显示的最大流条目数。如果您不提供此参数,则默认值为 10

注意

只有引擎版本 1.0.5.1 及更早版本才完全支持 %stream_viewer 行魔术命令。

%graph_notebook_config 行魔术命令

此行魔术命令显示一个 JSON 对象,其中包含笔记本用于与 Neptune 通信的配置。配置包括:

  • host:要连接和向其发出命令的端点。

  • port:向 Neptune 发出命令时使用的端口。默认为 8182

  • auth_mode:向 Neptune 发出命令时要使用的身份验证模式。如果连接到启用了 IAM 身份验证的集群,则必须为 IAM,否则为 DEFAULT

  • load_from_s3_arn:指定一个供 %load 魔术命令使用的 Amazon S3 ARN。如果此值为空,则必须在 %load 命令中指定 ARN。

  • ssl:表示是否使用 TLS 连接到 Neptune 的布尔值。默认值为 true

  • aws_region:部署此笔记本的区域。此信息用于 IAM 身份验证和 %load 请求。

您可以通过将 %graph_notebook_config 输出复制到新单元格中并在那里对其进行更改来更改配置。然后,如果您在新的单元格上运行 %%graph_notebook_config 单元格魔术命令,则配置将相应更改。

%graph_notebook_host 行魔术命令

将行输入设置为笔记本的主机。

%graph_notebook_version 行魔术命令

%graph_notebook_version 行魔术命令返回 Neptune Workbench 笔记本的版本号。例如,版本 1.27 中引入了图形可视化。

%graph_notebook_vis_options 行魔术命令

%graph_notebook_vis_options 行魔术命令显示笔记本使用的当前可视化设置。vis.js 文档中对这些选项进行了说明。

您可以修改这些设置,方法是将输出复制到新单元格中,进行所需的更改,然后在单元格上运行 %%graph_notebook_vis_options 单元格魔术命令。

要将可视化设置恢复为其默认值,您可以使用 reset 参数运行 %graph_notebook_vis_options 行魔术命令。这将重置所有可视化设置:

%graph_notebook_vis_options reset

%statistics 行魔术命令

%statistics 行魔术命令用于检索或管理 DFE 引擎统计数据(请参阅管理 Neptune DFE 要使用的统计数据)。这个魔术命令也可用来检索图形摘要

它接受以下参数:

  • --language– 统计端点的查询语言:propertygraph(或 pg)或 rdf

    如果未提供,则默认为 propertygraph

  • --mode(或 -m)- 指定要提交的请求或操作的类型:statusdisableAutoComputeenableAutoComputerefreshdeletedetailedbasic 之一。

    如果未提供,则默认值为 status,除非指定了 --summary,在这种情况下,默认值为 basic

  • --summary – 从所选语言的统计摘要端点检索图形摘要。

  • --silent – 如果存在,则查询完成后不显示任何输出。

  • --store-to – 用于指定用来存储查询结果的变量。

%summary 行魔术命令

%summary 行魔术命令用于检索图形摘要信息。它从 Neptune 引擎版本 1.2.1.0 开始提供。

它接受以下参数:

  • --language– 统计端点的查询语言:propertygraph(或 pg)或 rdf

    如果未提供,则默认为 propertygraph

  • --detailed – 在输出中打开或关闭结构字段的显示。

    如果未提供,则默认为 basic 摘要显示模式。

  • --silent – 如果存在,则查询完成后不显示任何输出。

  • --store-to – 用于指定用来存储查询结果的变量。

%%graph_notebook_config 单元格魔术命令

如果可能,%%graph_notebook_config 单元格魔术命令使用包含配置信息的 JSON 对象来修改笔记本用于与 Neptune 通信的设置。配置采用%graph_notebook_config行魔术命令返回的相同形式。

例如:

%%graph_notebook_config { "host": "my-new-cluster-endpoint.amazon.com", "port": 8182, "auth_mode": "DEFAULT", "load_from_s3_arn": "", "ssl": true, "aws_region": "us-east-1" }

%%sparql 单元格魔术命令

%%sparql 单元格魔术命令向 Neptune 端点发出 SPARQL 查询。它接受以下可选行输入:

  • -h--help – 返回有关这些参数的帮助文本。

  • --path– 为指向 SPARQL 端点的路径添加前缀。例如,如果您指定 --path "abc/def",则调用的端点将是 host:port/abc/def

  • --expand-all – 这是一个查询可视化提示,它告诉可视化工具在图形示意图中包含所有 ?s ?p ?o 结果,而无论绑定类型如何。

    默认情况下,SPARQL 可视化仅包含三重模式,其中 o?uribnode(空白节点)。所有其它 ?o 绑定类型(例如文本字符串或整数)都视为 ?s 节点的属性,可以使用图形选项卡中的详细信息窗格查看这些属性。

    如果您想改为在可视化中包含顶点等文本值,请使用 --expand-all 查询提示。

    请勿将此可视化提示与 explain 参数结合使用,因为 explain 查询不会可视化。

  • --explain-type – 用于指定要使用的 explain 模式(dynamicstaticdetails 之一)。

  • --explain-format – 用于指定 explain 查询的响应格式(text/csvtext/html 之一)。

  • --store-to – 用于指定用来存储查询结果的变量。

explain 查询示例:

%%sparql explain SELECT * WHERE {?s ?p ?o} LIMIT 10

带有可视化提示参数的 --expand-all 可视化查询示例(请参阅SPARQL 可视化):

%%sparql --expand-all SELECT * WHERE {?s ?p ?o} LIMIT 10

%%gremlin 单元格魔术命令

%%gremlin 单元格魔术命令使用 WebSocket 向 Neptune 端点发出 Gremlin 查询。它接受可选的行输入以切换到 Gremlin explain 模式或 Gremlin profile API,以及用于修改可视化输出行为的单独可选可视化提示输入(请参阅Gremlin 可视化)。

explain 查询示例:

%%gremlin explain g.V().limit(10)

profile 查询示例:

%%gremlin profile g.V().limit(10)

带有可视化查询提示的可视化查询示例:

%%gremlin -p v,outv g.V().out().limit(10)
%%gremlin profile 查询的可选参数
  • --chop – 指定 profile 结果字符串的最大长度。如果您不提供此参数,则默认值为 250。

  • --serializer – 指定要用于结果的序列化程序。允许的值为任何有效的 MIME 类型或 TinkerPop 驱动程序“Serializers”枚举值。如果您不提供此参数,则默认值为 application.json

  • --no-results – 仅显示结果计数。如果不使用,则默认情况下,所有查询结果都会显示在配置文件报告中。

  • --indexOps – 显示所有索引操作的详细报告。

%%opencypher 单元格魔术命令(也为 %%oc

%%opencypher 单元格魔术命令(也具有缩写 %%oc 形式)向 Neptune 端点发出 openCypher 查询。它接受以下可选的行输入参数:

  • mode – 查询模式:querybolt。如果您不提供此参数,则默认值为 query

  • --group-by-g – 指定用于对节点进行分组的属性。例如,code, ~id。如果您不提供此参数,则默认值为 ~labels

  • --ignore-groups – 如果存在,则忽略所有分组选项。

  • --display-propery-d - 指定应为每个顶点显示其值的属性。如果您不提供此参数,则默认值为 ~labels

  • --edge-display-propery-de - 指定应为每个边缘显示其值的属性。如果您不提供此参数,则默认值为 ~labels

  • --label-max-length-l – 指定要显示的顶点标签的最大字符数。如果您不提供此参数,则默认值为 10

  • --store-to-s - 指定用于存储查询结果的变量的名称。

  • --plan-cache-pc - 指定要使用的计划缓存模式。默认值为 auto

  • --query-timeout-qt - 指定最大查询超时时间(以毫秒为单位)。默认值为 1800000

  • --query-parametersqp - 要应用于查询的参数定义。此选项可以接受单个变量名称,也可以接受映射的字符串表示。

    --query-parameters 的用法示例
    1. 在一个笔记本单元格中定义 openCypher 参数的映射。

      params = '''{ "name":"john", "age": 20, }'''
    2. 使用 %%oc 将参数传递到另一个单元格的 --query-parameters 中。

      %%oc --query-parameters params MATCH (n {name: $name, age: $age}) RETURN n

%%graph_notebook_vis_options 单元格魔术命令

%%graph_notebook_vis_options 单元格魔术命令可让您为笔记本设置可视化选项。您可以将 %graph-notebook-vis-options 行魔术命令返回的设置复制到新的单元格中,对其进行更改,然后使用 %%graph_notebook_vis_options 单元格魔术命令设置新值。

vis.js 文档中对这些选项进行了说明。

要将可视化设置恢复为其默认值,您可以使用 reset 参数运行 %graph_notebook_vis_options 行魔术命令。这将重置所有可视化设置:

%graph_notebook_vis_options reset

%neptune_ml 行魔术命令

可以使用 %neptune_ml 行魔术命令来启动和管理各种 Neptune ML 操作。

注意

还可以使用 %%neptune_ml 单元格魔术命令启动和管理一些 Neptune ML 操作。

  • %neptune_ml export start – 开始新的导出任务。

    Parameters
    • --export-url exporter-endpoint -(可选)可以在其中调用导出程序的 Amazon API Gateway 端点。

    • --export-iam –(可选)表示必须使用 SigV4 对导出 url 的请求进行签名的标志。

    • --export-no-ssl –(可选)表示在连接到导出程序时不应使用 SSL 的标志。

    • --wait –(可选)指示操作应等到导出完成的标志。

    • --wait-interval interval-to-wait –(可选)设置导出状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待导出任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

    • --store-to location-to-store-result –(可选)用于存储导出结果的变量。如果指定 --wait,则最终状态将存储在那里。

  • %neptune_ml export status – 检索导出任务的状态。

    Parameters
    • --job-id export job ID – 要检索其状态的导出任务的 ID。

    • --export-url exporter-endpoint -(可选)可以在其中调用导出程序的 Amazon API Gateway 端点。

    • --export-iam –(可选)表示必须使用 SigV4 对导出 url 的请求进行签名的标志。

    • --export-no-ssl –(可选)表示在连接到导出程序时不应使用 SSL 的标志。

    • --wait –(可选)指示操作应等到导出完成的标志。

    • --wait-interval interval-to-wait –(可选)设置导出状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待导出任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

    • --store-to location-to-store-result –(可选)用于存储导出结果的变量。如果指定 --wait,则最终状态将存储在那里。

  • %neptune_ml dataprocessing start – 启动 Neptune ML 数据处理步骤。

    Parameters
    • --job-id ID for this job –(可选)分配给此任务的 ID。

    • --s3-input-uri S3 URI –(可选)用于查找此数据处理任务的输入的 S3 URI。

    • --config-file-name file name –(可选)此数据处理任务的配置文件的名称。

    • --store-to location-to-store-result -(可选)用于存储数据处理结果的变量。

    • --instance-type (instance type) -(可选)用于此数据处理任务的实例大小。

    • --wait –(可选)指示操作应等到数据处理完成的标志。

    • --wait-interval interval-to-wait –(可选)设置数据处理状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待数据处理任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

  • %neptune_ml dataprocessing status – 检索数据处理任务的状态。

    Parameters
    • --job-id ID of the job – 要检索其状态的任务的 ID。

    • --store-to instance type -(可选)用于存储模型训练结果的变量。

    • --wait –(可选)指示操作应等到模型训练完成的标志。

    • --wait-interval interval-to-wait –(可选)设置模型训练状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待数据处理任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

  • %neptune_ml training start– 启动 Neptune ML 模型训练过程。

    Parameters
    • --job-id ID for this job –(可选)分配给此任务的 ID。

    • --data-processing-id dataprocessing job ID –(可选)创建用于训练的构件的数据处理任务的 ID。

    • --s3-output-uri S3 URI –(可选)用于存储此模型训练任务的输出的 S3 URI。

    • --instance-type (instance type) –(可选)用于此模型训练任务的实例大小。

    • --store-to location-to-store-result –(可选)用于存储模型训练结果的变量。

    • --wait –(可选)指示操作应等到模型训练完成的标志。

    • --wait-interval interval-to-wait –(可选)设置模型训练状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待模型训练任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

  • %neptune_ml training status – 检索 Neptune ML 模型训练任务的状态。

    Parameters
    • --job-id ID of the job – 要检索其状态的任务的 ID。

    • --store-to instance type -(可选)用于存储状态结果的变量。

    • --wait –(可选)指示操作应等到模型训练完成的标志。

    • --wait-interval interval-to-wait –(可选)设置模型训练状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待数据处理任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

  • %neptune_ml endpoint create– 为 Neptune ML 模型创建查询端点。

    Parameters
    • --job-id ID for this job –(可选)分配给此任务的 ID。

    • --model-job-id model-training job ID –(可选)要为其创建查询端点的模型训练任务的 ID。

    • --instance-type (instance type) –(可选)用于查询端点的实例大小。

    • --store-to location-to-store-result –(可选)用于存储端点创建结果的变量。

    • --wait –(可选)指示操作应等到端点创建完成的标志。

    • --wait-interval interval-to-wait –(可选)设置状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待端点创建任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

  • %neptune_ml endpoint status – 检索 Neptune ML 查询端点的状态。

    Parameters
    • --job-id endpoint creation ID –(可选)要报告其状态的端点创建任务的 ID。

    • --store-to location-to-store-result –(可选)用于存储状态结果的变量。

    • --wait –(可选)指示操作应等到端点创建完成的标志。

    • --wait-interval interval-to-wait –(可选)设置状态检查之间的时间(以秒为单位,默认值:60)。

    • --wait-timeout timeout-seconds –(可选)设置等待端点创建任务完成后再返回最新状态的时间(以秒为单位,默认值:3600)。

%%neptune_ml 单元格魔术命令

%%neptune_ml 单元格魔术命令会忽略行输入,例如 --job-id--export-url。相反,它允许您在单元格正文内提供这些输入和其它输入。

也可以将此类输入保存在另一个单元格中,分配给 Jupyter 变量,然后使用该变量将它们注入单元格正文中。这样,可以一遍又一遍地使用这样的输入,而不必每次都重新输入。

只有当注入变量是单元格的唯一内容时,这才起作用。不能在一个单元格中使用多个变量,也不能使用文本和变量的组合。

例如,%%neptune_ml export start 单元格魔术命令可以在单元格正文中使用包含用于控制 Neptune 导出过程的参数中描述的所有参数的 JSON 文档。

Neptune-ML-01-Introduction-to-Node-Classification-Gremlin 笔记本中,在导出数据和模型配置部分的配置特征下,您可以看到以下单元格如何在分配给名为 export-params 的 Jupyter 变量的文档中保存导出参数:

export_params = { "command": "export-pg", "params": { "endpoint": neptune_ml.get_host(), "profile": "neptune_ml", "useIamAuth": neptune_ml.get_iam(), "cloneCluster": False }, "outputS3Path": f'{s3_bucket_uri}/neptune-export', "additionalParams": { "neptune_ml": { "targets": [ { "node": "movie", "property": "genre" } ], "features": [ { "node": "movie", "property": "title", "type": "word2vec" }, { "node": "user", "property": "age", "type": "bucket_numerical", "range" : [1, 100], "num_buckets": 10 } ] } }, "jobSize": "medium"}

运行此单元格时,Jupyter 会以该名称保存该参数文档。然后,可以使用 ${export_params} 将 JSON 文档注入到 %%neptune_ml export start cell 的正文中,如下所示:

%%neptune_ml export start --export-url {neptune_ml.get_export_service_host()} --export-iam --wait --store-to export_results ${export_params}

%%neptune_ml 单元格魔术命令的可用形式

%%neptune_ml 单元格魔术命令可以按下列形式使用:

  • %%neptune_ml export start – 启动 Neptune ML 导出过程。

  • %%neptune_ml dataprocessing start– 启动 Neptune ML 数据处理任务。

  • %%neptune_ml training start– 启动 Neptune ML 模型训练任务。

  • %%neptune_ml endpoint create– 为模型创建 Neptune ML 查询端点。