HugeGraph-Tools Quick Start

1 概述

HugeGraph-Tools 是 HugeGragh 的自动化部署、管理和备份/还原组件。

2 获取 HugeGraph-Tools

有两种方式可以获取 HugeGraph-Tools：

  • 下载二进制tar包
  • 下载源码编译安装

2.1 下载二进制tar包

下载最新版本的 HugeGraph-Tools 包：

  1. wget https://github.com/hugegraph/hugegraph-tools/releases/download/v${version}/hugegraph-tools-${version}.tar.gz
  2. tar zxvf hugegraph-tools-${version}.tar.gz

2.2 下载源码编译安装

下载最新版本的 HugeGraph-Tools 源码包：

  1. $ git clone https://github.com/hugegraph/hugegraph-tools.git

编译生成 tar 包:

  1. cd hugegraph-tools
  2. mvn package -DskipTests

生成 tar 包 hugegraph-tools-${version}.tar.gz

3 使用

3.1 功能概览

解压后，进入 hugegraph-tools 目录，可以使用bin/hugegraph或者bin/hugegraph help来查看 usage 信息。主要分为：

  • 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get 和 graph-clear
  • 异步任务管理类，task-list、task-get、task-delete、task-cancel 和 task-clear
  • Gremlin类，gremlin-execute 和 gremlin-schedule
  • 备份/恢复类，backup、restore、migrate、schedule-backup 和 dump
  • 安装部署类，deploy、clear、start-all 和 stop-all
  1. Usage: hugegraph [options] [command] [command options]
3.2 [options]-全局变量

options是 HugeGraph-Tools 的全局变量，可以在 hugegraph-tools/bin/hugegraph 中配置,包括：

  • —graph，HugeGraph-Tools 操作的图的名字，默认值是 hugegraph
  • —url，HugeGraph-Server 的服务地址，默认是 http://127.0.0.1:8080
  • —user，当 HugeGraph-Server 开启认证时，传递用户名
  • —password，当 HugeGraph-Server 开启认证时，传递用户的密码
  • —timeout, 连接 HugeGraph-Server 时的超时时间，默认是 30s

上述全局变量，也可以通过环境变量来设置。一种方式是在命令行使用 export 设置临时环境变量，在该命令行关闭之前均有效

全局变量 环境变量 示例
—url HUGEGRAPH_URL export HUGEGRAPH_URL=http://127.0.0.1:8080
—graph HUGEGRAPH_GRAPH export HUGEGRAPH_GRAPH=hugegraph
—user HUGEGRAPH_USERNAME export HUGEGRAPH_USERNAME=admin
—password HUGEGRAPH_PASSWORD export HUGEGRAPH_PASSWORD=test
—timeout HUGEGRAPH_TIMEOUT export HUGEGRAPH_TIMEOUT=30

另一种方式是在 bin/hugegraph 脚本中设置环境变量：

  1. #!/bin/bash
  3. # Set environment here if needed
  4. #export HUGEGRAPH_URL=
  5. #export HUGEGRAPH_GRAPH=
  6. #export HUGEGRAPH_USERNAME=
  7. #export HUGEGRAPH_PASSWORD=
  8. #export HUGEGRAPH_TIMEOUT=
3.3 图管理类，graph-mode-set、graph-mode-get、graph-list、graph-get和graph-clear
  • graph-mode-set，设置图的 restore mode
    • —graph-mode 或者 -m，必填项，指定将要设置的模式，合法值包括 [NONE, RESTORING, MERGING]
  • graph-mode-get，获取图的 restore mode
  • graph-list，列出某个 HugeGraph-Server 中全部的图
  • graph-get，获取某个图及其存储后端类型
  • graph-clear，清除某个图的全部 schema 和 data
    • —confirm-message 或者 -c，必填项，删除确认信息，需要手动输入，二次确认防止误删，”I’m sure to delete all data”，包括双引号

当需要把备份的图原样恢复到一个新的图中的时候，需要先将图模式设置为 RESTORING 模式；当需要将备份的图合并到已存在的图中时，需要先将图模式设置为 MERGING 模式。

