Reference

Access Control and Security

Parameter Description Node
thirdPartyAuthenticator Specifies a function view (which takes the same arguments as login) for third-party authentication. Users can connect to a third-party system through DolphinDB plugins such as HttpClient. Once specified, DolphinDB server authenticates the user login through the third-party system. controller
thirdPartyCreateUserCallback Specifies one or multiple function views (split with comma) to execute when the createUser has been used. The callbacks will be invoked in the order they are specified, from left to right. Note: Exceptions during the callback will be caught and logged, but only the last one will be thrown after all callbacks have finished executing. controller
thirdPartyDeleteUserCallback Specifies one or multiple function views (split with comma) to execute when the deleteUser has been used. The callbacks will be invoked in the order they are specified, from left to right. Note: Exceptions during the callback will be caught and logged, but only the last one will be thrown after all callbacks have finished executing. controller
enhancedSecurityVerification=false A Boolean value indicating whether to enable enhanced security verification, which includes password complexity verification and password retry limit. Set to false (default) to disable this function and true to enable. When it is enabled:
  • The password created or modified must meet the following conditions:
    • 8-20 characters
    • at least 1 capital letter
    • at least 1 special character, including !"#$%&'()*+,-./:;<=>?@[]^_`{|}~
  • If the server detects 5 failed login attempts within a minute, this account will be temporarily locked for 10 minutes, preventing further login attempts from the same IP address.
 controller
strictPermissionMode A Boolean value specifying whether to enable strict permission mode on the current node. The default value is false. When set to true, operations such as disk read/write are only allowed for administrators. Related functions include: saveTextFile, saveAsNpy, backup, restore, restoreDB, restoreTable, backupDB, backupTable, migrate, file, files, writeObject, readObject, loadPlugin, close, fflush, mkdir, rmdir, rm, writeLog, run, runScript, test, saveTable, savePartition, saveDualPartition, saveDatabase, saveText, loadText, loadModule, saveModule. controller/data node/compute node
enableShellFunction A Boolean value indicating whether an administrator can call the shell function. False (default) means the shell function cannot be called by any user. True means the permission to use the shell function is granted for the administrator. controller/data node/compute node
enableCoreDump=true [Linux Only] Whether to check and enable core dumps when starting DolphinDB. The default value is true. true means that DolphinDB will check if core dumps are enabled during startup. If core dumps are disabled, it will try to enable them, provided the system's hard limit allows core dumps of a sufficient size. If core dumps are already enabled, no changes will be made. False means that DolphinDB will start up without checking or modifying the system's current core dump enablement state. data node
disableCoreDumpOnShutdown =false [Linux Only] Whether to disable core dumps during a graceful shutdown. The default value is false, meaning core dumps will not be disabled during a graceful shutdown. This parameter only takes effect for the local node. data node

In a cluster setup, if a node fails, users can manually restart the node or wait for the datanodeRestartInterval time for the cluster to automatically restart the node.

Parameter Description Node
datanodeRestartInterval=0 It is a non-negative integer of int type. Its unit is second. Defaults to 0, indicating that the system will not automatically start data/compute nodes. Configure this parameter to implement the following features: (1) Automatically start the data/compute node after the controller is started (the agent needs to be started); (2) The data/compute node will be automatically restarted after its offline time is larger than the set value (for a non-graceful shutdown and the agent needs to be started). controller
datanodeRestartLevel=CRASH Specifies the triggering condition for the controller to automatically restart the data/compute node. It can take the following values (case sensitive):
  • CRASH (default): The controller will automatically restart a node if the node was not terminated gracefully and did not send heartbeats after datanodeRestartInterval.
  • OFFLINE: The controller will automatically restart a node if the node did not send heartbeats after datanodeRestartInterval.
 controller

Single Sign-On

Parameter Description
oauth A Boolean value specifying whether to enable OAuth SSO on the web interface. The default value is false, indicating that it is disabled.
oauthWebType A string specifying the OAuth type to be used by the web interface. It can be 'authorization code' (default) and 'implicit'.
oauthAuthUri A string specifying the URI of the authorization server, e.g., 'https://xxx.com/authorize'.
oauthClientId A string specifying the client ID.
oauthClientSecret A string specifying the client password. This parameter is required if oauthWebType is set to 'authorization code'.
oauthRedirectUri A string specifying the URI of the web interface. Note that if this parameter is specified, it must match the third-party callback URL; if unspecified, it defaults to the third-party callback URL for redirection.
oauthTokenUri A string specifying the token endpoint URI. This parameter is required if oauthWebType is set to 'authorization code'.
oauthTokenRequestMethod A string specifying the HTTP request method for the token. It can be 'GET' and 'POST' (default).
oauthUserUri A string specifying the URI to obtain the username, e.g., 'http://x.com/esc-sso/oauth2.0/profile'.
oauthUserRequestMethod A string specifying the HTTP request method for the username. It can be 'GET' (default) and 'POST'.
oauthUserField A string specifying the response field for the username. Note that an error occurs if the configuration doesn't match the returned field.

Note:

  • Parameters such as oauthAuthUri, oauthRedirectUri, oauthTokenUri, and oauthUserUri only support the input of strings enclosed in quotes. Values containing special characters (e.g., & and ;) need to have the entire input value enclosed in quotes.
  • If oauth is enabled, parameters oauthAuthUri, oauthClientId, oauthUserUri, and oauthUserField must be configured.

Compute-Storage Separation

Since version 3.00.2, DolphinDB has implemented a compute-storage separation architecture by introducing compute groups to clusters.

Parameter Description Node
computeNodeCacheDir Specifies the directory for compute node cache. Default: <HomeDir>/Disaggregation. Compute Node
computeNodeCacheMeta Specifies the directory for the compute node cache metadata. Default: <computeNodeCacheDir>/meta. Compute Node
computeNodeMemCacheSize A non-negative integer representing the maximum memory cache size (in MB) for the compute node. The default value is 1024, and the maximum is 5% * maxMemSize. Compute Node
computeNodeDiskCacheSize A non-negative integer representing the maximum disk cache size (in MB) for the compute node. The default value is 65536 (i.e., 64 GB). Compute Node
enableComputeNodeCacheEvictionFromQueryThread A Boolean value specifying whether query threads can perform cache eviction. Setting to true (default) improves the cache cleanup efficiency, but may increase query latency under limited cache conditions. Compute Node
computeNodeCachingDelay A non-negative integer representing the time interval (in seconds) that must elapse after the last update of a partition before it can be cached on the compute node. Default is 360. Controller
computeNodeCachingQueryThreshold A non-negative integer representing the threshold for caching based on the number of queries on a partition. The default value is 1, and the maximum is 32767. A partition can be cached on the compute node after exceeding the query threshold. Controller
enableComputeNodePrefetchData A Boolean value that determines the system's behavior during cache misses (i.e., when a partition cannot be found in the cache). When enabled (default), the system simultaneously assigns queries to the data node while initiating asynchronous cache prefetching in the compute group. This can lower latency but may increase network and CPU load due to repeated query execution. When disabled, queries are processed exclusively within the compute group. Controller

Multi-Cluster Management

Since version 3.00.2, DolphinDB has introduced an advanced multi-cluster management feature, enabling inter-cluster network communication and resource scheduling. There are two roles in multi-cluster management: MoM (master of master, a single node or the controller of the cluster) and member clusters (with their controllers as masters). To architect a multi-cluster environment, you can use the following configuration parameters.

