Skip to content

Version 1.5 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

HugeGraph configuration

1 Overview

The directory for the configuration files is hugegraph-release/conf, and all the configurations related to the service and the graph itself are located in this directory.

The main configuration files include gremlin-server.yaml, rest-server.properties, and hugegraph.properties.

The HugeGraphServer integrates the GremlinServer and RestServer internally, and gremlin-server.yaml and rest-server.properties are used to configure these two servers.

  • GremlinServer: GremlinServer accepts Gremlin statements from users, parses them, and then invokes the Core code.
  • RestServer: It provides a RESTful API that, based on different HTTP requests, calls the corresponding Core API. If the user’s request body is a Gremlin statement, it will be forwarded to GremlinServer to perform operations on the graph data.

Now let’s introduce these three configuration files one by one.

2. gremlin-server.yaml

The default content of the gremlin-server.yaml file is as follows:

  1# host and port of gremlin server, need to be consistent with host and port in rest-server.properties
  2#host: 127.0.0.1
  3#port: 8182
  4
  5# timeout in ms of gremlin query
  6evaluationTimeout: 30000
  7
  8channelizer: org.apache.tinkerpop.gremlin.server.channel.WsAndHttpChannelizer
  9# don't set graph at here, this happens after support for dynamically adding graph
 10graphs: {
 11}
 12scriptEngines: {
 13  gremlin-groovy: {
 14    staticImports: [
 15      org.opencypher.gremlin.process.traversal.CustomPredicates.*',
 16      org.opencypher.gremlin.traversal.CustomFunctions.*
 17    ],
 18    plugins: {
 19      org.apache.hugegraph.plugin.HugeGraphGremlinPlugin: {},
 20      org.apache.tinkerpop.gremlin.server.jsr223.GremlinServerGremlinPlugin: {},
 21      org.apache.tinkerpop.gremlin.jsr223.ImportGremlinPlugin: {
 22        classImports: [
 23          java.lang.Math,
 24          org.apache.hugegraph.backend.id.IdGenerator,
 25          org.apache.hugegraph.type.define.Directions,
 26          org.apache.hugegraph.type.define.NodeRole,
 27          org.apache.hugegraph.traversal.algorithm.CollectionPathsTraverser,
 28          org.apache.hugegraph.traversal.algorithm.CountTraverser,
 29          org.apache.hugegraph.traversal.algorithm.CustomizedCrosspointsTraverser,
 30          org.apache.hugegraph.traversal.algorithm.CustomizePathsTraverser,
 31          org.apache.hugegraph.traversal.algorithm.FusiformSimilarityTraverser,
 32          org.apache.hugegraph.traversal.algorithm.HugeTraverser,
 33          org.apache.hugegraph.traversal.algorithm.JaccardSimilarTraverser,
 34          org.apache.hugegraph.traversal.algorithm.KneighborTraverser,
 35          org.apache.hugegraph.traversal.algorithm.KoutTraverser,
 36          org.apache.hugegraph.traversal.algorithm.MultiNodeShortestPathTraverser,
 37          org.apache.hugegraph.traversal.algorithm.NeighborRankTraverser,
 38          org.apache.hugegraph.traversal.algorithm.PathsTraverser,
 39          org.apache.hugegraph.traversal.algorithm.PersonalRankTraverser,
 40          org.apache.hugegraph.traversal.algorithm.SameNeighborTraverser,
 41          org.apache.hugegraph.traversal.algorithm.ShortestPathTraverser,
 42          org.apache.hugegraph.traversal.algorithm.SingleSourceShortestPathTraverser,
 43          org.apache.hugegraph.traversal.algorithm.SubGraphTraverser,
 44          org.apache.hugegraph.traversal.algorithm.TemplatePathsTraverser,
 45          org.apache.hugegraph.traversal.algorithm.steps.EdgeStep,
 46          org.apache.hugegraph.traversal.algorithm.steps.RepeatEdgeStep,
 47          org.apache.hugegraph.traversal.algorithm.steps.WeightedEdgeStep,
 48          org.apache.hugegraph.traversal.optimize.ConditionP,
 49          org.apache.hugegraph.traversal.optimize.Text,
 50          org.apache.hugegraph.traversal.optimize.TraversalUtil,
 51          org.apache.hugegraph.util.DateUtil,
 52          org.opencypher.gremlin.traversal.CustomFunctions,
 53          org.opencypher.gremlin.traversal.CustomPredicate
 54        ],
 55        methodImports: [
 56          java.lang.Math#*,
 57          org.opencypher.gremlin.traversal.CustomPredicate#*,
 58          org.opencypher.gremlin.traversal.CustomFunctions#*
 59        ]
 60      },
 61      org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {
 62        files: [scripts/empty-sample.groovy]
 63      }
 64    }
 65  }
 66}
 67serializers:
 68  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphBinaryMessageSerializerV1,
 69      config: {
 70        serializeResultToString: false,
 71        ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]
 72      }
 73  }
 74  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
 75      config: {
 76        serializeResultToString: false,
 77        ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]
 78      }
 79  }
 80  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0,
 81      config: {
 82        serializeResultToString: false,
 83        ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]
 84      }
 85  }
 86  - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV3d0,
 87      config: {
 88        serializeResultToString: false,
 89        ioRegistries: [org.apache.hugegraph.io.HugeGraphIoRegistry]
 90      }
 91  }
 92metrics: {
 93  consoleReporter: {enabled: false, interval: 180000},
 94  csvReporter: {enabled: false, interval: 180000, fileName: ./metrics/gremlin-server-metrics.csv},
 95  jmxReporter: {enabled: false},
 96  slf4jReporter: {enabled: false, interval: 180000},
 97  gangliaReporter: {enabled: false, interval: 180000, addressingMode: MULTICAST},
 98  graphiteReporter: {enabled: false, interval: 180000}
 99}