3.4 异步任务管理类，task-list、task-get和task-delete
  • task-list，列出某个图中的异步任务，可以根据任务的状态过滤
    • —status，选填项，指定要查看的任务的状态，即按状态过滤任务
    • —limit，选填项，指定要获取的任务的数目，默认为 -1，意思为获取全部符合条件的任务
  • task-get，获取某个异步任务的详细信息
    • —task-id，必填项，指定异步任务的 ID
  • task-delete，删除某个异步任务的信息
    • —task-id，必填项，指定异步任务的 ID
  • task-cancel，取消某个异步任务的执行
    • —task-id，要取消的异步任务的 ID
  • task-clear，清理完成的异步任务
    • —force，选填项，设置时，表示清理全部异步任务，未执行完成的先取消，然后清除所有异步任务。默认只清理已完成的异步任务
3.5 Gremlin类，gremlin-execute和gremlin-schedule
  • gremlin-execute，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，同步执行，结束后返回结果
    • —file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 —script 互斥
    • —script 或者 -s，指定要执行的脚本字符串，与 —file 互斥
    • —aliases 或者 -a，Gremlin 别名设置，格式为：key1=value1,key2=value2,…
    • —bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
    • —language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy

      —file 和 —script 二者互斥，必须设置其中之一

  • gremlin-schedule，发送 Gremlin 语句到 HugeGraph-Server 来执行查询或修改操作，异步执行，任务提交后立刻返回异步任务id
    • —file 或者 -f，指定要执行的脚本文件，UTF-8编码，与 —script 互斥
    • —script 或者 -s，指定要执行的脚本字符串，与 —file 互斥
    • —bindings 或者 -b，Gremlin 绑定设置，格式为：key1=value1,key2=value2,…
    • —language 或者 -l，Gremlin 脚本的语言，默认为 gremlin-groovy

      —file 和 —script 二者互斥，必须设置其中之一

3.6 备份/恢复类
  • backup，将某张图中的 schema 或者 data 备份到 HugeGraph 系统之外，以 JSON 形式存在本地磁盘或者 HDFS
    • —directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
    • —huge-types 或者 -t，要备份的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，’all’ 代表全部6种类型，即顶点、边和所有schema
    • —log 或者 -l，指定日志目录，默认为当前目录
    • —retry，指定失败重试次数，默认为 3
    • —split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576
    • -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
  • restore，将 JSON 格式存储的 schema 或者 data 恢复到一个新图中（RESTORING 模式）或者合并到已存在的图中（MERGING 模式）
    • —directory 或者 -d，存储 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
    • —huge-types 或者 -t，要恢复的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，’all’ 代表全部6种类型，即顶点、边和所有schema
    • —log 或者 -l，指定日志目录，默认为当前目录
    • —retry，指定失败重试次数，默认为 3
    • -D，用 -Dkey=value 的模式指定动态参数，用来从 HDFS 恢复图时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
  • migrate, 将图从一个 HugeGraphServer 迁移至另一个 HugeGraphServer
    • —source-graph，源图的名字
    • —source-url，源图所在的 HugeGraphServer 的URL
    • —target-graph，目标图的名字
    • —target-url，目标图所在的 HugeGraphServer
    • —directory 或者 -d，迁移过程中，存储源图的 schema 或者 data 的目录，本地目录时，默认为’./{graphName}’，HDFS 时，默认为 ‘{fs.default.name}/{graphName}’
    • —huge-types 或者 -t，要迁移的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，’all’ 代表全部6种类型，即顶点、边和所有schema
    • —log 或者 -l，指定日志目录，默认为当前目录
    • —retry，指定失败重试次数，默认为 3
    • —split-size 或者 -s，指定迁移过程中对源图进行备份时顶点或者边分块的大小，默认为 1048576
    • -D，用 -Dkey=value 的模式指定动态参数，用来在迁移图过程中需要备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
    • —graph-mode 或者 -m，将源图恢复到目标图时将目标图设置的模式，合法值包括 [RESTORING, MERGING]
    • —clean，是否删除在迁移图的过程中产生的源图的备份，默认为 true，即默认迁移图结束后清理产生的源图备份
  • schedule-backup，周期性对图执行备份操作，并保留一定数目的最新备份（目前仅支持本地文件系统）
    • —directory 或者 -d，必填项，指定备份数据的目录
    • —backup-num，选填项，指定保存的最新的备份的数目，默认为 3
    • —interval，选填项，指定进行备份的周期，格式同 Linux crontab 格式
  • dump，把整张图的顶点和边全部导出，默认以vertex vertex-edge1 vertex-edge2...JSON格式存储。用户也可以自定义存储格式，只需要在hugegraph-tools/src/main/java/com/baidu/hugegraph/formatter目录下实现一个继承自Formatter的类，例如CustomFormatter，使用时指定该类为formatter即可，例如bin/hugegraph dump -f CustomFormatter
    • —formatter 或者 -f，指定使用的 formatter，默认为 JsonFormatter
    • —directory 或者 -d，存储 schema 或者 data 的目录，默认为当前目录
    • —huge-types 或者 -t，要备份的数据类型，逗号分隔，可选值为 ‘all’ 或者 一个或多个 [vertex,edge,vertex_label,edge_label,property_key,index_label] 的组合，’all’ 代表全部6种类型
    • —log 或者 -l，指定日志目录，默认为当前目录
    • —retry，指定失败重试次数，默认为 3
    • —split-size 或者 -s，指定在备份时对顶点或者边分块的大小，默认为 1048576
    • -D，用 -Dkey=value 的模式指定动态参数，用来备份数据到 HDFS 时，指定 HDFS 的配置项，例如：-Dfs.default.name=hdfs://localhost:9000
