Graph Service configuration

NebulaGraph provides two initial configuration files for the Graph Service, nebula-graphd.conf.default and nebula-graphd.conf.production. Users can use them in different scenarios conveniently. The default file path is /usr/local/nebula/etc/.

Caution

• It is not recommended to modify the value of local_config to false. If modified, the NebulaGraph service will first read the cached configurations, which may cause configuration inconsistencies between clusters and cause unknown risks.
• It is not recommended to modify the configurations that are not introduced in this topic, unless you are familiar with the source code and fully understand the function of configurations.

How to use the configuration files

To use the initial configuration file, choose one of the above two files and delete the suffix .default or .production from the initial configuration file for the Meta Service to apply the configurations defined in it.

About parameter values

If a parameter is not set in the configuration file, NebulaGraph uses the default value. Not all parameters are predefined. And the predefined parameters in the two initial configuration files are different. This topic uses the parameters in nebula-metad.conf.default.

Caution

Some parameter values in the configuration file can be dynamically modified during runtime. We label these parameters as Yes that supports runtime dynamic modification in this article. When the local_config value is set to true, the dynamically modified configuration is not persisted, and the configuration will be restored to the initial configuration after the service is restarted. For more information, see Modify configurations.

For all parameters and their current values, see Configurations.

Basics configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
daemonize	true	When set to true, the process is a daemon process.	No
pid_file	pids/nebula-graphd.pid	The file that records the process ID.	No
enable_optimizer	true	When set to true, the optimizer is enabled.	No
timezone_name	-	Specifies the NebulaGraph time zone. This parameter is not predefined in the initial configuration files. The system default value is UTC+00:00:00. For the format of the parameter value, see Specifying the Time Zone with TZ. For example, --timezone_name=UTC+08:00 represents the GMT+8 time zone.	No
default_charset	utf8	Specifies the default charset when creating a new graph space.	No
default_collate	utf8_bin	Specifies the default collate when creating a new graph space.	No
local_config	true	When set to true, the process gets configurations from the configuration files.	No

Note

• While inserting property values of time types, NebulaGraph transforms time types (except TIMESTAMP) to the corresponding UTC according to the time zone specified by timezone_name. The time-type values returned by nGQL queries are all UTC time.
• timezone_name is only used to transform the data stored in NebulaGraph. Other time-related data of the NebulaGraph processes still uses the default time zone of the host, such as the log printing time.

Logging configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
log_dir	logs	The directory that stores the Graph service log. It is recommended to put logs on a different hard disk from the data.	No
minloglevel	0	Specifies the minimum level of the log. That is, log messages at or above this level. Optional values are 0 (INFO), 1 (WARNING), 2 (ERROR), 3 (FATAL). It is recommended to set it to 0 during debugging and 1 in a production environment. If it is set to 4, NebulaGraph will not print any logs.	Yes
v	0	Specifies the detailed level of VLOG. That is, log all VLOG messages less or equal to the level. Optional values are 0, 1, 2, 3, 4, 5. The VLOG macro provided by glog allows users to define their own numeric logging levels and control verbose messages that are logged with the parameter v. For details, see Verbose Logging.	Yes
logbufsecs	0	Specifies the maximum time to buffer the logs. If there is a timeout, it will output the buffered log to the log file. 0 means real-time output. This configuration is measured in seconds.	No
redirect_stdout	true	When set to true, the process redirects thestdout and stderr to separate output files.	No
stdout_log_file	graphd-stdout.log	Specifies the filename for the stdout log.	No
stderr_log_file	graphd-stderr.log	Specifies the filename for the stderr log.	No
stderrthreshold	3	Specifies the minloglevel to be copied to the stderr log.	No
timestamp_in_logfile_name	true	Specifies if the log file name contains a timestamp. true indicates yes, false indicates no.	No

