Configuration Parameters

In this chapter, all the configuration parameters on both server and client side are described thoroughly.

Configuration File on Server Side

On the server side, the actual service of TDengine is provided by an executable taosd whose parameters can be configured in file taos.cfg to meet the requirements of different use cases. The default location of taos.cfg is /etc/taos, but can be changed by using -c parameter on the CLI of taosd. For example, the configuration file can be put under /home/user and used like below

  1. taosd -c /home/user

Parameter -C can be used on the CLI of taosd to show its configuration, like below:

  1. taosd -C

Configuration File on Client Side

TDengine CLI taos is the tool for users to interact with TDengine. It can share same configuration file as taosd or use a separate configuration file. When launching taos, parameter -c can be used to specify the location where its configuration file is. For example taos -c /home/cfg means /home/cfg/taos.cfg will be used. If -c is not used, the default location of the configuration file is /etc/taos. For more details please use taos --help to get.

From version 2.0.10.0 below commands can be used to show the configuration parameters of the client side.

  1. taos -C
  1. taos --dump-config

Configuration Parameters

Configuration - 图1note

taosd needs to be restarted for the parameters changed in the configuration file to take effect.

Connection Parameters

firstEp

AttributeDescription
ApplicableServer and Client
MeaningThe end point of the first dnode in the cluster to be connected to when taosd or taos is started
Default Valuelocalhost:6030

secondEp

AttributeDescription
ApplicableServer and Client
MeaningThe end point of the second dnode to be connected to if the firstEp is not available when taosd or taos is started
Default ValueNone

fqdn

AttributeDescription
ApplicableServer Only
MeaningThe FQDN of the host where taosd will be started. It can be IP address
Default ValueThe first hostname configured for the host
NoteIt should be within 96 bytes

serverPort

AttributeDescription
ApplicableServer Only
MeaningThe port for external access after taosd is started
Default Value6030
NoteREST service is provided by taosd before 2.4.0.0 but by taosAdapter after 2.4.0.0, the default port of REST service is 6041
Configuration - 图2note

TDengine uses 13 continuous ports, both TCP and UDP, starting with the port specified by serverPort. You should ensure, in your firewall rules, that these ports are kept open. Below table describes the ports used by TDengine in details.

ProtocolDefault PortDescriptionHow to configure
TCP6030Communication between client and serverserverPort
TCP6035Communication among server nodes in clusterserverPort+5
TCP6040Data syncup among server nodes in clusterserverPort+10
TCP6041REST connection between client and serverPrior to 2.4.0.0: serverPort+11; After 2.4.0.0 refer to taosAdapter
TCP6042Service Port of ArbitratorThe parameter of Arbitrator
TCP6043Service Port of TaosKeeperThe parameter of TaosKeeper
TCP6044Data access port for StatsDrefer to taosAdapter
UDP6045Data access for statsdrefer to taosAdapter
TCP6060Port of Monitoring Service in Enterprise version
UDP6030-6034Communication between client and serverserverPort
UDP6035-6039Communication among server nodes in clusterserverPort

maxShellConns

AttributeDescription
ApplicableServer Only
MeaningThe maximum number of connections a dnode can accept
Value Range10-50000000
Default Value5000

maxConnections

AttributeDescription
ApplicableServer Only
MeaningThe maximum number of connections allowed by a database
Value Range1-100000
Default Value5000
NoteThe maximum number of worker threads on the client side is maxConnections/100

rpcForceTcp

AttributeDescription
ApplicableServer and Client
MeaningTCP is used by force
Value Range0: disabled 1: enabled
Default Value0
NoteIt’s suggested to configure to enable if network is not good enough

Monitoring Parameters

monitor

AttributeDescription
ApplicableServer Only
MeaningThe switch for monitoring inside server. The workload of the hosts, including CPU, memory, disk, network, TTP requests, are collected and stored in a system builtin database LOG
Value Range0: monitoring disabled, 1: monitoring enabled
Default Value1

monitorInterval

AttributeDescription
ApplicableServer Only
MeaningThe interval of collecting system workload
Unitsecond
Value Range1-600
Default Value30

telemetryReporting

