客户端驱动参考手册

TDengine 客户端驱动提供了应用编程所需要的全部 API，并且在整个集群的分布式计算中扮演着重要角色。客户端驱动的行为除了 API 及其具体参数以外，也可以通过配置文件的形式进行全局控制，本节列举 TDengine 客户端可以使用的配置参数。

配置参数

连接相关

firstEp

• 说明：启动时，主动连接的集群中首个 dnode 的 endpoint
• 默认值：hostname:6030，若无法获取该服务器的 hostname，则赋值为 localhost
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

secondEp

• 说明：启动时，如果 firstEp 连接不上，尝试连接集群中第二个 dnode 的 endpoint
• 默认值：无
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

serverPort

• 说明：taosd 监听的端口
• 默认值：6030
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

compressMsgSize

• 说明：是否对 RPC 消息进行压缩
• 类型：整数；-1：所有消息都不压缩；0：所有消息都压缩；N (N>0)：只有大于 N 个字节的消息才压缩
• 单位：bytes
• 默认值：-1
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

shellActivityTimer

• 说明：客户端向 mnode 发送心跳的时长
• 类型：整数
• 单位：秒
• 默认值：3
• 最小值：1
• 最大值：120
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

numOfRpcSessions

• 说明：RPC 支持的最大连接数
• 类型：整数
• 默认值：30000
• 最小值：100
• 最大值：100000
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

numOfRpcThreads

• 说明：RPC 收发数据线程数目
• 类型：整数
• 默认值：CPU 核数的一半
• 最小值：1
• 最大值：50
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

numOfTaskQueueThreads

• 说明：客户端处理 RPC 消息的线程数
• 类型：整数
• 默认值：CPU 核数的一半
• 最小值：4
• 最大值：16
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

timeToGetAvailableConn

• 说明：获得可用连接的最长等待时间
• 类型：整数
• 单位：毫秒
• 默认值：500000
• 最小值：10
• 最大值：50000000
• 动态修改：不支持
• 支持版本：3.3.4.*之后取消

useAdapter

• 说明：是否使用 taosadapter，影响 CSV 文件导入 内部参数
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

shareConnLimit

• 说明：一个链接可以共享的查询数目 内部参数
• 最小值：1
• 最大值：256
• 默认值：10
• 动态修改：不支持
• 支持版本：从 v3.3.4.0 版本开始引入

readTimeout

• 说明：最小超时时间 内部参数
• 单位：秒
• 最小值：64
• 最大值：604800
• 默认值：900
• 动态修改：不支持
• 支持版本：从 v3.3.4.0 版本开始引入

maxRetryWaitTime

• 说明：重连最大超时时间，从重试时候开始计算。
• 类型：整数
• 单位：毫秒
• 默认值：20000
• 最小值：3000
• 最大值：86400000
• 动态修改：支持通过 SQL 修改，重启后生效。
• 支持版本：从 v3.3.4.0 版本开始引入

maxRetryTimes

• 说明：查询调度任务的基础最大重试次数。根据任务类型，实际最大重试次数取该值与副本系数的乘积、根据 maxRetryWaitTime 或节点数计算结果中的较大值。
• 类型：整数
• 默认值：12
• 最小值：1
• 最大值：1000
• 动态修改：支持通过 SQL 修改，重启后生效。
• 支持版本：从 v3.3.6.64 版本开始引入

retryOnOverloadBaseInterval

• 说明：服务端过载时（如 Sync 协商窗口满），客户端重试的初始间隔。重试采用指数退避策略，每次间隔翻倍。
• 类型：整数
• 单位：毫秒
• 默认值：1000
• 最小值：100
• 最大值：60000
• 动态修改：不支持动态修改，修改后需要重启客户端生效。
• 支持版本：从 v3.4.1.15 版本开始引入

retryOnOverloadTimeout

• 说明：服务端过载重试的最大总时长。从首次重试开始计算，超过此时长后不再重试，返回错误码给应用。
• 类型：整数
• 单位：毫秒
• 默认值：60000
• 最小值：1000
• 最大值：3600000
• 动态修改：不支持动态修改，修改后需要重启客户端生效。
• 支持版本：从 v3.4.1.15 版本开始引入

查询相关

countAlwaysReturnValue

• 说明：count/hyperloglog 函数在输入数据为空或者 NULL 的情况下是否返回值；该参数设置为 1 时，如果查询中含有 INTERVAL 子句或者该查询使用了 TSMA 时，且相应的组或窗口内数据为空或者 NULL，对应的组或窗口将不返回查询结果；注意此参数客户端和服务端值应保持一致
• 类型：整数；0：返回空行，1：返回
• 最小值：0
• 最大值：1
• 默认值：1
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

keepColumnName

• 说明：Last、First、LastRow 函数查询且未指定别名时，自动设置别名为列名（不含函数名），因此 order by 子句如果引用了该列名将自动引用该列对应的函数
• 类型：整数；1：表示自动设置别名为列名 (不包含函数名)，0：表示不自动设置别名
• 最小值：0
• 最大值：1
• 默认值：0
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