3.7 安装部署类
  • deploy，一键下载、安装和启动 HugeGraph-Server 和 HugeGraph-Studio
    • -v，必填项，指明安装的 HugeGraph-Server 和 HugeGraph-Studio 的版本号，最新的是 0.9
    • -p，必填项，指定安装的 HugeGraph-Server 和 HugeGraph-Studio 目录
    • -u，选填项，指定下载 HugeGraph-Server 和 HugeGraph-Studio 压缩包的链接
  • clear，清理 HugeGraph-Server 和 HugeGraph-Studio 目录和tar包
    • -p，必填项，指定要清理的 HugeGraph-Server 和 HugeGraph-Studio 的目录
  • start-all，一键启动 HugeGraph-Server 和 HugeGraph-Studio，并启动监控，服务死掉时自动拉起服务
    • -v，必填项，指明要启动的 HugeGraph-Server 和 HugeGraph-Studio 的版本号，最新的是 0.9
    • -p，必填项，指定安装了 HugeGraph-Server 和 HugeGraph-Studio 的目录
  • stop-all，一键关闭 HugeGraph-Server 和 HugeGraph-Studio

deploy命令中有可选参数 -u，提供时会使用指定的下载地址替代默认下载地址下载 tar 包，并且将地址写入~/hugegraph-download-url-prefix文件中；之后如果不指定地址时，会优先从~/hugegraph-download-url-prefix指定的地址下载 tar 包；如果 -u 和~/hugegraph-download-url-prefix都没有时，会从默认下载地址进行下载

3.8 具体命令参数