AttributeDescription
ApplicableServer Only
MeaningSwitch for allowing TDengine to collect and report service usage information
Value Range0: Not allowed; 1: Allowed
Default Value1

Query Parameters

queryBufferSize

AttributeDescription
ApplicableServer Only
MeaningThe total memory size reserved for all queries
UnitMB
Default ValueNone
NoteIt can be estimated by “maximum number of concurrent queries” “number of tables” 170

ratioOfQueryCores

AttributeDescription
ApplicableServer Only
MeaningMaximum number of query threads
Default Value1
Notevalue range: float number between [0, 2] 0: only 1 query thread; >0: the times of the number of cores

maxNumOfDistinctRes

AttributeDescription
ApplicableServer Only
MeaningThe maximum number of distinct rows returned
Value Range[100,000 - 100,000,000]
Default Value100,000
NoteAfter version 2.3.0.0

Locale Parameters

timezone

AttributeDescription
ApplicableServer and Client
MeaningTimeZone
Default ValueTimeZone configured in the host
Configuration - 图3info

To handle the data insertion and data query from multiple timezones, Unix Timestamp is used and stored in TDengine. The timestamp generated from any timezones at same time is same in Unix timestamp. To make sure the time on client side can be converted to Unix timestamp correctly, the timezone must be set properly.

On Linux system, TDengine clients automatically obtain timezone from the host. Alternatively, the timezone can be configured explicitly in configuration file taos.cfg like below.

  1. timezone UTC-7
  2. timezone GMT-8
  3. timezone Asia/Shanghai

The above examples are all proper configuration for the timezone of UTC+8. On Windows system, however, timezone Asia/Shanghai is not supported, it must be set as timezone UTC-8.

The setting for timezone impacts strings that are not in Unix timestamp format and keywords or functions related to date/time. For example:

  1. SELECT count(*) FROM table_name WHERE TS<'2019-04-11 12:01:08';

If the timezone is UTC+8, the above SQL statement is equal to:

  1. SELECT count(*) FROM table_name WHERE TS<1554955268000;

If the timezone is UTC, it’s equal to

  1. SELECT count(*) FROM table_name WHERE TS<1554984068000;

To avoid the problems of using time strings, Unix timestamp can be used directly. Furthermore, time strings with timezone can be used in SQL statements. For example “2013-04-12T15:52:01.123+08:00” in RFC3339 format or “2013-04-12T15:52:01.123+0800” in ISO-8601 format are not influenced by timezone setting when converted to Unix timestamp.

locale

AttributeDescription
ApplicableServer and Client
MeaningLocation code
Default ValueLocale configured in host
Configuration - 图4info

A specific type “nchar” is provided in TDengine to store non-ASCII characters such as Chinese, Japanese, and Korean. The characters to be stored in nchar type are firstly encoded in UCS4-LE before sending to server side. To store non-ASCII characters correctly, the encoding format of the client side needs to be set properly.

The characters input on the client side are encoded using the default system encoding, which is UTF-8 on Linux, or GB18030 or GBK on some systems in Chinese, POSIX in docker, CP936 on Windows in Chinese. The encoding of the operating system in use must be set correctly so that the characters in nchar type can be converted to UCS4-LE.

The locale definition standard on Linux is: <Language>_<Region>.<charset>, for example, in “zh_CN.UTF-8”, “zh” means Chinese, “CN” means China mainland, “UTF-8” means charset. On Linux and Mac OSX, the charset can be set by locale in the system. On Windows system another configuration parameter charset must be used to configure charset because the locale used on Windows is not POSIX standard. Of course, charset can also be used on Linux to specify the charset.

charset

AttributeDescription
ApplicableServer and Client
MeaningCharacter
Default Valuecharset set in the system
Configuration - 图5info

On Linux, if charset is not set in taos.cfg, when taos is started, the charset is obtained from system locale. If obtaining charset from system locale fails, taos would fail to start. So on Linux system, if system locale is set properly, it’s not necessary to set charset in taos.cfg. For example:

  1. locale zh_CN.UTF-8