100maxInitialLineLength: 4096
101maxHeaderSize: 8192
102maxChunkSize: 8192
103maxContentLength: 65536
104maxAccumulationBufferComponents: 1024
105resultIterationBatchSize: 64
106writeBufferLowWaterMark: 32768
107writeBufferHighWaterMark: 65536
108ssl: {
109  enabled: false
110}

There are many configuration options mentioned above, but for now, let’s focus on the following options: channelizer and graphs.

  • graphs: This option specifies the graphs that need to be opened when the GremlinServer starts. It is a map structure where the key is the name of the graph and the value is the configuration file path for that graph.
  • channelizer: The GremlinServer supports two communication modes with clients: WebSocket and HTTP (default). If WebSocket is chosen, users can quickly experience the features of HugeGraph using Gremlin-Console, but it does not support importing large-scale data. It is recommended to use HTTP for communication, as all peripheral components of HugeGraph are implemented based on HTTP.

By default, the GremlinServer serves at localhost:8182. If you need to modify it, configure the host and port settings.

  • host: The hostname or IP address of the machine where the GremlinServer is deployed. Currently, HugeGraphServer does not support distributed deployment, and GremlinServer is not directly exposed to users.
  • port: The port number of the machine where the GremlinServer is deployed.

Additionally, you need to add the corresponding configuration gremlinserver.url=http://host:port in rest-server.properties.

3. rest-server.properties

The default content of the rest-server.properties file is as follows:

 1# bind url
 2# could use '0.0.0.0' or specified (real)IP to expose external network access
 3restserver.url=http://127.0.0.1:8080
 4#restserver.enable_graphspaces_filter=false
 5# gremlin server url, need to be consistent with host and port in gremlin-server.yaml
 6#gremlinserver.url=http://127.0.0.1:8182
 7
 8graphs=./conf/graphs
 9
10# The maximum thread ratio for batch writing, only take effect if the batch.max_write_threads is 0
11batch.max_write_ratio=80
12batch.max_write_threads=0
13
14# configuration of arthas
15arthas.telnet_port=8562
16arthas.http_port=8561
17arthas.ip=127.0.0.1
18arthas.disabled_commands=jad
19
20# authentication configs
21# choose 'org.apache.hugegraph.auth.StandardAuthenticator' or
22# 'org.apache.hugegraph.auth.ConfigAuthenticator'
23#auth.authenticator=
24
25# for StandardAuthenticator mode
26#auth.graph_store=hugegraph
27# auth client config
28#auth.remote_url=127.0.0.1:8899,127.0.0.1:8898,127.0.0.1:8897
29
30# for ConfigAuthenticator mode
31#auth.admin_token=
32#auth.user_tokens=[]
33
34# TODO: Deprecated & removed later (useless from version 1.5.0)
35# rpc server configs for multi graph-servers or raft-servers
36#rpc.server_host=127.0.0.1
37#rpc.server_port=8091
38#rpc.server_timeout=30
39
40# rpc client configs (like enable to keep cache consistency)
41#rpc.remote_url=127.0.0.1:8091,127.0.0.1:8092,127.0.0.1:8093
42#rpc.client_connect_timeout=20
43#rpc.client_reconnect_period=10
44#rpc.client_read_timeout=40
45#rpc.client_retries=3
46#rpc.client_load_balancer=consistentHash
47
48# raft group initial peers
49#raft.group_peers=127.0.0.1:8091,127.0.0.1:8092,127.0.0.1:8093
50
51# lightweight load balancing (beta)
52server.id=server-1
53server.role=master
54
55# slow query log
56log.slow_query_threshold=1000
57
58# jvm(in-heap) memory usage monitor, set 1 to disable it
59memory_monitor.threshold=0.85
60memory_monitor.period=2000
  • restserver.url: The URL at which the RestServer provides its services. Modify it according to the actual environment. If you can’t connet to server from other IP address, try to modify it as specific IP; or modify it as http://0.0.0.0 to listen all network interfaces as a convenient solution, but need to take care of the network area that might access.
  • graphs: The RestServer also needs to open graphs when it starts. This option is a map structure where the key is the name of the graph and the value is the configuration file path for that graph.