multiResultFunctionStarReturnTags

• 说明：查询超级表时，last(*)/last_row(*)/first(*) 是否返回标签列；查询普通表、子表时，不受该参数影响；
• 类型：整数；0：不返回标签列，1：返回标签列；该参数设置为 0 时，last(*)/last_row(*)/first(*) 只返回超级表的普通列；为 1 时，返回超级表的普通列和标签列
• 最小值：0
• 最大值：1
• 默认值：0
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.3.3.0 版本开始引入

metaCacheMaxSize

• 说明：指定单个客户端元数据缓存大小的最大值
• 类型：整数；0：不返回标签列，1：返回标签列；该参数设置为 0 时，last(*)/last_row(*)/first(*) 只返回超级表的普通列；为 1 时，返回超级表的普通列和标签列
• 单位：MB
• 最小值：-1
• 最大值：2147483647
• 默认值：-1 表示无限制
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

maxTsmaCalcDelay

• 说明：查询时客户端可允许的 tsma 计算延迟，若 tsma 的计算延迟大于配置值，则该 TSMA 将不会被使用
• 类型：整数
• 单位：秒
• 最小值：600
• 最大值：86400
• 默认值：600
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

tsmaDataDeleteMark

• 说明：TSMA 计算的历史数据中间结果保存时间
• 类型：整数
• 单位：毫秒
• 最小值：3600000
• 最大值：9223372036854775807
• 默认值：86400000
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryPolicy

• 说明：查询语句的执行策略
• 类型：整数；1：只使用 vnode，不使用 qnode；2：没有扫描算子的子任务在 qnode 执行，带扫描算子的子任务在 vnode 执行；3：vnode 只运行扫描算子，其余算子均在 qnode 执行；
• 单位：秒
• 默认值：1
• 动态修改：仅在企业版支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryTableNotExistAsEmpty

• 说明：查询表不存在时是否返回空结果集
• 类型：布尔；false：返回错误；true：返回空结果集
• 默认值：false
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

querySmaOptimize

• 说明：querSmaOptimize，永远从原始数据进行查询
• 类型：整数；1：表示使用 sma index，对符合的语句，直接从预计算的结果进行查询
• 默认值：false
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryPlannerTrace

• 说明：查询计划是否输出详细日志 内部参数
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryNodeChunkSize

• 说明：查询计划的块大小 内部参数
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryUseNodeAllocator

• 说明：查询计划的分配方法 内部参数
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

queryMaxConcurrentTables

• 说明：查询计划的并发数目 内部参数
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

enableQueryHb

• 说明：是否发送查询心跳消息 内部参数
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

minSlidingTime

• 说明：sliding 的最小允许值 内部参数
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

minIntervalTime

• 说明：interval 的最小允许值 内部参数
• 动态修改：不支持
• 支持版本：从 v3.0.0.0 版本开始引入

compareAsStrInGreatest

• 说明：用于决定 greatest、least 函数的参数既有数值类型又有字符串类型时，比较类型的转换规则。
• 类型：整数；1：统一转为字符串比较，0：统一转为数值类型比较。
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.3.6.0 版本开始引入

写入相关

smlChildTableName

• 说明：schemaless 自定义的子表名的 key
• 默认值：无
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

smlAutoChildTableNameDelimiter

• 说明：schemaless tag 之间的连接符，连起来作为子表名
• 默认值：无
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

smlTagName

• 说明：schemaless tag 为空时默认的 tag 名字
• 默认值："_tag_null"
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

smlTsDefaultName

• 说明：schemaless 自动建表的时间列名字通过该配置设置
• 默认值："_ts"
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

smlDot2Underline

• 说明：schemaless 把超级表名中的 dot 转成下划线
• 默认值：true
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

maxInsertBatchRows

• 说明：一批写入的最大条数
• 默认值：1000000
• 最小值：1
• 最大值：2147483647
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.0.0.0 版本开始引入

maxSQLLength

• 说明：单条 SQL 语句最大长度
• 默认值：1048576
• 最小值：1048576
• 最大值：67108864
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.3.6.34 版本开始引入

区域相关

timezone

• 说明：时区
• 默认值：从系统中动态获取当前的时区设置
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

locale

• 说明：系统区位信息及编码格式
• 默认值：从系统中获取
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

charset

• 说明：字符集编码
• 默认值：从系统中获取
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

存储相关

tempDir

• 说明：指定所有运行过程中的临时文件生成的目录
• 默认值：Linux 平台默认值为 /tmp
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

minimalTmpDirGB

• 说明：tempDir 所指定的临时文件目录所需要保留的最小空间
• 类型：浮点数
• 单位：GB
• 默认值：1
• 最小值：0.001f
• 最大值：10000000
• 动态修改：不支持
• 支持版本：从 v3.1.0.0 版本开始引入

日志相关

logDir