On a Linux system, if the charset contained in locale is not consistent with that set by charset, the later setting in the configuration file takes precedence.

  1. locale zh_CN.UTF-8
  2. charset GBK
  1. charset GBK
  2. locale zh_CN.UTF-8

On Windows system, it’s not possible to obtain charset from system locale. If it’s not set in configuration file taos.cfg, it would be default to CP936, same as set as below in taos.cfg. For example

  1. charset CP936

Storage Parameters

dataDir

AttributeDescription
ApplicableServer Only
MeaningAll data files are stored in this directory
Default Value/var/lib/taos

cache

AttributeDescription
ApplicableServer Only
MeaningThe size of each memory block
UnitMB
Default Value16

blocks

AttributeDescription
ApplicableServer Only
MeaningThe number of memory blocks of size cache used by each vnode
Default Value6

days

AttributeDescription
ApplicableServer Only
MeaningThe time range of the data stored in single data file
Unitday
Default Value10

keep

AttributeDescription
ApplicableServer Only
MeaningThe number of days for data to be kept
Unitday
Default Value3650

minRows

AttributeDescription
ApplicableServer Only
Meaningminimum number of rows in single data file
Default Value100

maxRows

AttributeDescription
ApplicableServer Only
Meaningmaximum number of rows in single data file
Default Value4096

walLevel

AttributeDescription
ApplicableServer Only
MeaningWAL level
Value Range0: wal disabled
1: wal enabled without fsync
2: wal enabled with fsync
Default Value1

fsync

AttributeDescription
ApplicableServer Only
MeaningThe waiting time for invoking fsync when walLevel is 2
Unitmillisecond
Value Range0: no waiting time, fsync is performed immediately once WAL is written;
maximum value is 180000, i.e. 3 minutes
Default Value3000

update

AttributeDescription
ApplicableServer Only
MeaningIf it’s allowed to update existing data
Value Range0: not allowed
1: a row can only be updated as a whole
2: a part of columns can be updated
Default Value0
NoteNot available from version 2.0.8.0

cacheLast

AttributeDescription
ApplicableServer Only
MeaningWhether to cache the latest rows of each sub table in memory
Value Range0: not cached
1: the last row of each sub table is cached
2: the last non-null value of each column is cached
3: identical to both 1 and 2 are set
Default Value0

minimalTmpDirGB

AttributeDescription
ApplicableServer and Client
MeaningWhen the available disk space in tmpDir is below this threshold, writing to tmpDir is suspended
UnitGB
Default Value1.0

minimalDataDirGB

AttributeDescription
ApplicableServer Only
Meaninghen the available disk space in dataDir is below this threshold, writing to dataDir is suspended
UnitGB
Default Value2.0

vnodeBak

AttributeDescription
ApplicableServer Only
MeaningWhether to backup the corresponding vnode directory when a vnode is deleted
Value Range0: not backed up, 1: backup
Default Value1

Cluster Parameters

numOfMnodes

AttributeDescription
ApplicableServer Only
MeaningThe number of management nodes
Default Value3

replica

AttributeDescription
ApplicableServer Only
MeaningThe number of replications
Value Range1-3
Default Value1

quorum

AttributeDescription
ApplicableServer Only
MeaningThe number of required confirmations for data replication in case of multiple replications
Value Range1,2
Default Value1

role

AttributeDescription
ApplicableServer Only
MeaningThe role of the dnode
Value Range0: both mnode and vnode
1: mnode only
2: dnode only
Default Value0

balance

AttributeDescription
ApplicableServer Only
MeaningAutomatic load balancing
Value Range0: disabled, 1: enabled
Default Value1

balanceInterval

AttributeDescription
ApplicableServer Only
MeaningThe interval for checking load balance by mnode
Unitsecond
Value Range1-30000
Default Value300

arbitrator

AttributeDescription
ApplicableServer Only
MeaningEnd point of arbitrator, format is same as firstEp
Default ValueNone

Time Parameters

precision

AttributeDescription
ApplicableServer only
MeaningTime precision used for each database
Value Rangems: millisecond; us: microsecond ; ns: nanosecond
Default Valuems

rpcTimer

AttributeDescription
ApplicableServer and Client
Meaningrpc retry interval
Unitmilliseconds
Value Range100-3000
Default Value300