Query configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
accept_partial_success	false	When set to false, the process treats partial success as an error. This configuration only applies to read-only requests. Write requests always treat partial success as an error. A partial success query will prompt Got partial result.	Yes
session_reclaim_interval_secs	60	Specifies the interval that the Session information is sent to the Meta service. This configuration is measured in seconds.	Yes
max_allowed_query_size	4194304	Specifies the maximum length of queries. Unit: bytes. The default value is 4194304, namely 4MB.	Yes

Networking configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
meta_server_addrs	127.0.0.1:9559	Specifies the IPs (or hostnames) and ports of all Meta Services. Multiple addresses are separated with commas.	No
local_ip	127.0.0.1	Specifies the local IP (or hostname) for the Graph Service. The local IP address is used to identify the nebula-graphd process. If it is a distributed cluster or requires remote access, modify it to the corresponding address.	No
listen_netdev	any	Specifies the listening network device.	No
port	9669	Specifies RPC daemon listening port of the Graph service.	No
reuse_port	false	When set to false, the SO_REUSEPORT is closed.	No
listen_backlog	1024	Specifies the maximum length of the connection queue for socket monitoring. This configuration must be modified together with the net.core.somaxconn.	No
client_idle_timeout_secs	28800	Specifies the time to expire an idle connection. The value ranges from 1 to 604800. The default is 8 hours. This configuration is measured in seconds.	No
session_idle_timeout_secs	28800	Specifies the time to expire an idle session. The value ranges from 1 to 604800. The default is 8 hours. This configuration is measured in seconds.	No
num_accept_threads	1	Specifies the number of threads that accept incoming connections.	No
num_netio_threads	0	Specifies the number of networking IO threads. 0 is the number of CPU cores.	No
num_max_connections	0	Max active connections for all networking threads. 0 means no limit. Max connections for each networking thread = num_max_connections / num_netio_threads	No
num_worker_threads	0	Specifies the number of threads that execute queries. 0 is the number of CPU cores.	No
ws_ip	0.0.0.0	Specifies the IP address for the HTTP service.	No
ws_http_port	19669	Specifies the port for the HTTP service.	No
heartbeat_interval_secs	10	Specifies the default heartbeat interval. Make sure the heartbeat_interval_secs values for all services are the same, otherwise NebulaGraph CANNOT work normally. This configuration is measured in seconds.	Yes
storage_client_timeout_ms	-	Specifies the RPC connection timeout threshold between the Graph Service and the Storage Service. This parameter is not predefined in the initial configuration files. You can manually set it if you need it. The system default value is 60000 ms.	No
slow_query_threshold_us	200000	When the execution time of a query exceeds the value, the query is called a slow query. Unit: Microsecond. Note: Even if the execution time of DML statements exceeds this value, they will not be recorded as slow queries.	No
ws_meta_http_port	19559	Specifies the Meta service listening port used by the HTTP protocol. It must be consistent with the ws_http_port in the Meta service configuration file.	No

Caution

It is recommended to use a real IP when using IP address. Otherwise, 127.0.0.1/0.0.0.0 cannot be parsed correctly in some cases.

Authorization configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
enable_authorize	false	When set to false, the system authentication is not enabled. For more information, see Authentication.	No
auth_type	password	Specifies the login method. Available values are password, ldap, and cloud.	No

Memory configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
system_memory_high_watermark_ratio	0.8	Specifies the trigger threshold of the high-level memory alarm mechanism. If the system memory usage is higher than this value, an alarm mechanism will be triggered, and NebulaGraph will stop querying. This parameter is not predefined in the initial configuration files.	Yes

Metrics configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
enable_space_level_metrics	false	Enable or disable space-level metrics. Such metric names contain the name of the graph space that it monitors, for example, query_latency_us{space=basketballplayer}.avg.3600. You can view the supported metrics with the curl command. For more information, see Query NebulaGraph metrics.	No

Session configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
max_sessions_per_ip_per_user	300	The maximum number of active sessions that can be created from a single IP adddress for a single user.	No