Parameter Description Node
isMasterOfMaster A boolean value to determine whether the current node is a MoM node. On a single node or the controller of the cluster
momHeartbeatHandler A string specifying one or more function views (comma-separated) as callback functions. These functions are triggered when the MoM node receives heartbeat signals from the controller of member clusters. The heartbeats serve as inputs to these functions. When multiple functions are listed, they execute sequentially from left to right. MoM node
masterOfMasterSite A string host:port specifying the IP address and port number of the MoM node. Controllers of member clusters
clusterName A string specifying the name of the current cluster. MoM node or the controllers of member clusters

High Availability

The metadata for cluster is stored on controllers. A standard cluster contains a single controller, and its failure can lead to cluster downtime. To prevent this, DolphinDB allows multiple controllers to form a Raft group, ensuring high availability for controllers.

To enable high availability for controllers, dfsHAMode=Raft and the network information about all nodes should be specified in the configuration file for each controller (default is controller.cfg).

Parameter Description
dfsHAMode=Raft Whether the controller nodes form a raft group. It can be Raft or None (default).
raftElectionTick=800 Specify a time interval (in 10ms): [raftElectionTick, 2*raftElectionTick]. After receiving the last heartbeat from the leader, if a follower does not receive the next heartbeat after a random waiting time within the specified interval, it will send a request for leader election. The default value is 800 (8 seconds) and the interval is [8s, 16s]. raftElectionTick should be specified in controller.cfg.
Note: All controllers of the raft group must have the same configurations.

In a cluster setup, before an agent starts up, parameters localSite and controllerSite should be configured in the configuration file for agents (default is agent.cfg). In the configuration file for agent nodes (default is agent.cfg), the controllerSite parameter should be specified as the LAN information about any controller in the Raft group and the sites parameter should be added.

Parameter Description
controllerSite Host address, port number and alias of the controller site of the agent node. When an agent starts up, it uses this information to contact the controller. It must be identical as localSite of one of the controllers in controller.cfg.
sites Specifies the LAN information for the current agent node and all controllers in the cluster with the same format as localSite. Use commas to separate multiple nodes.

To ensure data security and high availability, DolphinDB supports storing multiple replicas across different servers and adopts a two-phase commit protocol to ensure strong consistency among replicas and between data and metadata. Even if the data on a server is corrupted, the service remains uninterrupted by accessing replicas on other servers. To enable data replication and backup, the following parameters need to be configured in controller.cfg:

Parameter Description
dfsReplicationFactor=2 The number of all replicas for each data chunk. The default value is 2.
dfsReplicaReliabilityLevel=0 Whether multiple replicas can reside on the same node.
  • 0 (default): Yes.
  • 1: No.
  • 2: replicas are allocated to multiple servers if possible.
dfsRecoveryWaitTime=0 In a multi-replica cluster setup, the failure of a data node can result in an inconsistency between the number of replicas in the cluster and the value of dfsReplicationFactor. The dfsRecoveryWaitTime parameter specifies the length of time (in milliseconds) before replicating the inconsistent replicas to other nodes. The minimum value is 60,000 and any value below will be automatically adjusted to 60,000. The default value is 0, indicating no automatic recovery.

Log

Log files include metadata log file, redo log, query log, system log and batch job log. They have different requirements for disk performance. Generally, metadata log and redo log should be stored on SSDs while other logs can be stored on HDDs.

Runtime Log

Upon server startup, the system automatically generates runtime information. Users can determine whether to output the information to the command line or the runtime log by setting the stdoutLog parameter in the command line.

Parameter Description
logFile=DolphinDBlog The path and name of the log file. It displays the server configuration specifications, warnings and error messages.
maxLogSize=1024 The system will archive the server log after the log reaches the specified size limit (in MB). The default value is 1024 and the minimum value is 100. Upon reaching this limit, DolphinDB automatically generates a new log with a timestamp prefix in seconds. The prefix is in the format of \date\seq, e.g. 20181109000. seq has 3 digits and starts with 000.
Note: In standalone mode, maxLogSize can only be specified in command line.
logRetentionTime=30 To prevent excessive resource usage from old logs, the logRetentionTime parameter can be used to specify the amount of time (in days) to keep a log file before deleting it. The default value is 30 (of floating-point data type). For example, 0.5 means 12 hours. If set to 0, log files are not deleted.
logLevel=INFO Specifies the level equal to and above which logs are printed to help users locate the error message in the log. From the lowest to the highest level, the possible values are DEBUG, INFO, WARNING andERROR. The default value is INFO.
Note: The log printing level can also be adjusted online using the setLogLevel function.

Redo Log

After a transaction is completed, the system automatically purges the corresponding redo logs. This process can be optimized by specifying the following parameters.

Parameter Description
redoLogPurgeInterval=30 Clear the redo log of transactions whose data have been persisted at intervals specified by redoLogPurgeInterval in terms of seconds. The default value is 30.
redoLogPurgeLimit=4 Clear the redo log of transactions whose data have been persisted if the size of the redo log exceeds redoLogPurgeLimit in terms of MB. The default value is 4.

Job Log

Parameter Description Node
batchJobDir The folder for batch job logs and results. The default value is <HomeDir>/batchJobs. data node
batchJobFileRetentionTime A floating-point number that sets the retention time (in days) for the files storing outputs (<job>.msg) and return values (<job>.obj) for batch and scheduled jobs. The default value 0 means these files will not be automatically deleted. data node

Query Log

In a cluster setup, the system also logs descriptive information of the queries for each node.

Parameter Description Node
jobLogFile=nodeAlias_job.log The path and name of the job log file that contains descriptive information of all the queries that have been executed for each node. It must be a csv file. The default folder for the job log file is the log folder. The default name of the job log file is nodeAlias_job.log. data node
jobLogRetentionTime=0 A floating-point number indicating the retention time (in days) to keep achived query logs. A query log on a node (<nodeAlias>_job.log) is archived if its size exceeds 1 GB. The default value is 0, indicating that archived logs are not to be deleted. data node

In version 2.00.11.1, a new parameter enableDFSQueryLog is added. This helps identify the queries that are taking too long or those that are in progress during a node failure, troubleshooting probable causes for node congestion or deadlocks.

Parameter Description Node
enableDFSQueryLog=false Different from parameter jobLogFile that only records executed queries, enableDFSQueryLog records all completed and ongoing queries and subqueries on DFS tables. The default value is false. To set it to true, parameter perfMonitoring must be enabled. When set to true, a query log named nodeAlias_query.log will be generated in the directory where nodeAlias_job.log is located. The query log contains the following fields: node, userId, sessionId, rootId, type, level, time, database, table, and jobDesc. Subqueries on DFS tables return a query log with fields "database" and "table" left empty. data node
queryLogRetentionTime=0 When the size of the query lognodeAlias_query.log exceeds 1 GB, the system archives the log file and subsequent logs will be written to a new file. This parameter is a floating point number indicating the retention time (in days) to keep archived query logs. The default value is 0, indicating that archived logs are not to be deleted. data node

Note: Although nodeAlias_query.log and nodeAlias_job.log share similarities in functionality and recorded fields, they differ in the following aspects:

  • nodeAlias_query.log records only complete queries.
  • nodeAlias_job.log records both complete queries and queries in progress.

SQL Trace Log

The storage path for SQL trace logs is specified by the traceLogDir parameter.

Parameter Description
traceLogDir The SQL tracing log path. The default value is <HomeDir>/traces.

DDL Trace Log

Parameter Description Node
enableAuditLog Whether to enable logging DDL operations to a separate log file. The default value is false. When set to true, an audit log will be generated in the directory <logFile>/<ALIAS>_audit.log. The maximum size of an audit log file is 128M, beyond which another file prefixed with a timestamp (in second) will be automatically generated for continuous storage of DDL operations. data node
auditLogRetentionTime A floating-point number indicating the amount of time (in days) to keep an audit log before deleting it. For example, 0.5 means 12 hours. The default value is 0, indicating that audit log files are not deleted. data node