各子命令的具体参数如下：

  1. Usage: hugegraph [options] [command] [command options]
  2.   Options:
  3.     --graph
  4.       Name of graph
  5.       Default: hugegraph
  6.     --password
  7.       Password of user
  8.     --timeout
  9.       Connection timeout
  10.       Default: 30
  11.     --url
  12.       The URL of HugeGraph-Server
  13.       Default: http://127.0.0.1:8080
  14.     --user
  15.       User Name
  16.   Commands:
  17.     graph-list      List all graphs
  18.       Usage: graph-list
  20.     graph-get      Get graph info
  21.       Usage: graph-get
  23.     graph-clear      Clear graph schema and data
  24.       Usage: graph-clear [options]
  25.         Options:
  26.         * --confirm-message, -c
  27.             Confirm message of graph clear is "I'm sure to delete all data". 
  28.             (Note: include "")
  30.     graph-mode-set      Set graph mode
  31.       Usage: graph-mode-set [options]
  32.         Options:
  33.         * --graph-mode, -m
  34.             Graph mode, include: [NONE, RESTORING, MERGING]
  35.             Possible Values: [NONE, RESTORING, MERGING]
  37.     graph-mode-get      Get graph mode
  38.       Usage: graph-mode-get
  40.     task-list      List tasks
  41.       Usage: task-list [options]
  42.         Options:
  43.           --limit
  44.             Limit number, no limit if not provided
  45.             Default: -1
  46.           --status
  47.             Status of task
  49.     task-get      Get task info
  50.       Usage: task-get [options]
  51.         Options:
  52.         * --task-id
  53.             Task id
  54.             Default: 0
  56.     task-delete      Delete task
  57.       Usage: task-delete [options]
  58.         Options:
  59.         * --task-id
  60.             Task id
  61.             Default: 0
  63.     task-cancel      Cancel task
  64.       Usage: task-cancel [options]
  65.         Options:
  66.         * --task-id
  67.             Task id
  68.             Default: 0
  70.     task-clear      Clear completed tasks
  71.       Usage: task-clear [options]
  72.         Options:
  73.           --force
  74.             Force to clear all tasks, cancel all uncompleted tasks firstly, 
  75.             and delete all completed tasks
  76.             Default: false
  78.     gremlin-execute      Execute Gremlin statements
  79.       Usage: gremlin-execute [options]
  80.         Options:
  81.           --aliases, -a
  82.             Gremlin aliases, valid format is: 'key1=value1,key2=value2...'
  83.             Default: {}
  84.           --bindings, -b
  85.             Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
  86.             Default: {}
  87.           --file, -f
  88.             Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
  89.             --script 
  90.           --language, -l
  91.             Gremlin script language
  92.             Default: gremlin-groovy
  93.           --script, -s
  94.             Gremlin script to be executed, exclusive to --file
  96.     gremlin-schedule      Execute Gremlin statements as asynchronous job
  97.       Usage: gremlin-schedule [options]
  98.         Options:
  99.           --bindings, -b
  100.             Gremlin bindings, valid format is: 'key1=value1,key2=value2...'
  101.             Default: {}
  102.           --file, -f
  103.             Gremlin Script file to be executed, UTF-8 encoded, exclusive to 
  104.             --script 
  105.           --language, -l
  106.             Gremlin script language
  107.             Default: gremlin-groovy
  108.           --script, -s
  109.             Gremlin script to be executed, exclusive to --file
  111.     backup      Backup graph schema/data. If directory is on HDFS, use -D to 
  112.             set HDFS params if needed. For exmaple: 
  113.             -Dfs.default.name=hdfs://localhost:9000 
  114.       Usage: backup [options]
  115.         Options:
  116.           --directory, -d
  117.             Directory of graph schema/data, default is './{graphname}' in 
  118.             local file system or '{fs.default.name}/{graphname}' in HDFS
  119.           --huge-types, -t
  120.             Type of schema/data. Concat with ',' if more than one. 'all' means 
  121.             all vertices, edges and schema, in other words, 'all' equals with 
  122.             'vertex,edge,vertex_label,edge_label,property_key,index_label' 
  123.             Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
  124.           --log, -l
  125.             Directory of log
  126.             Default: ./logs
  127.           --retry
  128.             Retry times, default is 3
  129.             Default: 3
  130.           --split-size, -s
  131.             Split size of shard
  132.             Default: 1048576
  133.           -D
  134.             HDFS config parameters
  135.             Syntax: -Dkey=value
  136.             Default: {}
  138.     schedule-backup      Schedule backup task
  139.       Usage: schedule-backup [options]
  140.         Options:
  141.           --backup-num
  142.             The number of latest backups to keep
  143.             Default: 3
  144.         * --directory, -d
  145.             The directory of backups stored
  146.           --interval
  147.             The interval of backup, format is: "a b c d e". 'a' means minute 
  148.             (0 - 59), 'b' means hour (0 - 23), 'c' means day of month (1 - 
  149.             31), 'd' means month (1 - 12), 'e' means day of week (0 - 6) 
  150.             (Sunday=0), "*" means all
  151.             Default: "0 0 * * *"
  153.     dump      Dump graph to files
  154.       Usage: dump [options]
  155.         Options:
  156.           --directory, -d
  157.             Directory of graph schema/data, default is './{graphname}' in 
  158.             local file system or '{fs.default.name}/{graphname}' in HDFS
  159.           --formatter, -f
  160.             Formatter to customize format of vertex/edge
  161.             Default: JsonFormatter
  162.           --huge-types, -t
  163.             Type of schema/data. Concat with ',' if more than one. 'all' means 
  164.             all vertices, edges and schema, in other words, 'all' equals with 
  165.             'vertex,edge,vertex_label,edge_label,property_key,index_label' 
  166.             Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
  167.           --log, -l
  168.             Directory of log
  169.             Default: ./logs
  170.           --retry
  171.             Retry times, default is 3
  172.             Default: 3
  173.           --split-size, -s
  174.             Split size of shard
  175.             Default: 1048576
  176.           -D
  177.             HDFS config parameters
  178.             Syntax: -Dkey=value
  179.             Default: {}
  181.     restore      Restore graph schema/data. If directory is on HDFS, use -D to 
  182.             set HDFS params if needed. For 
  183.             exmaple:-Dfs.default.name=hdfs://localhost:9000 
  184.       Usage: restore [options]
  185.         Options:
  186.           --clean
  187.             Whether to remove the directory of graph data after restored
  188.             Default: false
  189.           --directory, -d
  190.             Directory of graph schema/data, default is './{graphname}' in 
  191.             local file system or '{fs.default.name}/{graphname}' in HDFS
  192.           --huge-types, -t
  193.             Type of schema/data. Concat with ',' if more than one. 'all' means 
  194.             all vertices, edges and schema, in other words, 'all' equals with 
  195.             'vertex,edge,vertex_label,edge_label,property_key,index_label' 
  196.             Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
  197.           --log, -l
  198.             Directory of log
  199.             Default: ./logs
  200.           --retry
  201.             Retry times, default is 3
  202.             Default: 3
  203.           -D
  204.             HDFS config parameters
  205.             Syntax: -Dkey=value
  206.             Default: {}
  208.     migrate      Migrate graph
  209.       Usage: migrate [options]
  210.         Options:
  211.           --clean
  212.             Whether to remove the directory of graph data after restored
  213.             Default: true
  214.           --directory, -d
  215.             Directory of graph schema/data, default is './{graphname}' in 
  216.             local file system or '{fs.default.name}/{graphname}' in HDFS
  217.           --graph-mode, -m
  218.             Mode used when migrating to target graph, include: [RESTORING, 
  219.             MERGING] 
  220.             Default: RESTORING
  221.             Possible Values: [NONE, RESTORING, MERGING]
  222.           --huge-types, -t
  223.             Type of schema/data. Concat with ',' if more than one. 'all' means 
  224.             all vertices, edges and schema, in other words, 'all' equals with 
  225.             'vertex,edge,vertex_label,edge_label,property_key,index_label' 
  226.             Default: [PROPERTY_KEY, VERTEX_LABEL, EDGE_LABEL, INDEX_LABEL, VERTEX, EDGE]
  227.           --log, -l
  228.             Directory of log
  229.             Default: ./logs
  230.           --retry
  231.             Retry times, default is 3
  232.             Default: 3
  233.           --source-graph
  234.             The source graph to migrate
  235.             Default: hugegraph
  236.           --source-url
  237.             The source graph url to migrate
  238.             Default: http://127.0.0.1:8080
  239.           --split-size, -s
  240.             Split size of shard
  241.             Default: 1048576
  242.           --target-graph
  243.             The target graph to migrate
  244.             Default: hugegraph
  245.           --target-url
  246.             The target graph url to migrate
  247.             Default: http://127.0.0.1:8081
  248.           -D
  249.             HDFS config parameters
  250.             Syntax: -Dkey=value
  251.             Default: {}
  253.     deploy      Install HugeGraph-Server and HugeGraph-Studio
  254.       Usage: deploy [options]
  255.         Options:
  256.         * -p
  257.             Install path of HugeGraph-Server and HugeGraph-Studio
  258.           -u
  259.             Download url prefix path of HugeGraph-Server and HugeGraph-Studio
  260.         * -v
  261.             Version of HugeGraph-Server and HugeGraph-Studio
  263.     start-all      Start HugeGraph-Server and HugeGraph-Studio
  264.       Usage: start-all [options]
  265.         Options:
  266.         * -p
  267.             Install path of HugeGraph-Server and HugeGraph-Studio
  268.         * -v
  269.             Version of HugeGraph-Server and HugeGraph-Studio
  271.     clear      Clear HugeGraph-Server and HugeGraph-Studio
  272.       Usage: clear [options]
  273.         Options:
  274.         * -p
  275.             Install path of HugeGraph-Server and HugeGraph-Studio
  277.     stop-all      Stop HugeGraph-Server and HugeGraph-Studio
  278.       Usage: stop-all
  280.     help      Print usage
  281.       Usage: help