• 说明：日志文件目录，运行日志将写入该目录
• 类型：字符串
• 默认值：/var/log/taos
• 动态修改：不支持
• 支持版本：从 v3.1.0.0 版本开始引入

minimalLogDirGB

• 说明：日志文件夹所在磁盘可用空间大小小于该值时，停止写日志
• 类型：浮点数
• 单位：GB
• 默认值：1
• 最小值：0.001f
• 最大值：10000000
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

numOfLogLines

• 说明：单个日志文件允许的最大行数
• 类型：整数
• 默认值：10,000,000
• 最小值：1000
• 最大值：2000000000
• 动态修改：仅在企业版支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

asyncLog

• 说明：日志写入模式
• 类型：整数；0：同步，1：异步
• 默认值：1
• 最小值：0
• 最大值：1
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

logKeepDays

• 说明：日志文件的最长保存时间，等于 0 意味着只有两个日志文件相互切换保存日志，超过两个文件保存数量的日志会被删除；当设置为大于 0 的值时，当日志文件大小达到设置的上限时会被重命名为 taosdlog.yyy，其中 yyy 为日志文件最后修改的时间戳，并滚动产生新的日志文件，日志文件创建时间超过 logKeepDays 则删除；考虑到 2.0 版本的用户习惯，自 TDengine 3.3.6.6 版本开始，当设置为小于 0 的值时，除日志文件创建时间超过 -logKeepDays 删除外，其他行为与取值大于 0 时一致（3.0.0.0-3.3.6.5 之间的版本，不建议设置为小于 0 的值）。
• 类型：整数；0
• 单位：天
• 默认值：0
• 最小值：-365000
• 最大值：365000
• 动态修改：仅在企业版支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

debugFlag

• 说明：运行日志开关，该参数的设置会影响所有模块的开关，后设置的参数起效
• 类型：整数
• 取值范围：131（输出错误和警告日志），135（输出错误、警告和调试日志），143（输出错误、警告、调试和跟踪日志）
• 默认值：131 或 135（取决于不同模块）
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

tmrDebugFlag

• 说明：定时器模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

uDebugFlag

• 说明：共用功能模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

rpcDebugFlag

• 说明：rpc 模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

jniDebugFlag

• 说明：jni 模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

qDebugFlag

• 说明：query 模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

cDebugFlag

• 说明：客户端模块的日志开关
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

simDebugFlag

• 说明：测试工具的日志开关 内部参数
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

tqClientDebugFlag

• 说明：测试工具的日志开关 内部参数
• 类型：整数
• 取值范围：同上
• 默认值：131
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

调试相关

crashReporting

• 说明：是否上传 crash 到 telemetry
• 类型：整数；0：不上传，1：上传；
• 默认值：1
• 最小值：0
• 最大值：1
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

enableCoreFile

• 说明：crash 时是否生成 core 文件
• 类型：整数；0：不生成，1：生成；
• 默认值：1
• 最小值：0
• 最大值：1
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.1.0.0 版本开始引入

assert

• 说明：断言控制开关
• 类型：整数；0:关闭，1：开启
• 默认值：0
• 最小值：0
• 最大值：1
• 动态修改：不支持
• 支持版本：从 v3.1.0.0 版本开始引入

configDir

• 说明：配置文件所在目录
• 类型：字符串
• 动态修改：不支持
• 支持版本：从 v3.1.0.0 版本开始引入

scriptDir

• 说明：测试工具的脚本目录 内部参数
• 类型：字符串
• 动态修改：不支持
• 支持版本：从 v3.3.3.0 版本开始引入

randErrorChance

• 说明：用于随机失败测试 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.3.0 版本开始引入

randErrorDivisor

• 说明：用于随机失败测试 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.3.0 版本开始引入

randErrorScope

• 说明：用于随机失败测试 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.3.0 版本开始引入

safetyCheckLevel

• 说明：用于随机失败测试 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.3.0 版本开始引入

simdEnable

• 说明：用于测试 SIMD 加速 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.4.3 版本开始引入

AVX512Enable

• 说明：用于测试 AVX512 加速 内部参数
• 动态修改：不支持
• 支持版本：从 v3.3.4.3 版本开始引入

bypassFlag

• 说明：用于短路测试 内部参数
• 类型：整数；
• 取值范围：0：正常写入，1：写入消息在 taos 客户端发送 RPC 消息前返回，2：写入消息在 taosd 服务端收到 RPC 消息后返回，4：写入消息在 taosd 服务端写入内存缓存前返回，8：写入消息在 taosd 服务端数据落盘前返回
• 默认值：0
• 动态修改：支持通过 SQL 修改，立即生效
• 支持版本：从 v3.3.4.5 版本开始引入

SHELL 相关

enableScience

• 说明：是否开启科学计数法显示浮点数
• 类型：整数；0：不开始，1：开启；
• 默认值：1
• 最小值：0
• 最大值：1
• 动态修改：不支持
• 支持版本：从 v3.1.0.0 版本开始引入

API

请参考连接器