Thread Types

DolphinDB provides the following types of threads:

  • worker: threads that handle regular interactive tasks.

    Since version 1.30.22/2.00.10, DolphinDB has introduced a multilevel task assignment algorithm which divides the jobs and tasks (broken down from jobs) into different levels. The jobs and tasks are handled by the workers at the same levels. The levels of workers range from 0 to 5.

    A job submitted to the node starts at level 0 and is handled by a level 0 worker. Based on the number of partitions involved in the job, the level 0 worker breaks it into an equivalent number of tasks. Local tasks are executed concurrently by the level 0 or level 1 workers, while remote tasks are sent to remote nodes by remote executors. Tasks sent to remote nodes are marked as level 1 and handled by level 1 workers there. If a task is further divided into subtasks, the remote subtasks are marked one level lower than their parent and handled by workers at the same level on the remote nodes.

    With different levels of workers handling different levels of jobs and tasks, deadlock issues caused by circular dependencies across nodes can be effectively prevented.

    The number of workers determines the concurrent computing capability of a system.

  • remote executor: an independent thread that sends tasks to remote computing nodes. The remote executor is failure tolerant. If one machine fails, the remote executor will send the task to another machine with the data necessary for the task.
  • batch job worker: threads that handle batch jobs. Batch jobs are submitted with function submitJob and are usually time-consuming jobs. A batch job worker will be destroyed automatically after being idle for over 60 seconds.
  • dynamic worker: if there are jobs in the queue of regular interactive jobs and no jobs are completed in the previous second, the system will create dynamic workers to process the jobs in the queue. A dynamic worker will automatically be destroyed after being idle for 60 seconds. Dynamic workers make the system more responsive and can solve deadlocks among multiple nodes.
  • web worker: threads that handle HTTP requests. DolphinDB provides a web-based cluster management interface to interact with DolphinDB nodes.
  • urgent worker: threads that only handle time-sensitive system-level jobs such as logins (login) and job cancellations (cancelJob/cancelConsoleJob). The configuration parameter urgentWorkerNum specifies the maximum number of urgent workers. The default is 1.
Parameter Description
workerNum The size of worker pool for regular interactive jobs. The default value is the number of CPU cores.
remoteExecutors=1 The number of remote executors. The default is 1. It is recommended to set it to the number of cluster nodes - 1.
maxBatchJobWorker=4 The maximum number of batch job workers. The default value is the value of workerNum.
maxDynamicWorker=4 The maximum number of dynamic workers. The default value is the value of workerNum.
webWorkerNum=1 The size of the web worker pool to process HTTP requests. The default value is 1.
urgentWorkerNum=1 The maximum number of urgent workers. The default value is 1.
enableMultiThreadMerge A Boolean value indicating whether the results of subqueries assigned to each node can be merged using multiple threads. The default value is false. When set to true, for multi-threaded merging to be effectively performed, the subquery result must contain at least two columns and have more than 50 million entries. This configuration parameter can provide a significant performance boost for queries involving a large number of partitions.
openblasThreads The number of threads that can be used by OpenBLAS. It is applicable to matrix computing.

Memory Management

To avoid the OOM issues caused by insufficient memory in queries and calculations on large-scalr data, DolphinDB offers the following parameters for memory optimization.

Parameter Description
maxMemSize=0 The maximum memory (in units of GB) allocated to DolphinDB. If set to 0, it means no limits on memory usage. The value of maxMemSize cannot exceed the machine memory.
warningMemSize When memory usage exceeds warningMemSize (in units of GB), the system will automatically clean up the cache of some databases to avoid OOM exceptions. The default value is 75% of MaxMemSize.
reservedMemSize=5% * maxMemSize A positive number specified in units of GB. When the available memory in DolphinDB is less than reservedMemSize, DolphinDB only allocates a memory block of limited size (as specifiedby maxBlockSizeForReservedMemory) for each memory request. reservedMemSize is provided to restrict the memory allocation for each memory request to improve the likelihood that there is enough memory for critical operations that use a small amount of memory (error reporting, rollbacks, etc.). For example, when data writes fail due to insufficient memory, the transactions can be rolled back to guarantee data consistency. If the parameter is not specified, the system sets reservedMemSize = 5% * maxMemSize and reservedMemSize must be between 64MB and 1GB.
maxBlockSizeForReservedMemory=8 The maximum size (in units of KB) of the memory block that DolphinDB allocates for each memory request when its available memory is less than reservedMemSize. The default value is 64. It is not recommended to set it too high as exceptions or crashes may occur if there isn't enough memory left for critical database operations.
memoryReleaseRate=5 Specifies the rate at which unused memory is released to the operating system. It is a floating point number between 0 and 10. The default value is 5. memoryReleaseRate = 0 means that unused memory will not be released actively; memoryReleaseRate = 10 means that memory will be released at the fastest speed. memoryReleaseRate is equivalent to the TCMALLOC_RELEASE_RATE flag of TCMalloc.
dataSync=0 Whether database logs are forced to persist to disk before the transaction is committed. If dataSync=1, the redo logs, data, and metadata are forced to persist to disk. If dataSync=0 (default), the operating system will decide when to write the log files to disk.

DolphinDB offers regular arrays and big arrays. Regular arrays use continuous memory, which enhances performance. However, if there is not enough continuous memory, an out-of-memory exception may occur. In contrast, big arrays use small memory blocks to relieve the memory fragmentation issue. This, however, may come with light performance penalty for certain operations.

Parameter Description
regularArrayMemoryLimit=2048 The limit on the maximum memory size (in MB) of a regular array. Its value must be a power of 2. The default value is 2048 (MB). The actual available memory is min(regularArrayMemoryLimit, maxMemSize/2). If the memory occupied by an array exceeds this limit, the system will create a big array instead.

Hard Disk

Parameter Description
volumes The folder where data files are saved in the distributed file system on a data node. Users can specify multiple volumes across different disks for higher read and write performance. The default value is:
  • For standalone mode: <HomeDir>/storage
  • For cluster mode: <HomeDir>/<nodeAlias>/storage
chunkMetaDir The folder for the metadata on each data node. The default value is the first path specified by the volumes parameter.
allowVolumeCreation=true Sets the parameter to determine whether a volume can be created automatically if the volume does not exist. The value can be 0 or 1. The default value 1 indicates to create volumes automatically. If the parameter is set to 0, the system will report an error if the volume does not exist.
volumeUsageThreshold=0.97 Specifies the upper limit of volume usage on a data node. It is a floating-point value in (0, 1]. The default value is 0.97. When the volume usage on a data node reaches the threshold, new chunks are not allowed to be created on the node, but data can be written to existing chunks. The parameter can only be configured on the controller.
diskIOConcurrencyLevel=1 Specifies the number of threads for reading and writing to disk for I/O improvement. The default value is 1. diskIOConcurrencyLevel = 0 means the threads handling the relevant tasks will read and write to the disk. When diskIOConcurrencyLevel > 0, the system will create the specified number of threads to read and write to the disk concurrently. For HDDs, it is recommended to set diskIOConcurrencyLevel to the number of volumes configured on the node (specified by the configuration parameter volumes). For SSDs, it is recommended to set diskIOConcurrencyLevel = 0
useHardLink=true Whether to use the hardlink feature of the file system. Set to true to use the system hardlink feature; Set to false to not use the hardlink feature. The default value is true.
maxFileHandles=1024 Sets the maximum number of file descriptors open in a DolphinDB process.

Since version 2.00.9, DolphinDB supports trading calendars for functions temporalAdd, resample, asFreq, and transFreq.