rpcMaxTime

AttributeDescription
ApplicableServer and Client
Meaningmaximum wait time for rpc response
Unitsecond
Value Range100-7200
Default Value600

statusInterval

AttributeDescription
ApplicableServer Only
Meaningthe interval of dnode reporting status to mnode
Unitsecond
Value Range1-10
Default Value1

shellActivityTimer

AttributeDescription
ApplicableServer and Client
MeaningThe interval for taos shell to send heartbeat to mnode
Unitsecond
Value Range1-120
Default Value3

tableMetaKeepTimer

AttributeDescription
ApplicableServer Only
MeaningThe expiration time for metadata in cache, once it’s reached the client would refresh the metadata
Unitsecond
Value Range1-8640000
Default Value7200

maxTmrCtrl

AttributeDescription
ApplicableServer and Client
MeaningMaximum number of timers
UnitNone
Value Range8-2048
Default Value512

offlineThreshold

AttributeDescription
ApplicableServer Only
MeaningThe expiration time for dnode online status, once it’s reached before receiving status from a node, the dnode becomes offline
Unitsecond
Value Range5-7200000
Default Value86400*10 (i.e. 10 days)

Performance Optimization Parameters

numOfThreadsPerCore

AttributeDescription
ApplicableServer and Client
MeaningThe number of consumer threads per CPU core
Default Value1.0

ratioOfQueryThreads

AttributeDescription
ApplicableServer Only
MeaningMaximum number of query threads
Value Range0: Only one query thread
1: Same as number of CPU cores
2: two times of CPU cores
Default Value1
NoteThis value can be a float number, 0.5 means half of the CPU cores

maxVgroupsPerDb

AttributeDescription
ApplicableServer Only
MeaningMaximum number of vnodes for each DB
Value Range0-8192
Default Value

maxTablesPerVnode

AttributeDescription
ApplicableServer Only
MeaningMaximum number of tables in each vnode
Default Value1000000

minTablesPerVnode

AttributeDescription
ApplicableServer Only
MeaningMinimum number of tables in each vnode
Default Value1000

tableIncStepPerVnode

AttributeDescription
ApplicableServer Only
MeaningWhen minTablesPerVnode is reached, the number of tables are allocated for a vnode each time
Default Value1000

maxNumOfOrderedRes

AttributeDescription
ApplicableServer and Client
MeaningMaximum number of rows ordered for a STable
Default Value100,000

mnodeEqualVnodeNum

AttributeDescription
ApplicableServer Only
MeaningThe number of vnodes whose system resources consumption are considered as equal to single mnode
Default Value4

numOfCommitThreads

AttributeDescription
ApplicableServer Only
MeaningMaximum of threads for committing to disk
Default Value

Compression Parameters

comp

AttributeDescription
ApplicableServer Only
MeaningWhether data is compressed
Value Range0: uncompressed, 1: One phase compression, 2: Two phase compression
Default Value2

tsdbMetaCompactRatio

AttributeDescription
MeaningThe threshold for percentage of redundant in meta file to trigger compression for meta file
Value Range0: no compression forever, [1-100]: The threshold percentage
Default Value0

compressMsgSize

AttributeDescription
ApplicableServer Only
MeaningThe threshold for message size to compress the message..
Unitbytes
Value Range0: already compress; >0: compress when message exceeds it; -1: always uncompress
Default Value-1

compressColData

AttributeDescription
ApplicableServer Only
MeaningThe threshold for size of column data to trigger compression for the query result
Unitbytes
Value Range0: always compress; >0: only compress when the size of any column data exceeds the threshold; -1: always uncompress
Default Value-1
Noteavailable from version 2.3.0.0

lossyColumns

AttributeDescription
ApplicableServer Only
MeaningThe floating number types for lossy compression
Value Range“”: lossy compression is disabled
float: only for float
double: only for double
float | double: for both float and double
Default Value“” , i.e. disabled

fPrecision

AttributeDescription
ApplicableServer Only
MeaningCompression precision for float type
Value Range0.1 ~ 0.00000001
Default Value0.00000001
NoteThe fractional part lower than this value will be discarded