Note: Both gremlin-server.yaml and rest-server.properties contain the graphs configuration option, and the init-store command initializes based on the graphs specified in the graphs section of gremlin-server.yaml.

The gremlinserver.url configuration option is the URL at which the GremlinServer provides services to the RestServer. By default, it is set to http://localhost:8182. If you need to modify it, it should match the host and port settings in gremlin-server.yaml.

4. hugegraph.properties

hugegraph.properties is a type of file. If the system has multiple graphs, there will be multiple similar files. This file is used to configure parameters related to graph storage and querying. The default content of the file is as follows:

 1# gremlin entrence to create graph
 2gremlin.graph=org.apache.hugegraph.HugeFactory
 3
 4# cache config
 5#schema.cache_capacity=100000
 6# vertex-cache default is 1000w, 10min expired
 7#vertex.cache_capacity=10000000
 8#vertex.cache_expire=600
 9# edge-cache default is 100w, 10min expired
10#edge.cache_capacity=1000000
11#edge.cache_expire=600
12
13# schema illegal name template
14#schema.illegal_name_regex=\s+|~.*
15
16#vertex.default_label=vertex
17
18backend=rocksdb
19serializer=binary
20
21store=hugegraph
22
23raft.mode=false
24raft.safe_read=false
25raft.use_snapshot=false
26raft.endpoint=127.0.0.1:8281
27raft.group_peers=127.0.0.1:8281,127.0.0.1:8282,127.0.0.1:8283
28raft.path=./raft-log
29raft.use_replicator_pipeline=true
30raft.election_timeout=10000
31raft.snapshot_interval=3600
32raft.backend_threads=48
33raft.read_index_threads=8
34raft.queue_size=16384
35raft.queue_publish_timeout=60
36raft.apply_batch=1
37raft.rpc_threads=80
38raft.rpc_connect_timeout=5000
39raft.rpc_timeout=60000
40
41# if use 'ikanalyzer', need download jar from 'https://github.com/apache/hugegraph-doc/raw/ik_binary/dist/server/ikanalyzer-2012_u6.jar' to lib directory
42search.text_analyzer=jieba
43search.text_analyzer_mode=INDEX
44
45# rocksdb backend config
46#rocksdb.data_path=/path/to/disk
47#rocksdb.wal_path=/path/to/disk
48
49# cassandra backend config
50cassandra.host=localhost
51cassandra.port=9042
52cassandra.username=
53cassandra.password=
54#cassandra.connect_timeout=5
55#cassandra.read_timeout=20
56#cassandra.keyspace.strategy=SimpleStrategy
57#cassandra.keyspace.replication=3
58
59# hbase backend config
60#hbase.hosts=localhost
61#hbase.port=2181
62#hbase.znode_parent=/hbase
63#hbase.threads_max=64
64
65# mysql backend config
66#jdbc.driver=com.mysql.jdbc.Driver
67#jdbc.url=jdbc:mysql://127.0.0.1:3306
68#jdbc.username=root
69#jdbc.password=
70#jdbc.reconnect_max_times=3
71#jdbc.reconnect_interval=3
72#jdbc.ssl_mode=false
73
74# postgresql & cockroachdb backend config
75#jdbc.driver=org.postgresql.Driver
76#jdbc.url=jdbc:postgresql://localhost:5432/
77#jdbc.username=postgres
78#jdbc.password=
79
80# palo backend config
81#palo.host=127.0.0.1
82#palo.poll_interval=10
83#palo.temp_dir=./palo-data
84#palo.file_limit_size=32