Parameter Description
marketHolidayDir Specifies the directory to the file of market holidays. Either absolute or relative directory can be specified. The system searches the relative directory in the following order: home directory of the node, the working directory of the node, and the directory with the DolphinDB executable. The default directory is <HomeDir> /marketHoliday. The file must be a single-column CSV file with DATE data. Based on the CSV files under marketHolidayDir, a trading calendar is created with the file name as its identifier. Note:
  • Weekends are recognized as holidays by default, therefore, only weekday holidays need to be filled in the file.
  • It is recommended to name the file in Market Identifier Code, e.g., "XNYS.csv".

In the distributed file system, the metadata of the cluster is stored in files DFSMetaLog.xxx and DSFMetaCheckpoint.xxx on controllers. The storage path can be specified by the dfsMetaDir parameter.

Parameter Description Node
dfsMetaDir The directory to save the metadata of the distributed file system. The default value is:
  • Standalone mode: <HomeDir>/<nodeAlias>/dfsMeta
  • Regular cluster mode: <HomeDir>
  • High availability cluster mode: <HomeDir>/<nodeAlias>/dfsMeta (<nodeAlias> is the alias for the leader)
 controller

Network

To reduce network transmission costs, it is recommended to allocate all cluster nodes within the same LAN.

Parameter Description
localSite The LAN information of the node, including host address, port number and alias of the node, separated by ":".In standalone mode, the default value is localhost:8848:local8848. If the port is occupied, it can be modified in the corresponding configuration file. Assigning an alias helps quickly identify and connect to a specific node. For example, users can set the server parameter of subscribeTable as the alias of a remote node to subscribe to the stream table published by this node. Use getNodeAlias to get the alias of the current node and use getControllerAlias to get the alias of the controller.

Since version 2.00.9, license server is supported for resource allocation. License server is only available with license of type 3. You may contact our technical support for more information.

Parameter Description
mode Node mode. It can be “controller“, “agent“, “datanode“, or “computenode“. mode must be specified in the configuration file of each node.
computeGroup Specifies the compute group that a compute node belongs to. It can only be added after a compute node using the format host:port:alias,computenode,groupName. For example, to specify a compute node belonging to group orca, 192.168.1.10:8080:node1,computenode,orca.

The following TCP configuration parameters allow users to optimize communication. Enabling these parameters can reduce transmission latency, but may increase network load.

Parameter Description
tcpNoDelay=1 Whether to enable the TCP_NODELAY socket option. The default value is false.
tcpUserTimeout=300000 Set the socket option TCP_USER_TIMEOUT. The default value is 300000 (in ms).

The controller monitors the status of other nodes through a heartbeat mechanism, which can use either TCP or UDP for transmission. The related configuration parameters are as follows:

Parameter Description
lanCluster=true Whether the cluster is within a LAN. If set to true (default), use UDP for heartbeats. If set to false, use TCP for heartbeats. Set lanCluster = false if the system is deployed in the cloud.
Note: lanCluster should be specified in the corresponding configuration file of agent, data node, or compute node.
dfsChunkNodeHeartBeatTimeout=8 An integer indicating the time interval (in seconds) for marking a

data node/compute node/agent as down. If the controller has not received heartbeat message from a node for more than this time interval, the node will be marked and treated as down. A larger value is recommended for a poor network. The default value is 8.

In a cluster, a local node can be connected to other remote nodes and sessions created by API, GUI, or Web notebook.

Parameter Description
maxConnectionPerSite=2 The maximum number of connections from the local node to remote nodes. Minimum is 16. The default value is set to (workerNum + webWorkerNum + 1), with a minimum value of 16.
maxConnections=64 The maximum number of connections (from GUI, API, other nodes, etc) to the local node.
enableHTTPS=false Whether to enable HTTPS protocol. The default value is false.
publicName Within a LAN, the cluster's web interface can be directly accessed using the controller’s IP address and port. If the controller is not in the same LAN as other nodes, the external network information must be configured through the publicName parameter. It consists of the internet IP or domain name of the controller. If enableHTTPS=true, publicName must be specified as the domain name.

RDMA allows one computer system's memory to directly access the memory of other computer systems without involving the central processing unit (CPU). To enable RDMA in DolphinDB:

  • Using RDMA technology requires special network interface cards (NICs) and other hardware support. Consider the compatibility of RDMA NICs with existing hardware and ensure correct installation of the current operating system and drivers.
  • The libibverbs library must be downloaded on all machines in the cluster.
  • The enableRDMA configuration parameter must be enabled on all cluster nodes (controller, data nodes, compute nodes, and agent).
Parameter Description
enableRDMA [Linux Only] A BOOLEAN value indicating whether to enable RDMA. The default value is false, meaning RDMA is not enabled.

Starting from versions 2.00.14/3.00.2, DolphinDB offers centralized resource distribution and management through a public license server, which is hosted and maintained by DolphinDB on the public internet. Enabling the public license server mode requires a specialized license file (type 3), registration and configurations. Contact DolphinDB technical support for more information.

Note: Before configuring the following parameters, make sure a licenseServer.lic file (which can be obtained from DolphinDB support team) has been placed under the server directory.

Parameter Description Node
useLicenseServer Boolean. When true, starts in license server mode. When false (default), starts as a regular node using local license file. Standalone server, or all types of nodes in a cluster
coreAffinity String specifying CPU core IDs for the node. Separate multiple IDs by ","; consecutive IDs can use "-" (e.g., "1,2,3,4" or "1-4" for binding cores 1 to 4).
  • For nodes with this configuration:
    • When specified, process runs on designated cores;
    • When unspecified, binds to first workerNum cores.
  • Node startup requires:
    • Specified cores exist on physical machine;
    • Number of bound cores ≤ workerNum.
 Standalone server, or all types of nodes in a cluster. Only configurable for nodes requesting resources from license server

Recovery and Rebalance

Online recovery repairs inconsistent or corrupted data replicas in a distributed file system (DFS). The online recovery process consists of the following two stages:

  • In the synchronous stage, the source node (with intact replica) identifies the maximum CID of the target node (with inconsistent replica) and copies the differential data.
  • In the synchronous stage, The source node copies the remaining data to the target node.
Parameter Description
dfsSyncRecoveryChunkRowSize=1000 A positive integer with a default value of 1000. During data recovery, asynchronous replicationis switched to synchronous replication when the differential records between replicas is less than dfsSyncRecoveryChunkRowSize.
dfsRecoveryConcurrency The number of concurrent recovery tasks in a node recovery. This parameter can be adjusted to increase the concurrency of recovery tasks, thus further improve the speed of inter-node data recovery. The default value is twice the number of all data nodes in the cluster.
recoveryWorkers=1 An integer indicating the number of workers that can be used to recover chunks synchronously in node recovery. The default value is 1.
Note:
  • If the number of exsting threads is fewer than that of the newly configured threads, the system will create the missing threads. If it is larger, the system will block and reclaim the excess threads.
  • There is no hard upper limit on recoveryWorkers, but it is subject to the constraints of the operating system.

Data rebalancing can be divided into two modes:

  • Intra-node rebalancing (through rebalanceChunksWithinDataNode): Rebalance data in the chunks of a data node after volumes are added to this node, improving I/O performance.
  • Inter-node rebalancing (through rebalanceChunksAmongDataNodes): Rebalance data among nodes when data is unevenly distributed across nodes in a cluster.
Parameter Description
dfsRebalanceConcurrency The number of concurrent rebalance tasks in a node rebalance. The default value is twice the number of all nodes except the agent.
enableDfsRecoverRedo=true Whether to enable recovery redo log. If set to true, the redo log for node recovery transactions is enabled, where the data related to recovery transactions is written. This helps minimize the impact of node downtime or disconnection on the recovery process.
recoverLogDir=<LogDir>/recoverLog The directory of the recovery redo log. It must be stored on a separate disk (preferably SSD) from the data files. The default is <LogDir>/recoverLog.

