What the taosc client driver does
taosc is the core client driver for TDengine, standing for TDengine Standard Connector. It provides applications with all the API interfaces needed to access the TDengine server.
Whether your application is written in Java, Python, Go, or another language, it communicates with TDengine through the taosc driver. Understanding its configuration is the first step to getting reliable performance from a TDengine deployment.
The taosc driver supports two connection modes: Native connection and WebSocket connection. Native connections talk directly to the taosd service for higher performance but require installation of the native client. WebSocket connections route through taosAdapter for better compatibility and easier cross-language invocation. Developers can choose the mode that fits their deployment scenario.
Connection configuration parameters
Connection parameters are the most important part of taosc driver configuration, directly affecting the quality of communication between client and server.
The firstEp and secondEp parameters specify the FQDN and port that the client tries first. If the node specified by firstEp is unavailable, the client falls back to secondEp. This dual-node configuration ensures high availability for the application.
# Linux/Mac configuration file path
/etc/taos/taos.cfg
# Windows configuration file path
C:\TDengine\cfg\taos.cfg
The serverPort parameter specifies the TDengine server port, with a default of 6030. When the client needs to connect to a non-standard port, set this parameter in the configuration file.
The compressMsgSize parameter controls the message compression threshold. When a message exceeds this size, the client compresses it before transmission, reducing network bandwidth usage. The default value is -1, meaning no compression. A common recommendation is to set this to 1024 (1 KB) or higher to enable compression.
# Connection configuration example
firstEp node1.example.com:6030
secondEp node2.example.com:6030
serverPort 6030
compressMsgSize 1024
Query performance configuration
Query performance settings directly affect data read efficiency in TDengine. Thoughtful configuration can improve query response times.
The countAlwaysReturnValue parameter controls whether the COUNT function returns 0 or NULL when there is no data. When enabled, COUNT queries return 0 instead of NULL even if the Supertable contains no data, which can simplify application logic.
The keepColumnName parameter determines how column names are preserved in query results. By default, TDengine returns the original column names. When this parameter is enabled, query results retain the full table name and column name, making it easier for front-end parsing.
The queryPolicy parameter configures the query strategy, supporting several query algorithms. For queries involving aggregation across multiple timelines, the right query strategy can deliver noticeable performance gains.
# Query configuration example
countAlwaysReturnValue 1
keepColumnName 1
queryPolicy 2
Write configuration and batch processing
Data writing is one of the core workloads of TDengine. Proper write configuration can increase data throughput.
The smlChildTableName parameter configures the label template used to define the naming rules for Subtable names under a Supertable. Well-configured Subtable naming rules help keep the time-series data storage structure organized.
The maxInsertBatchRows parameter controls the maximum number of rows per batch insert. A recommended range is 1000 to 10000, balancing write performance against memory usage. For high-frequency write scenarios, a higher value may be appropriate.
The maxSQLLength parameter limits the maximum length of SQL statements, defaulting to 1048576 bytes (1 MB). In batch write scenarios where SQL statements are long, this parameter may need adjustment to support larger batches.
# Write configuration example
smlChildTableName device_id
maxInsertBatchRows 5000
maxSQLLength 2097152
Locale and character set configuration
Locale configuration in TDengine is important for international applications.
The timezone parameter specifies the timezone used by the client, defaulting to the system timezone. For cross-timezone data processing, configure this explicitly to ensure correct timestamp conversion.
The locale parameter configures localization support. A correct locale setting ensures that date formats and sorting rules match regional conventions.
The charset parameter specifies the character encoding. UTF-8 is recommended for the best compatibility. TDengine uses UTF-8 encoding internally, and keeping the client configuration consistent avoids performance overhead from character conversion.
# Locale configuration example
timezone America/New_York
locale en_US.UTF-8
charset UTF-8
Storage and temporary file configuration
Storage settings affect how the TDengine client manages temporary files and disk space.
The tempDir parameter specifies the client temporary file directory, used for caching query results. In high-concurrency query scenarios, make sure this directory has enough disk space.
The minimalTmpDirGB parameter sets the minimum free space threshold for the temporary directory. When disk space falls below this value, TDengine logs a warning.
# Storage configuration example
tempDir /var/lib/taos/tmp
minimalTmpDirGB 10
Log configuration and debugging
Log configuration is a key tool for troubleshooting TDengine client issues.
The logDir parameter specifies the log file directory. Log files are named in the format taoslog0.tar.gz.
The numOfLogLines parameter controls the maximum number of lines per log file, defaulting to 100000. When the log file reaches this limit, it rotates when the limit is reached.
The asyncLog parameter controls the log write mode. Set to 0 for synchronous writes, 1 for asynchronous writes. Asynchronous log writing reduces IO blocking but may lose the most recent log entries.
# Log configuration example
logDir /var/log/taos
numOfLogLines 200000
asyncLog 1
Native connection vs. WebSocket connection
The taosc driver supports two connection modes. Developers should choose based on their deployment scenario.
| Feature | Native connection | WebSocket connection |
|---|---|---|
| Connection method | Direct to taosd | Via taosAdapter |
| Performance | Higher | Slightly lower |
| Dependencies | Client installation required | HTTP support only |
| Cross-platform | Platform-dependent | All platforms |
| Firewall | taosd port must be open | Only ports 80/443 needed |
Native connections suit scenarios that demand high performance and homogeneous deployment. WebSocket connections are better for cross-platform, cross-language heterogeneous system integration.
Scenario-based configuration recommendations
Industrial IoT
Industrial IoT scenarios typically handle large volumes of time-series data. A higher maxInsertBatchRows value (5000 to 10000) is recommended, with compressMsgSize enabled to reduce network overhead.
firstEp iot-gateway1:6030
secondEp iot-gateway2:6030
maxInsertBatchRows 10000
compressMsgSize 1024
queryPolicy 2
Financial time-series data
Financial data demands high accuracy. Disable asynchronous logging (asyncLog set to 0) to guarantee logs are written promptly. For high-frequency trading scenarios, increase the maxSQLLength parameter.
firstEp finance-node1:6030
secondEp finance-node2:6030
asyncLog 0
maxSQLLength 4194304
numOfLogLines 500000
Summary
The taosc client driver is an essential part of TDengine. Knowing how to configure it makes the difference between adequate and excellent performance for time-series data applications. The parameters covered here span connection setup, query tuning, write throughput, locale settings, storage paths, and logging behavior.
Tailor the configuration to your business scenario and hardware environment, and keep refining it by monitoring logs and performance metrics. For more TDengine configuration details, refer to the TDengine documentation.