dPrecision

AttributeDescription
ApplicableServer Only
MeaningCompression precision for double type
Value Range0.1 ~ 0.0000000000000001
Default Value0.0000000000000001
NoteThe fractional part lower than this value will be discarded

Continuous Query Parameters

stream

AttributeDescription
ApplicableServer Only
MeaningWhether to enable continuous query
Value Range0: disabled
1: enabled
Default Value1

minSlidingTime

AttributeDescription
ApplicableServer Only
MeaningMinimum sliding time of time window
Unitmillisecond or microsecond , depending on time precision
Value Range10-1000000
Default Value10

minIntervalTime

AttributeDescription
ApplicableServer Only
MeaningMinimum size of time window
Unitmillisecond
Value Range1-1000000
Default Value10

maxStreamCompDelay

AttributeDescription
ApplicableServer Only
MeaningMaximum delay before starting a continuous query
Unitmillisecond
Value Range10-1000000000
Default Value20000

maxFirstStreamCompDelay

AttributeDescription
ApplicableServer Only
MeaningMaximum delay time before starting a continuous query the first time
Unitmillisecond
Value Range10-1000000000
Default Value10000

retryStreamCompDelay

AttributeDescription
ApplicableServer Only
MeaningDelay time before retrying a continuous query
Unitmillisecond
Value Range10-1000000000
Default Value10

streamCompDelayRatio

AttributeDescription
ApplicableServer Only
MeaningThe delay ratio, with time window size as the base, for continuous query
Value Range0.1-0.9
Default Value0.1
Configuration - 图6info

To prevent system resource from being exhausted by multiple concurrent streams, a random delay is applied on each stream automatically. maxFirstStreamCompDelay is the maximum delay time before a continuous query is started the first time. streamCompDelayRatio is the ratio for calculating delay time, with the size of the time window as base. maxStreamCompDelay is the maximum delay time. The actual delay time is a random time not bigger than maxStreamCompDelay. If a continuous query fails, retryStreamComDelay is the delay time before retrying it, also not bigger than maxStreamCompDelay.

HTTP Parameters

Configuration - 图7note

HTTP service was provided by taosd prior to version 2.4.0.0 and is provided by taosAdapter after version 2.4.0.0. The parameters described in this section are only application in versions prior to 2.4.0.0. If you are using any version from 2.4.0.0, please refer to taosAdapter.

http

AttributeDescription
ApplicableServer Only
MeaningWhether to enable http service
Value Range0: disabled, 1: enabled
Default Value1

httpEnableRecordSql

AttributeDescription
ApplicableServer Only
MeaningWhether to record the SQL invocation through REST interface
Default Value0: false; 1: true
NoteThe resulting files, i.e. httpnote.0/httpnote.1, are located under logDir

httpMaxThreads

AttributeDescription
ApplicableServer Only
MeaningThe number of threads for RESTFul interface.
Default Value2

restfulRowLimit

AttributeDescription
ApplicableServer Only
MeaningMaximum number of rows returned each time by REST interface.
Default Value10240
NoteMaximum value is 10,000,000

httpDBNameMandatory

AttributeDescription
ApplicableServer Only
MeaningWhether database name is required in URL
Value Range0:not required, 1: required
Default Value0
NoteFrom version 2.3.0.0

Log Parameters

logDir

AttributeDescription
ApplicableServer and Client
MeaningThe directory for writing log files
Default Value/var/log/taos

minimalLogDirGB

AttributeDescription
ApplicableServer and Client
MeaningWhen the available disk space in logDir is below this threshold, writing to log files is suspended
UnitGB
Default Value1.0

numOfLogLines

AttributeDescription
ApplicableServer and Client
MeaningMaximum number of lines in single log file
Default Value10,000,000

asyncLog

AttributeDescription
ApplicableServer and Client
MeaningThe mode of writing log file
Value Range0: sync way; 1: async way
Default Value1

logKeepDays

AttributeDescription
ApplicableServer and Client
MeaningThe number of days for log files to be kept
Unitday
Default Value0
NoteWhen it’s bigger than 0, the log file would be renamed to “taosdlog.xxx” in which “xxx” is the timestamp when the file is changed last time

debugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level
Value Range131: INFO/WARNING/ERROR; 135: plus DEBUG; 143: plus TRACE
Default Value131 or 135, depending on the module

mDebugFlag

AttributeDescription
ApplicableServer Only
MeaningLog level of mnode
Value Rangesame as debugFlag
Default Value135

dDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of dnode
Value Rangesame as debugFlag
Default Value135

sDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of sync module
Value Rangesame as debugFlag
Default Value135

wDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of WAL module
Value Rangesame as debugFlag
Default Value135

sdbDebugFlag

AttributeDescription
ApplicableServer and Client
MeaninglogLevel of sdb module
Value Rangesame as debugFlag
Default Value135

rpcDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of rpc module
Value RangeSame as debugFlag
Default Value

tmrDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of timer module
Value RangeSame as debugFlag
Default Value

cDebugFlag

AttributeDescription
ApplicableClient Only
MeaningLog level of Client
Value RangeSame as debugFlag
Default Value

jniDebugFlag

AttributeDescription
ApplicableClient Only
MeaningLog level of jni module
Value RangeSame as debugFlag
Default Value

odbcDebugFlag

AttributeDescription
ApplicableClient Only
MeaningLog level of odbc module
Value RangeSame as debugFlag
Default Value

uDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of common module
Value RangeSame as debugFlag
Default Value

httpDebugFlag

AttributeDescription
ApplicableServer Only
MeaningLog level of http module (prior to 2.4.0.0)
Value RangeSame as debugFlag
Default Value

mqttDebugFlag

AttributeDescription
ApplicableServer Only
MeaningLog level of mqtt module
Value RangeSame as debugFlag
Default Value

monitorDebugFlag

AttributeDescription
ApplicableServer Only
MeaningLog level of monitoring module
Value RangeSame as debugFlag
Default Value

qDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of query module
Value RangeSame as debugFlag
Default Value

vDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of vnode
Value RangeSame as debugFlag
Default Value

tsdbDebugFlag

AttributeDescription
ApplicableServer Only
MeaningLog level of TSDB module
Value RangeSame as debugFlag
Default Value

cqDebugFlag

AttributeDescription
ApplicableServer and Client
MeaningLog level of continuous query module
Value RangeSame as debugFlag
Default Value

Client Only

maxSQLLength

AttributeDescription
ApplicableClient Only
MeaningMaximum length of single SQL statement
Unitbytes
Value Range65480-1048576
Default Value1048576

tscEnableRecordSql

AttributeDescription
MeaningWhether to record SQL statements in file
Value Range0: false, 1: true
Default Value0
NoteThe generated files are named as “tscnote-xxxx.0/tscnote-xxx.1” in which “xxxx” is the pid of the client, and located at same place as client log

maxBinaryDisplayWidth

AttributeDescription
MeaningMaximum display width of binary and nchar in taos shell. Anything beyond this limit would be hidden
Value Range5 -
Default Value30
Configuration - 图8info

If the length of value exceeds maxBinaryDisplayWidth, then the actual display width is max(column name, maxBinaryDisplayLength); otherwise the actual display width is max(length of column name, length of column value). This parameter can also be changed dynamically using set max_binary_display_width <nn\> in TDengine CLI taos.

maxWildCardsLength

AttributeDescription
MeaningThe maximum length for wildcard string used with LIKE
Unitbytes
Value Range0-16384
Default Value100
NoteFrom version 2.1.6.1

clientMerge

AttributeDescription
MeaningWhether to filter out duplicate data on client side
Value Range0: false; 1: true
Default Value0
NoteFrom version 2.3.0.0

maxRegexStringLen

AttributeDescription
MeaningMaximum length of regular expression
Value Range[128, 16384]
Default Value128
NoteFrom version 2.3.0.0

Other Parameters

enableCoreFile

AttributeDescription
ApplicableServer and Client
MeaningWhether to generate core file when server crashes
Value Range0: false, 1: true
Default Value1
NoteThe core file is generated under root directory systemctl start taosd is used to start, or under the working directory if taosd is started directly on Linux Shell.