Asynchronous Replication

Master Cluster

The parameters clusterReplicationSlaveNum and clusterReplicationMode must be configured.

Parameter Description Node
clusterReplicationSlaveNum Specifies the upper limit of slave clusters. The default value is 2. controller
clusterReplicationMode Specifies whether the cluster is master or slave cluster. data node
clusterReplicationWorkDir Specifies the working directory where data of write tasks on the master cluster is stored. The default value is <HomeDir>/clusterReplication. A larger-sized SSD is recommended. data node
clusterReplicationSyncPersistence=false Specifies a Boolean value indicating whether to persist data of write tasks synchronously or asynchronously. Note: Synchronous persistence ensures data consistency but may affect transaction efficiency, while asynchronous persistence improves performance but may cause data loss in node crashes. data node

Slave Cluster

The parameters clusterReplicationMasterCtl and clusterReplicationMode must be configured.

Parameter Description Node
clusterReplicationMasterCtl Specifies ip:port of the controller in the master cluster. For a high-availability (HA) cluster, you can specify any controller in a raft group. controller
clusterReplicationMode Specifies whether the cluster is master or slave cluster. data node
clusterReplicationExecutionUsername Specifies the username (default=admin) used to execute operations regarding cluster replication. The specified user must have relevant privileges on transactions, otherwise the asynchronous tasks will fail. data node
clusterReplicationExecutionPassword Specifies the user password (default=123456) for clusterReplicationExecutionUsername.
Note: Since version 2.00.13/3.00.1, the user is not required to specify this parameter.
 data node
clusterReplicationQueue A positive integer specifying the number of execution queues. The default value is 4 times the number of data nodes. controller
clusterReplicationWorkerNum The number of workers (task execution threads) on each data node. The default value is max(workerNum/4, 4). data node

Job Management

There are two types of jobs in DolphinDB, interactive jobs and asynchronous jobs. Most tasks submitted via scripts are interactive jobs. Asynchronous jobs mainly refer to batch and scheduled jobs. For more information, refer to Job Management.

Interactive Jobs

The maximum number of concurrent interactive jobs that can be executed on a node is determined by the number of workers and web workers. The submitted interactive jobs are added to a queue, from which the workers consume the jobs submitted via non-web clients and the web workers consume the ones submitted via the Web interface.

Parameter Description
workerNum=4 The size of worker pool for regular interactive jobs. The default value is the number of CPU cores.
webWorkerNum=1 The size of the web worker pool to process HTTP requests. The default value is 1.

Asynchronous Jobs

Asynchronous jobs include batch jobs, scheduled jobs, and streaming jobs. Batch jobs are submitted with submitJob or submitJobEx.

Parameter Description
maxBatchJobWorker=4 The maximum number of batch job workers. If it is exceeded, the incoming batch jobs will enter a queue. The default value is the value of workerNum.
maxCachedBatchJobNum=2048 The maximum number of batch jobs in the batch job queue. Batch jobs in the queue are automatically destroyed after being idle for more than 60 seconds. The default value is 2048.

Job Parallelism

Parameter Description
jobParallelismHardLimit=false A Boolean value indicating whether to set the limit on the maximum number of workers a task can use. The default value is false. If it is set to true, the maximum number of workers a task can use cannot exceed the specified parallelism.
defaultJobParallelism=2 A positive integer in range (0,64] indicating the default parallelism of the background task submitted by users. The default value is 2. Note that if the value of this parameter falls outside the specified range, the server fails to start.

Streaming

The following parameters need to be configured to initiate streaming data persistence:

Parameter Description
persistenceDir= /home/DolphinDB/Data/Persistence The directory where shared streaming tables are persisted to. To enable persistence, persistenceDir must be specified. In a cluster, each data node should be configured with different persistenceDir.
persistenceWorkerNum=1 The number of workers responsible for persisting streaming tables to disk in asynchronous mode. The default value is 0.

The streaming data persistence feature in DolphinDB mainly serves the following purposes:

  • Backup and restore streaming data. When a node reboots, the persisted data can be automatically loaded into the stream table.
  • Avoid out-of-memory problems.
  • Resubscribe from any position.

Publisher Node

The following parameters can be configured on the publisher node:

Parameter Description
maxMsgNumPerBlock=1024 The maximum number of records in a message block. The default value is 1024.
maxPersistenceQueueDepth= 10000000 The maximum depth (number of records) of a message queue to persist a stream table to disk. The default value is 10,000,000.
maxPubQueueDepthPerSite= 10000000 The maximum depth (number of records) of a message queue on the publisher node. The default value is 10,000,000.
maxPubConnections=0 The maximum number of subscriber nodes that the publisher node can connect to. The default value is 0. For the node to server as a publisher, we must set maxPubConnections>0.

Subscriber Node

The following parameters can be configured on the subscriber node:

Parameter Description
subPort=8000 The port number that the subscription thread is listening on. Before version 2.00.9, this parameter must be specified to enable the node(s) to serve as subscriber(s). Since version 2.00.9, this parameter can be unspecified.
maxSubConnections=64 The maximum number of publisher nodes that the subscriber node can connect to. The default value is 64.
maxSubQueueDepth= 10000000 The maximum depth (number of records) of a message queue on the subscriber node. The default value is 10,000,000.
subExecutorPooling=false A Boolean value indicating whether streaming executors use pooling mode. The default value is false. If it is set to 0, it means the thread can conduct message parsing and can also process messages.
subExecutors=1 The number of message processing threads in the subscriber node. Only when subscription is enabled is this parameter relevant. The default value is 1. If it is set to 0, it means the thread can conductmessage parsing and can also process messages.
subThrottle=1000 A non-negative integer in milliseconds, indicating the interval at which the system checks whether throttle in function subscribeTable has been reached. The default value is 1000. If the interval specified by the parameter throttle in subscribeTable is less than the configuration parameter subThrottle, the parameter handler in subscribeTable will be triggered to process messages at an interval of subThrottle. To set throttle is less than 1 second, you need to modify the configuration parameter subThrottle first. For example, to set throttle =0.001 (second), please set subThrottle =1 first. Note: This parameter is only valid if the parameter batchSize is specified in function subscribeTable.
localSubscriberNum=1 Sets the number of threads used to distribute the messages from the publish queue if the publisher and subscriber are on the same node. The default value is 1. If a number greater than 1 is specified, the system will allocate the threads to distribute messages in parallel to the processing threads.

If a subscriber crashes while consuming streaming data, it may lose track of the consumption progress upon restart. To solve this issue, the offset of the subscribed consumption data can be persisted to disk through the persistenceOffsetDir parameter.

Parameter Description
persistenceOffsetDir=/home/DolphinDB/streamlog The directory where the offset of consumption data from the subscriber is persisted to. If persistenceOffsetDir is unspecified but persistenceDir is specified, the offset is saved in persistenceDir. If neither is specified, the offset is saved in /home/DolphinDB/streamlog.

High Availability

Streaming data persistence of publishers must be initiated before enabling HA stream tables. DolphinDB utilizes the Raft groups consisted of data nodes for HA streaming.