Experimental configurations

Note

The switch of the experimental feature is only available in the Community Edition.

Name	Predefined value	Description	Whether supports runtime dynamic modifications
enable_experimental_feature	false	Specifies the experimental feature. Optional values are true and false.	No
enable_data_balance	true	Whether to enable the BALANCE DATA feature. Only works when enable_experimental_feature is true.	No

Memory tracker configurations

Note

Memory Tracker is a memory management tool designed to monitor and limit memory usage. For large-scale queries, Memory Tracker can prevent Out Of Memory (OOM) issues. If you're using Memory Tracker in a containerized environment, you need to add the relevant configurations to the configuration file of the Graph service.

1. Create the directory /sys/fs/cgroup/graphd/, and then add and configure the memory.max file under the directory.

2. Add the following configurations to etc/nebula-graphd.conf.

   --containerized=true
   --cgroup_v2_controllers=/sys/fs/cgroup/graphd/cgroup.controllers
   --cgroup_v2_memory_stat_path=/sys/fs/cgroup/graphd/memory.stat
   --cgroup_v2_memory_max_path=/sys/fs/cgroup/graphd/memory.max
   --cgroup_v2_memory_current_path=/sys/fs/cgroup/graphd/memory.current
   

For more details, see Memory Tracker: Memory Management Practice in NebulaGraph Database.

Name	Predefined value	Description	Whether supports runtime dynamic modifications
memory_tracker_limit_ratio	0.8	The value of this parameter can be set to (0, 1], 2, and 3. Caution: When setting this parameter, ensure that the value of system_memory_high_watermark_ratio is not set to 1, otherwise the value of this parameter will not take effect. (0, 1]: The percentage of available memory. Formula: Percentage of available memory = Available memory / (Total memory - Reserved memory). When an ongoing query results in memory usage exceeding the configured limit, the query fails and subsequently the memory is released. Note: For the hybrid deployment of a cluster with cloud-based and on-premises nodes, the value of memory_tracker_limit_ratio should be set to a lower value. For example, when the graphd is expected to occupy only 50% of memory, the value can be set to less than 0.5. 2: Dynamic Self Adaptive mode. MemoryTracker dynamically adjusts the available memory based on the system's current available memory. Note: This feature is experimental. As memory usage cannot be monitored in real time in dynamic adaptive mode, an OOM error may still occur to handle large memory allocations. 3: Disable MemoryTracker. MemoryTracker only logs memory usage and does not interfere with executions even if the limit is exceeded.	Yes
memory_tracker_untracked_reserved_memory_mb	50	The reserved memory that is not tracked by the memory tracker. Unit: MB.	Yes
memory_tracker_detail_log	false	Whether to enable the memory tracker log. When the value is true, the memory tracker log is generated.	Yes
memory_tracker_detail_log_interval_ms	60000	The time interval for generating the memory tracker log. Unit: Millisecond. memory_tracker_detail_log is true when this parameter takes effect.	Yes
memory_purge_enabled	true	Whether to enable the memory purge feature. When the value is true, the memory purge feature is enabled.	Yes
memory_purge_interval_seconds	10	The time interval for the memory purge feature to purge memory. Unit: Second. This parameter only takes effect if memory_purge_enabled is set to true.	Yes

performance optimization configurations

Name	Predefined value	Description	Whether supports runtime dynamic modifications
max_job_size	1	The maximum number of concurrent jobs, i.e., the maximum number of threads used in the phase of query execution where concurrent execution is possible. It is recommended to be half of the physical CPU cores.	Yes
min_batch_size	8192	The minimum batch size for processing the dataset. Takes effect only when max_job_size is greater than 1.	Yes
optimize_appendvertices	false	When enabled, the MATCH statement is executed without filtering dangling edges.	Yes
path_batch_size	10000	The number of paths constructed per thread.	Yes

---

Last update: April 19, 2024