Pay attention to the following uncommented items:

  • gremlin.graph: The entry point for GremlinServer startup. Users should not modify this item.
  • backend: The backend storage used, with options including memory, cassandra, scylladb, mysql, hbase, postgresql, and rocksdb.
  • serializer: Mainly for internal use, used to serialize schema, vertices, and edges to the backend. The corresponding options are text, cassandra, scylladb, and binary (Note: The rocksdb backend should have a value of binary, while for other backends, the values of backend and serializer should remain consistent. For example, for the hbase backend, the value should be hbase).
  • store: The name of the database used for storing the graph in the backend. In Cassandra and ScyllaDB, it corresponds to the keyspace name. The value of this item is unrelated to the graph name in GremlinServer and RestServer, but for clarity, it is recommended to use the same name.
  • cassandra.host: This item is only meaningful when the backend is set to cassandra or scylladb. It specifies the seeds of the Cassandra/ScyllaDB cluster.
  • cassandra.port: This item is only meaningful when the backend is set to cassandra or scylladb. It specifies the native port of the Cassandra/ScyllaDB cluster.
  • rocksdb.data_path: This item is only meaningful when the backend is set to rocksdb. It specifies the data directory for RocksDB.
  • rocksdb.wal_path: This item is only meaningful when the backend is set to rocksdb. It specifies the log directory for RocksDB.
  • admin.token: A token used to retrieve server configuration information. For example: http://localhost:8080/graphs/hugegraph/conf?token=162f7848-0b6d-4faf-b557-3a0797869c55

5. Multi-Graph Configuration

Our system can have multiple graphs, and the backend of each graph can be different, such as hugegraph_rocksdb and hugegraph_mysql, where hugegraph_rocksdb uses RocksDB as the backend, and hugegraph_mysql uses MySQL as a backend.

The configuration method is simple:

[Optional]: Modify rest-server.properties

You can modify the graph profile directory in the graphs option of rest-server.properties. The default configuration is graphs=./conf/graphs, if you want to change it to another directory then adjust the graphs option, e.g. adjust it to graphs=/etc/hugegraph/graphs, example is as follows:

1graphs=./conf/graphs

Modify hugegraph_mysql_backend.properties and hugegraph_rocksdb_backend.properties based on hugegraph.properties under conf/graphs path

The modified part of hugegraph_mysql_backend.properties is as follows:

 1backend=mysql
 2serializer=mysql
 3
 4store=hugegraph_mysql
 5
 6# mysql backend config
 7jdbc.driver=com.mysql.cj.jdbc.Driver
 8jdbc.url=jdbc:mysql://127.0.0.1:3306
 9jdbc.username=root
10jdbc.password=xxx
11jdbc.reconnect_max_times=3
12jdbc.reconnect_interval=3
13jdbc.ssl_mode=false

The modified part of hugegraph_rocksdb_backend.properties is as follows:

1backend=rocksdb
2serializer=binary
3
4store=hugegraph_rocksdb

Stop the server, execute init-store.sh (to create a new database for the new graph), and restart the server.

1$ ./bin/stop-hugegraph.sh
 1$ ./bin/init-store.sh
 2
 3Initializing HugeGraph Store...
 42023-06-11 14:16:14 [main] [INFO] o.a.h.u.ConfigUtil - Scanning option 'graphs' directory './conf/graphs'
 52023-06-11 14:16:14 [main] [INFO] o.a.h.c.InitStore - Init graph with config file: ./conf/graphs/hugegraph_rocksdb_backend.properties
 6...
 72023-06-11 14:16:15 [main] [INFO] o.a.h.StandardHugeGraph - Graph 'hugegraph_rocksdb' has been initialized
 82023-06-11 14:16:15 [main] [INFO] o.a.h.c.InitStore - Init graph with config file: ./conf/graphs/hugegraph_mysql_backend.properties
 9...
102023-06-11 14:16:16 [main] [INFO] o.a.h.StandardHugeGraph - Graph 'hugegraph_mysql' has been initialized
112023-06-11 14:16:16 [main] [INFO] o.a.h.StandardHugeGraph - Close graph standardhugegraph[hugegraph_rocksdb]
12...
132023-06-11 14:16:16 [main] [INFO] o.a.h.HugeFactory - HugeFactory shutdown
142023-06-11 14:16:16 [hugegraph-shutdown] [INFO] o.a.h.HugeFactory - HugeGraph is shutting down
15Initialization finished.
1$ ./bin/start-hugegraph.sh
2
3Starting HugeGraphServer...
4Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)...OK
5Started [pid 21614]

Check out created graphs:

1curl http://127.0.0.1:8080/graphs/
2
3{"graphs":["hugegraph_rocksdb","hugegraph_mysql"]}

Get details of the graph

1curl http://127.0.0.1:8080/graphs/hugegraph_mysql_backend
2
3{"name":"hugegraph_mysql","backend":"mysql"}
1curl http://127.0.0.1:8080/graphs/hugegraph_rocksdb_backend
2
3{"name":"hugegraph_rocksdb","backend":"rocksdb"}
Last modified 2025-09-25 · docs: docker starts up by default by setting a password (#417) (18d0dffaa)