Parameter Description
streamingHAMode=raft Enable high-availability for streaming.
streamingRaftGroups = 2:NODE1:NODE2:NODE3,3:NODE3:NODE4:NODE5 Information about raft groups. Each raft group is represented by group ID and aliases of data nodes in the group, separated with colon (:). Raft group ID must be an integer greater than 1. Each raft group has at least 3 data nodes. Use comma (,) to seperate multiple raft groups.
streamingHADir=<HomeDir>/log/streamLog The directory to keep streaming raft log files. The default value is <HomeDir>/log/streamLog. Each data node should be configured with different streamingHADir.
streamingHAPurgeInterval=300 The interval to garbage collect raft logs in seconds. The increase of raft logs may affect the replay efficiency in case of node recovery. The Raft protocol implements log truncation using checkpoints. Note that the performance may be affected by the checkpoint operations: Frequent checkpoints may affect the disk bandwidth, while rare checkpoints may cause a large number of logs to be replayed after node startup. The default value is 300.

SQL Queries

In a cluster setup, when a user initiates a query on a DFS table from a connected node (coordinator), the coordinator splits the query based on the partitions involved and maps the subqueries to the relevant nodes. If the number of partitions or the volume of data is excessively large, memory overflow may occur when summarizing the data. To prevent this issue, the following parameters can be configured:

Parameter Description Node
maxPartitionNumPerQuery=65536 The maximum number of partitions that a single query can search. The default value is 65536. data node/compute node
checkExistingPartitionNumForQuery Whether to use the number of existing partitions obtained from the controller to check if the number of partitions for a single query exceeds the maximum (configured by maxPartitionNumPerQuery). False (default) means that the number of partitions set in partitioning scheme is used. data node/compute node
memLimitOfQueryResult The memory limit for a query result. The default value is min(50% * maxMemSize, 8G), and it must be smaller than 80% * maxMemSize. data node/compute node
memLimitOfTaskGroupResult In the Map phase of MapReduce, a single query is divided into several tasks, among which the remote tasks are sent to remote nodes in batches (task groups). The configuration parameter is used to set the memory limit of a task group sent from the current node. The default value is min(20% * maxMemSize, 2G),and it must be smaller than 50% * maxMemSize. data node/compute node
memLimitOfTempResult=1
Note: This configuration is deprecated since 2.00.13/3.00.1 version. Please use memLimitOfAllTempResults instead.
Specifies the maximum memory usage (in GB) for each temporary result generated during SQL distributed queries. The default value is 1. The maximum value is capped by the maxMemSize parameter. If a temporary result exceeds the specified memory limit, it is spilled to disk in the directory specified by tempResultsSpillDir. Temporary files are automatically deleted after query completion.		 data node/compute node
tempResultsSpillDir=tempResults Specifies the directory for storing temporary results generated during distributed queries when they exceed memory limits. The default directory is <HomeDir>/tempResults. Temporary results exceeding the memory limit (specified by memLimitOfAllTempResults) are spilled to the directory. Files are automatically deleted after query completion. Note: This directory is recreated after server reboot, deleting any existing contents. data node/compute node

memLimitOfAllTempResults

 Specifies the total memory limit (in GB) for all temporary results generated during SQL distributed queries. The default value is 20% * maxMemSize. If the memory usage exceeds the limit, temporary results are spilled to disk. data node/compute node

Database and Table

Parameter Description
enableChunkGranularityConfig=false Specifies the chunk granularity to determine the level of the lock of a DolphinDB transaction. When writing to a chunk, the transaction locks it to prevent other transactions from writing to it. Before version 1.30.16/2.00.4, the chunk granularity is set at the database level, i.e., each partition in the database is a chunk. In this case, concurrent writes to different tablets in the same partition are not allowed. This configuration parameter was released with version 1.30.16/2.00.4. The default value is false, which indicates the chunk granularity is at the table level, i.e., each tablet of a partition is a chunk. Concurrent writes to different tables in the same partition are thus allowed. If it is set to true, you can specify the chunk granularity with the parameter chunkGranularity of function database.
newValuePartitionPolicy=skip Specifies how new data outside of existing VALUE partitions are handled in databases. It can be "add", "skip", or "fail".
  • skip (default): appends data that belongs to existing VALUE partitions and ignores out-of-scope data.
  • add: Creates new VALUE partitions to add all data.
  • fail: Throws exception if out-of-scope data is included. None of the data will be written. In most cases, add is recommended.
oldChunkVersionRetentionTime= 60 Sets the retention time (in minutes) for the old chunk versions. The upper limit is 240. When SQL update/upsert/delete is executed, the system generates a new replica of the chunk (named by "table_name_tid") to perform the update and delete operations. Each old chunk will be retained in the system for the specified retention time, and a maximum of 5 old chunks can be kept at the same time.
allowMissingPartitions=true Specifies the behavior when incoming data contains new partition values that do not match any existing partitions. true (default) means to write the data that belongs to existing partitions and ignore the out-of-scope data. false means not to write any incoming data to the database and throw an exception. Note: For VALUE partitions where newValuePartitionPolicy is set to "add" or "fail", data will be handled based on the corresponding rules. In those cases, allowMissingPartitions does not take effect.
enableLocalDatabase=true A Boolean value indicating whether to enable the creation of a local database. The default value is true. Once configured, it takes effect for all nodes in the cluster.

enableInsertStatementForDFSTable

Whether to enable the insert into statement for DFS tables. The default value is false.
enableConcurrentDimensionalTableWrite =false Whether to allow conducting concurrent write or update/delete on dimension tables. The default value is false, indicating concurrent write and update/delete is disabled for dimension tables.
removeSpecialCharInColumnName=false Whether to allow column names to contain special characters or to start without a letter. The default value is false, which can be used to remove the special characters in the column names generated by pivot by. Specify the value as true to be compatible with version 1.30.14 and before.

Each persisted MVCC table has a log file. Operations (including adding, deleting and modifying) on an MVCC table are first written to the log. When the number of operations reaches mvccCheckpointThreshold, a log checkpoint is initiated, where the operations are performed on the table and the log is cleared. Note that when you load an MVCC table with loadMvccTable, the log file needs to be replayed. If the amount of data in the log is too large, it may take a long time to replay, or even result in an OOM event. To solve this issue, the mvccCheckpointThreshold parameter can be specified to control the amount of data in the log.

Parameter Description
mvccCheckpointThreshold =5000000 Sets the threshold for the number of operations on an MVCC table to trigger a checkpoint. The value can be set in [100,000, 2^31-1], and the default value is 5,000,000. The number of operations on an MVCC table are counted as below:
  • For adds (append!, tableInsert, insert into) and updates (update): the number of applied rows multiplied by the number of applied columns;
  • For deletes (delete): the number of applied rows.

TSDB

Parameter Description
TSDBRedoLogDir=<HomeDir>/log/TSDBRedo The directory of the redo log of TSDB engine. The default value is <HomeDir>/log/TSDBRedo. In cluster mode, it is necessary to ensure that different TSDBRedoLogDir are configured on the data nodes of the same machine.

TSDBMeta (including level file metadata) is stored in <HomeDir>/log, and transaction data is stored in <HomeDir>/storage/CHUNKS. To configure this parameter:

  1. Use the relative paths, i.e., do not start with '/';
  2. Include <ALIAS> in the path: /home/xxx/<ALIAS>/redolog;
  3. Configure for each node separately: node1.TSDBRedoLogDir=/home/xxx/node1/redolog, node2.TSDBRedoLogDir=/home/xxx/node2/redolog.

The TSDB engine caches SYMBOL base during read/write operations. An LRU (Least Recently Used) policy is employed to manage this cache, with two configuration parameters determining when to evict SYMBOL base cache based on time or capacity limits. Only SYMBOL base entries absent from both the cache engine and ongoing transactions will be evicted based on LRU.

Parameter Description Node
TSDBSymbolBaseEvictTime=3600 A positive integer indicating the maximum amount of time (in seconds) to keep cached SYMBOL base entries before they are evicted. The default value is 3600. When exceeded, the system evicts the cached SYMBOL base entries. data node
TSDBCachedSymbolBaseCapacity A positive number indicating the maximum capacity (in GB) for cached SYMBOL base. The default value is 5% of maxMemSize, with a 128MB minimum. When exceeded, the system evicts the entries that hasn't been accessed for the longest period first, until the cache size meets the limit. data node
TSDBCacheEngineSize A positive number indicating the capacity (in GB) of the TSDB cache engine. The default value is 1. The memory used by the cache engine may reach twice the set value as an extra memoryblock will be allocated to cache the incoming data while data in the original memory is being flushed to disk. If the flush process is not fast enough, the newly allocated memory may also reach TSDBCacheEngineSize and thus block the writer thread. If the parameter is set too small, data in the cache engine may be flushed to disk too frequently, thus affecting the write performance; If set too high, a large volume of cached data is not flushed to disk until it reaches TSDBCacheEngineSize (or after 10 minutes). If power failure or shutdownoccurs in such cases, numerous redo logs are to be replayed when the system is restarting, causing a slow startup.

In the TSDB engine, the data writing process involves three stages: sorting, compaction, and flushing. The following parameters can be specified to configure the data writing process:

Parameter Description
TSDBAsyncSortingWorkerNum=1 A non-negative integer indicating the number of threads for asynchronous sorting in the TSDB cache engine. The default value is 1. Data written to the TSDB cache engine are sorted by sortColumns. The tasks of writing and sorting data can be processed either synchronously or asynchronously and the asynchronous mode optimizes writing performance. Set it to 0 to enable the synchronous mode.
TSDBCacheTableBufferThreshold=16384 The threshold for batch sorting cached data in the TSDB engine. Once the number of cached records reaches TSDBCacheTableBufferThreshold, the cache engine initiates the sorting.
TSDBCacheFlushWorkNum The number of threads for the flushing process of the TSDB cache engine. The default value is the number of disk volumes configured by parameter volumes. If volumes is less than the number of disk volumes, TSDBCacheFlushWorkNum is set to default.
TSDBLevelFileIndexCacheSize=5% * maxMemSize The upper limit of the size (in GB) of level file metadata of the TSDB engine. It is of floating type. The default value is 5% of the maximum memory for DolphinDB (set by maxMemSize), and the minimum value is 0.1 (GB). If exceeded, the system replaces the least frequently accessed indices based on access time.
TSDBLevelFileIndexCacheInvalidPercent=0.95 The threshold for caching algorithm for the level file index in the TSDB engine. The default value is 0.95.
allowTSDBLevel3Compaction=false Whether to allow compaction of level 3 files of TSDB storage engine.
  • When set to false (default), level 3 files are not compacted;
  • When set to true, compaction of level 3 files is enabled only for tables with keepDuplicates=FIRST/LAST.
TSDBVectorIndexCacheSize=0 The TSDB engine caches vector indexes to improve the query performance. The cache size can be set using the configuration parameter TSDBVectorIndexCacheSize. It is a non-negative floating-point number specifying the size of the vector index cache in GB. To enable the cache, set TSDBVectorIndexCacheSize to a positive number. The default value is 0, indicating that the cache is disabled.
compactWorkerNumPerVolume=1 The size of worker pool for the level file compaction on each volume. The default value is 1. This parameter is added since version 2.00.11 to control over resource usage, compaction speeds, and load balancing across volumes.

OLAP

Parameter Description
redoLogDir=/log/redoLog The directory of the redo log of OLAP engine. The default value is /log/redoLog. In cluster mode, it is necessary to ensure that different redoLogDir are configured on the data nodes of the same machine.
OLAPCacheEngineSize=0 Alias:chunkCacheEngineMemSize The capacity of cache engine in units of GB. After cache engine is enabled, data is not written to disk until data in cache exceeds 30% of OLAPCacheEngineSize. The default value is 0 indicating the cache engine is not enabled. To enable the cache engine, we must set OLAPCacheEngineSize > 0 and dataSync = 1.

PKEY

Parameter Description
enablePKEYEngine A Boolean value that determines whether to enable the PKEY engine. The default value is true.
PKEYMetaLogDir A string that specifies the path where the PKEY meta log files will be stored. The default value is <ALIAS>/log/PKEYMeta.
PKEYRedoLogDir A string that specifies the path where the PKEY redo log files will be stored. The default value is <ALIAS>/log/PKEYRedo.
PKEYCacheEngineSize A positive number indicating the capacity (in GB) of the PKEY cache engine. The default value is 1. The memory used by the cache engine may reach twice the set value as an extra memory block will be allocated to cache the incoming data while data in the original memory is being flushed to disk. If the flush process is not fast enough, the newly allocated memory may also reach PKEYCacheEngineSize and thus block the writer thread. If the parameter is set too small, data in the cache engine may be flushed to disk too frequently, thus affecting the write performance; If set too high, a large volume of cached data is not flushed to disk until it reaches PKEYCacheEngineSize (or after 10 minutes). If power failure or shutdown occurs in such cases, numerous redo logs are to be replayed when the system is restarting, causing a slow startup.
PKEYBlockCacheSize A positive number indicating the capacity (in GB) of the PKEY block cache. The default value is 1.
PKEYDeleteBitmapUpdateThreshold A positive number indicating the buffer size threshold (in MB) for updating the PKEY delete bitmap. The default value is 100. The process of updating the PKEY delete bitmap occurs asynchronously in batches as a background operation. During the flushing process, the system extracts and temporarily stores the primary key and CID of the data in a buffer. This buffer is used to trigger updates to the delete bitmap. When this buffer reaches the size specified by PKEYDeleteBitmapUpdateThreshold, thedelete bitmap is updated and the buffer is cleared. This parameter should be set appropriately. If set too small, the delete bitmap will be updated too frequently, consuming excessive disk bandwidth. This can negatively impact queries, cache engine flushing, and level file compaction. If set too large, the de-duplication process during queries becomes more resource-intensive, potentially increasing query time. The system recovery process after a reboot may be significantly slower.
PKEYStashedPrimaryKeyBufferSize A positive number indicating the buffer size (in MB) for the PKEY engine. The default value is 1024. Under excessive write load, frequent disk flushing and delayed buffer clearing due to slow delete bitmap updates will result in the buffer to grow continuously. The buffer size may reach twice the set value. This parameter serves as a safeguard against potential OOM issues that could arise from an indefinitely growing staging buffer during periods of high write activity.
PKEYBackgroundWorkerPerVolume The size of worker pool for the PKEY level file compaction and delete bitmap updates on each volume. The default and minimum value is 1.
PKEYCacheFlushWorkerNumPerVolume The size of worker pool for the PKEY cache engine flushing on each volume. The default and minimum value is 1.

IMOLTP

Parameter Description
enableIMOLTPEngine A Boolean value that determines whether to enable the IMOLTP engine. The default value is false.
enableIMOLTPRedo A Boolean value that determines whether to enable redo log mechanism for IMOLTP databases. The default value is true.
IMOLTPRedoFilePath A string that specifies the path where the redo log files will be stored. If a relative path is provided, the redo log files will be located under the <homeDir>/IMOLTP/ directory. The default value is <homeDir>/IMOLTP/im_oltp.redo. Note that the path must exist and be unique.
IMOLTPSyncOnTxnCommit This parameter only takes effect when enableIMOLTPRedo = true. It is a Boolean value that determines whether a transaction should be committed after the data is safely persisted to redo log files on disk. The default value is false, which means the transaction is committed after redo log is written to system buffer instead of disk. In cases of power outages or operating system crashes, data cannot be restored if it is false.
enableIMOLTPCheckpoint A Boolean value that determines whether to enable checkpoint mechanism for IMOLTP databases. The default value is true.
IMOLTPCheckpointFilePath A string that specifies the path where the checkpoint files will be stored. If a relative path is provided, the checkpoint files will be located under the <homeDir>/IMOLTP/ directory. The default value is <homeDir>/IMOLTP/im_oltp.ckp. Note that the path must exist and be unique.
IMOLTPCheckpointThreshold A LONG integer that sets the threshold for the redo logs (in MiB) to trigger a checkpoint. The default value is 100.
IMOLTPCheckpointInterval A LONG integer that sets the interval (in seconds) to trigger a checkpoint. The default value is 60.

Tiered Storage

For more information, see Tiered Storage.

To enable tiered storage, configure the storage path for cold data first.

Parameter Description
coldVolumes= [file://home/mypath/hdd](file://home/mypath/hdd), s3://bucket1/data Configures the storage path of cold data. After the tiered storage is enabled with functions moveHotDataToColdVolume and setRetentionPolicy, cold data will be moved from volumes to coldVolumes.

To store expired data in the cloud, DolphinDB provides the following AWS configurations.

Parameters Description
s3AccessKeyId ID of an Amazon S3 account
s3SecretAccessKey Secret access key of an Amazon S3 account
s3Region Region of an Amazon S3 bucket
s3Endpoint Endpoint to access Amazon S3
Note:

  • When configuring s3Endpoint, you can add a BOOLEAN value after the endpoint to indicate whether to access the endpoint via HTTP protocol (true) or HTTPS protocol (false, default). For example, s3Endpoint=192.168.1.160:980,true indicates accessing 192.168.1.160:980 via HTTP protocol.

  • With s3Endpoint configured, it is not necessary to configure s3Region.

Performance and Resource Monitoring

Parameter Description
perfMonitoring=1 Whether to enable performance monitoring. The default value is false for the standalone mode and true for the cluster mode.

After performance monitoring is enabled, users can get the descriptive information about the SQL queries with functions getCompletedQueries and getRunningQueries. They can also get the performance information about the system with functions getSystemCpuUsage and getSystemLoadAvg.

DolphinDB supports tracking resource usage at the user level on data nodes or compute nodes, including CPU and memory usage. It also supports monitoring operations on DFS tables, including the number of SQL queries on DFS tables, the number of rows read and the amount of data processed. The following parameters can be specified to configure these features as needed:

Parameter Description Node
resourceSamplingInterval=-1 An integer (in seconds) specifying the sampling interval of resource monitoring. The default value is -1, indicating resource tracking is disabled. To enable resource sampling, a positive integer must be set. data node/compute node
resourceSamplingMaxLogSize=1024 A positive integer (in MB) specifying the maximum size threshold of the resource sampling log. The default value is 1024. Log rotation is applied to split the log once it reaches the specified size. The generated file name is prefixed with its generation timestamp. For example, the file 20231101162302_access.log is generated at 2023.11.01T16:23:02. data node/compute node
resourceSamplingLogRetentionTime=-1 An integer (in days) specifying the maximum retention period for the resource sampling logs. The default value -1 means logs never expire. data node/compute node

resourceSamplingLogDir=<HomeDir>/resource

 A string specifying the directory storing the resource sampling logs. The default value is <HomeDir>/resource. data node/compute node

Compatibility Configuration

The following parameters can be specified to unify the format, rules, and other compatibility details in various scenarios.

Parameter Description Release Version
decimalRoundingMode=trunc Specifies the rounding mode for DECIMAL type. The default is trunc, meaning the decimal part is truncated. Set it to round to round the decimal part. It is applicable to the following conversion scenarios:
  • Parsing floating-point numeric strings to DECIMAL type (e.g., loading files with loadText).
  • Converting floating-point numbers to DECIMAL type.
  • Converting DECIMAL values to Integral type.
  • Converting high-precision DECIMAL values to low-precision DECIMAL values.
Note: Since version 2.00.10, the rounding mode for the first case was changed from truncation to rounding. For other scenarios, truncation was used.
 2.00.12
ignoreSpecialCharacterInPartitionId =true A Boolean value specifying whether to ignore ":" and "." in partitioning columns when creating partition directories for value-partitioned tables with partitioning columns of STRING or SYMBOL type. The default value is true, which matches the behavior before version 2.00.11/1.30.23. For example, by default, keys like ".a:bc." and "abc" of the partitioning column will map to the same directory path since ":" and "." are ignored. So data written to partitions ".a:bc." and "abc" will both end up being stored under "abc". If set to false, "." and ":" will be included as part of the path, which means data written to the ".a:bc." and "abc" partitions will be separated into different paths. 2.00.11
ignoreSpecialCharacterInPartitionId =true A Boolean value specifying whether to ignore ":" and "." in partitioning columns when creating partition directories for value-partitioned tables with partitioning columns of STRING or SYMBOL type. The default value is true, which matches the behavior before version 2.00.11/1.30.23. For example, by default, keys like ".a:bc." and "abc" of the partitioning column will map to the same directory path since ":" and "." are ignored. So data written to partitions ".a:bc." and "abc" will both end up being stored under "abc". If set to false, "." and ":" will be included as part of the path, which means data written to the ".a:bc." and "abc" partitions will be separated into different paths. 2.00.11
ignoreSpecialCharacterInPartitionId =true A Boolean value specifying whether to ignore ":" and "." in partitioning columns when creating partition directories for value-partitioned tables with partitioning columns of STRING or SYMBOL type. The default value is true, which matches the behavior before version 2.00.11/1.30.23. For example, by default, keys like ".a:bc." and "abc" of the partitioning column will map to the same directory path since ":" and "." are ignored. So data written to partitions ".a:bc." and "abc" will both end up being stored under "abc". If set to false, "." and ":" will be included as part of the path, which means data written to the ".a:bc." and "abc" partitions will be separated into different paths. 2.00.11
parseDecimalAsFloatingNumber =true Specifieswhether decimal numbers are parsed to DOUBLE or DECIMAL64 type.
  • If set to true (default), decimals are parsed to DOUBLE floating point numbers, which matches the behavior in prior versions.
  • If set to false, decimals are parsedto DECIMAL64 fixed point numbers.
 2.00.10.4
enableNullSafeJoin=false Specifies whether to match NULL values in join columns when performing JOIN operations (including left join, left semi join, right join, equi join and full join).
  • If set to false (default), joining on NULLs is not allowed, which follows the ANSI SQL semantics.
  • If set to true, joining on NULLs is allowed, which matches the behavior in prior versions.
 2.00.10
logicOrIgnoreNull=true Specifies whether function or ignores NULL values. When set to true (default):
  • If the other operand is non-zero, it returns true.
  • If the other operand is zero, it returns false.
  • If the other operand is NULL, it returns NULL.
When set to false, it always returns NULL regardless of the value of the other operand, which matches the behavior in prior versions.		 2.00.9.4
nullAsMinValueForComparison=true Specifieswhether a NULL value is treated as the minimum value in data comparison. The default value is true. If it is set to false, the result of comparison involving NULL value is NULL. For prior versions, all NULL values are treated as the minimum value. 2.00.5
removeSpecialCharInColumnName=false Specifies whether to normalize column names.
  • If set to false (default), column names can contain special characters (except underscores) or start without letters or Chinese characters.
  • If set to true, column names are normalized, which matches the behavior in prior versions.
 1.30.14/2.00.2
appendTupleAsAWhole Specifies how a tuple is appended (append!) or joined (join!) to another tuple. True (default): append or join the tuple as an embedded tuple element. False: append or join each element of the tuple independently.