taosBenchmark Reference

taosBenchmark (formerly known as taosdemo) is a tool used for testing the performance of TDengine products. taosBenchmark can test the performance of TDengine's insert, query, and subscription functions. It can simulate a large amount of data generated by numerous devices and allows flexible control over the number and types of databases, supertables, tag columns, data columns, subtables, the amount of data per subtable, the time interval for inserting data, the number of worker threads in taosBenchmark, and whether to insert out-of-order data, among other parameters. To accommodate past user habits, the installation package provides taosdemo as a symlink to taosBenchmark.

Installation

taosBenchmark can be installed in two ways:

• It is automatically installed when you install the official TDengine installation package. For details, please refer to TDengine Installation.
• You can compile taos-tools separately and install it. For more information, please refer to the taos-tools repository.

Running

Configuration and Running Modes

taosBenchmark needs to be executed from the terminal of the operating system. This tool supports two configuration methods: command-line parameters and JSON configuration files. These two methods are mutually exclusive; when using a configuration file, only the command-line parameter -f <json file> can be specified. When running taosBenchmark using command-line parameters to control its behavior, the -f parameter must not be used, and other parameters should be used for configuration. Additionally, taosBenchmark offers a special running mode that requires no parameters.

taosBenchmark supports comprehensive performance testing for TDengine, which can be categorized into three main functions: writing, querying, and subscribing. These functions are mutually exclusive, meaning that taosBenchmark can only test one at a time. Notably, when using command-line configuration methods, the type of function to be tested cannot be configured, and command-line configurations can only test write performance. To test TDengine's query and subscription performance, you must use the configuration file method and specify the function type in the configuration file with the parameter filetype.

Before running taosBenchmark, ensure that the TDengine cluster is running correctly.

Running Without Command-Line Parameters

You can quickly experience the write performance test of taosBenchmark against TDengine using default configurations by executing the following command:

taosBenchmark

In the no-parameter run, taosBenchmark will by default connect to the TDengine cluster specified in /etc/taos, create a database named test in TDengine, create a supertable named meters under the test database, and write 10,000 records into 10,000 tables. Note that if the test database already exists, this command will first delete it and then create a new test database.

Running with Command-Line Configuration Parameters

When running taosBenchmark using command-line parameters to control its behavior, the -f <json file> parameter cannot be used. All configuration parameters must be specified via the command line. Below is an example of using command-line arguments to test taosBenchmark write performance:

taosBenchmark -I stmt -n 200 -t 100

The above command will create a database named test, establish a supertable named meters, and insert 200 records into each of the 100 subtables using parameter binding.

Running with a Configuration File

The installation package for taosBenchmark includes example configuration files located in <install_directory>/examples/taosbenchmark-json. You can run taosBenchmark and control its behavior via the configuration file with the following command:

taosBenchmark -f <json file>

Here are several examples of configuration files:

Insert Scenario JSON Configuration File Example

insert.json

{
    "filetype": "insert",
    "cfgdir": "/etc/taos",
    "host": "127.0.0.1",
    "port": 6030,
    "user": "root",
    "password": "taosdata",
    "connection_pool_size": 8,
    "thread_count": 4,
    "create_table_thread_count": 4,
    "result_file": "./insert_res.txt",
    "confirm_parameter_prompt": "no",
    "num_of_records_per_req": 10000,
    "prepared_rand": 10000,
    "chinese": "no",
    "escape_character": "yes",
    "continue_if_fail": "no",
    "databases": [
        {
            "dbinfo": {
                "name": "test",
                "drop": "yes",
                "vgroups": 4,
                "precision": "ms"
            },
            "super_tables": [
                {
                    "name": "meters",
                    "child_table_exists": "no",
                    "childtable_count": 1000,
                    "childtable_prefix": "d",
                    "auto_create_table": "no",
                    "batch_create_tbl_num": 5,
                    "data_source": "rand",
                    "insert_mode": "taosc",
                    "non_stop_mode": "no",
                    "line_protocol": "line",
                    "insert_rows": 10000,
                    "childtable_limit": 0,
                    "childtable_offset": 0,
                    "interlace_rows": 0,
                    "insert_interval": 0,
                    "partial_col_num": 0,
                    "timestamp_step": 10,
                    "start_timestamp": "2020-10-01 00:00:00.000",
                    "sample_format": "csv",
                    "sample_file": "./sample.csv",
                    "use_sample_ts": "no",
                    "tags_file": "",
                    "columns": [
                        {"type": "FLOAT", "name": "current", "count": 1, "max": 12, "min": 8 },
                        { "type": "INT", "name": "voltage", "max": 225, "min": 215 },
                        { "type": "FLOAT", "name": "phase", "max": 1, "min": 0 }
                    ],
                    "tags": [
                        {"type": "TINYINT", "name": "groupid", "max": 10, "min": 1},
                        {"type": "BINARY",  "name": "location", "len": 16,
                            "values": ["San Francisco", "Los Angles", "San Diego",
                                "San Jose", "Palo Alto", "Campbell", "Mountain View",
                                "Sunnyvale", "Santa Clara", "Cupertino"]
                        }
                    ]
                }
            ]
        }
    ]
}

Query Scenario JSON Configuration File Example

query.json

{
	"filetype": "query",
	"cfgdir": "/etc/taos",
	"host": "127.0.0.1",
	"port": 6030,
	"user": "root",
	"password": "taosdata",
	"confirm_parameter_prompt": "no",
    "continue_if_fail": "yes",
	"databases": "test",
	"query_times": 10,
	"query_mode": "taosc",
	"specified_table_query": {
		"query_interval": 1,
		"concurrent": 3,
		"sqls": [
			{
				"sql": "select last_row(*) from meters",
				"result": "./query_res0.txt"
			},
			{
				"sql": "select count(*) from d0",
				"result": "./query_res1.txt"
			}
		]
	},
	"super_table_query": {
		"stblname": "meters",
		"query_interval": 1,
		"threads": 3,
		"sqls": [
			{
				"sql": "select last_row(ts) from xxxx",
				"result": "./query_res2.txt"
			}
		]
	}
}

Subscription Scenario JSON Configuration File Example

tmq.json

{
    "filetype": "subscribe",
    "cfgdir": "/etc/taos",
    "host": "127.0.0.1",
    "port": 6030,
    "user": "root",
    "password": "taosdata",
    "result_file": "tmq_res.txt",
    "tmq_info": {
        "concurrent": 3,
        "poll_delay": 10000,
        "group.id": "",
        "group_mode": "independent",
        "create_mode": "parallel",
        "client.id": "client001",
        "auto.offset.reset": "earliest",
        "enable.manual.commit": "false",
        "enable.auto.commit": "false",
        "auto.commit.interval.ms": 1000,
        "experimental.snapshot.enable": "false",
        "msg.with.table.name": "false",
        "rows_file": "rowfile",
        "topic_list": [
            {"name": "topic1", "sql": "select * from test.meters;"}
        ]
    }
}

Command-Line Parameter Details

• -f/--file <json file> : The JSON configuration file to use, which specifies all parameters. This parameter cannot be used simultaneously with other command-line parameters. No default value.
• -c/--config-dir <dir> : The directory where the TDengine cluster configuration file is located, with a default path of /etc/taos.
• -h/--host <host> : Specifies the FQDN of the TDengine server to connect to, with a default value of localhost.
• -P/--port <port> : The port number of the TDengine server to connect to, with a default value of 6030.
• -I/--interface <insertMode> : The insert mode. Optional values are taosc, rest, stmt, sml, and sml-rest, corresponding to regular insert, RESTful interface insert, parameter binding interface insert, schemaless interface insert, and RESTful schemaless interface insert (provided by taosAdapter). The default value is taosc.
• -u/--user <user> : The username used to connect to the TDengine server, with a default of root.
• -U/--supplement-insert : Write data without first creating the database and tables; this is off by default.
• -p/--password <passwd> : The password used to connect to the TDengine server, with a default value of taosdata.
• -o/--output <file> : The output file path for results, with a default value of ./output.txt.
• -T/--thread <threadNum> : The number of threads for inserting data, with a default of 8.
• -B/--interlace-rows <rowNum> : Enables interleaved insert mode and specifies the number of rows to insert into each subtable at a time. In interleaved insert mode, rows will be inserted into each subtable sequentially as specified until all data for all subtables has been inserted. The default value is 0, meaning that data insertion will proceed to the next subtable only after completing data insertion into one subtable.
• -i/--insert-interval <timeInterval> : Specifies the insertion interval for the interleaved insert mode in milliseconds, with a default value of 0. This only takes effect if -B/--interlace-rows is greater than 0, meaning that the data insertion thread will wait for the specified time interval after inserting records into each subtable before proceeding to the next round of inserts.
• -r/--rec-per-req <rowNum> : The number of rows to request writing to TDengine in each request, with a default value of 30000.
• -t/--tables <tableNum> : Specifies the number of subtables, with a default of 10000.
• -S/--timestampstep <stepLength> : The timestamp step length for inserting data into each subtable, in milliseconds, with a default value of 1.
• -n/--records <recordNum> : The number of records to insert into each subtable, with a default value of 10000.
• -d/--database <dbName> : The name of the database to be used, with a default value of test.
• -b/--data-type <colType> : The data types of the columns in the supertable. If not specified, the default is three columns with types FLOAT, INT, FLOAT.
• -l/--columns <colNum> : The total number of data columns in the supertable. If both this parameter and -b/--data-type are set, the resulting number of columns will be the greater of the two. If this parameter specifies a number greater than that specified by -b/--data-type, the unspecified column types default to INT. For example: -l 5 -b float,double, will yield columns FLOAT, DOUBLE, INT, INT, INT. If columns specifies a number less than or equal to that specified by -b/--data-type, the result will be the columns and types specified by -b/--data-type. For example: -l 3 -b float,double,float,bigint will yield columns FLOAT, DOUBLE, FLOAT, BIGINT.
• -L/--partial-col-num <colNum> : Specifies which columns will have data written to them, while the other columns will have NULL values. By default, all columns will have data written.
• -A/--tag-type <tagType> : The data types of the tag columns in the supertable. Both nchar and binary types can specify lengths. For example:

taosBenchmark -A INT,DOUBLE,NCHAR,BINARY(16)

If the tag types are not specified, the default is two tags with types INT and BINARY(16). Note: In some shells like bash, parentheses need to be escaped.

taosBenchmark -A INT,DOUBLE,NCHAR,BINARY\(16\)

• -w/--binwidth <length> : The default length for nchar and binary types, with a default value of 64.
• -m/--table-prefix <tablePrefix> : The prefix for subtable names, with a default value of "d".
• -E/--escape-character : A switch to specify whether to use escape characters in the names of supertables and subtables. The default is not to use them.
• -C/--chinese : A switch to specify whether nchar and binary types should use Unicode Chinese characters. The default is not to use.
• -N/--normal-table : A switch to specify that only basic tables should be created, without supertables. The default is false. This can only be used when the insert mode is taosc, stmt, or rest.
• -M/--random : A switch to generate random values for the data being inserted. The default is false. If this parameter is configured, random values will be generated for the data to be inserted. For numeric types of tag/data columns, the values will be random within the range of that type. For NCHAR and BINARY types, the values will be random strings within the specified length range.
• -x/--aggr-func : A switch indicating that an aggregate function should be queried after insertion. The default is false.
• -y/--answer-yes : A switch requiring user confirmation to continue after a prompt. The default is false.
• -O/--disorder <Percentage> : Specifies the percentage probability of out-of-order data, ranging from [0,50]. The default is 0, meaning no out-of-order data.
• -R/--disorder-range <timeRange> : Specifies the timestamp rollback range for out-of-order data. The generated out-of-order timestamps will be the expected timestamps minus a random value within this range. This is only effective if the out-of-order data percentage specified by -O/--disorder is greater than 0.
• -F/--prepare_rand <Num> : The number of unique values in the generated random data. If set to 1, all data will be the same. The default is 10000.
• -a/--replica <replicaNum> : Specifies the number of replicas when creating the database, with a default of 1.
• -k/--keep-trying <NUMBER> : The number of times to retry after a failure, with no retries by default. This requires version v3.0.9 or above.
• -z/--trying-interval <NUMBER> : The interval time for retries after a failure, in milliseconds, and only effective when -k specifies retries. This requires version v3.0.9 or above.
• -v/--vgroups <NUMBER> : Specifies the number of vgroups when creating the database, effective only for TDengine v3.0+.
• -V/--version : Displays version information and exits. This cannot be mixed with other parameters.
• -?/--help : Displays help information and exits. This cannot be mixed with other parameters.

Configuration File Parameter Details

General Configuration Parameters

The parameters listed in this section apply to all function modes.

• filetype : The function to be tested, optional values are insert, query, and subscribe, corresponding to insert, query, and subscription functions, respectively. Only one of these can be specified in each configuration file.
• cfgdir : The directory where the TDengine client configuration file is located, with a default path of /etc/taos.
• host : Specifies the FQDN of the TDengine server to connect to, with a default value of localhost.
• port : The port number of the TDengine server to connect to, with a default value of 6030.
• user : The username used to connect to the TDengine server, with a default of root.
• password : The password used to connect to the TDengine server, with a default value of taosdata.

Insert Scenario Configuration Parameters

In the insert scenario, filetype must be set to insert. This parameter and other general parameters are detailed in General Configuration Parameters.

• keep_trying : The number of retries after a failure, with no retries by default. This requires version v3.0.9 or above.
• trying_interval : The interval time for retries after a failure, in milliseconds, only effective when keep_trying specifies retries. This requires version v3.0.9 or above.
• childtable_from and childtable_to : Specify the range of subtables to write to, with a closed interval of [childtable_from, childtable_to).
• continue_if_fail : Allows the user to define behavior after a failure.
  • "continue_if_fail": "no": taosBenchmark automatically exits on failure (default behavior).
  • "continue_if_fail": "yes": taosBenchmark warns the user and continues writing on failure.
  • "continue_if_fail": "smart": If the subtable does not exist, taosBenchmark will create it and continue writing.

Database Related Configuration Parameters

Configuration parameters related to creating databases are set in the dbinfo section of the JSON configuration file. Some specific parameters are as follows. Other parameters correspond to the parameters specified in the TDengine create database command. For details, refer to [../../taos-sql/database].

• name : The name of the database.
• drop : Whether to delete the database before inserting, with optional values of "yes" or "no". Defaults to delete.

Stream Processing Configuration Parameters

Configuration parameters related to creating stream processing are set in the stream section of the JSON configuration file, with the following specific parameters.

• stream_name : The name of the stream processing, which is required.
• stream_stb : The name of the corresponding supertable for the stream processing, which is required.
• stream_sql : The SQL statement for the stream processing, which is required.
• trigger_mode : The trigger mode for the stream processing, with optional values.
• watermark : The watermark for the stream processing, with optional values.
• drop : Whether to create the stream processing, with optional values of "yes" or "no". If set to "no", it will not be created.

Supertable Related Configuration Parameters

Configuration parameters related to creating supertables are set in the super_tables section of the JSON configuration file, with specific parameters as follows.

• name: The name of the supertable, which is required and has no default value.
• child_table_exists : Whether the subtables already exist, default is "no", with optional values of "yes" or "no".
• child_table_count : The number of subtables, default is 10.
• child_table_prefix : The prefix for subtable names, which is a required configuration item and has no default value.
• escape_character : Whether to include escape characters in supertable and subtable names, default is "no", with optional values of "yes" or "no".
• auto_create_table : Only effective when the insert mode is taosc, rest, stmt, and child_table_exists is "no". If this parameter is set to "yes", taosBenchmark will automatically create the non-existent tables when inserting data; if set to "no", it indicates that all tables should be created in advance before inserting data.
• batch_create_tbl_num : The number of tables to create in each batch, default is 10. Note: The actual number of batches may not match this value; when the executed SQL statement exceeds the maximum allowed length, it will be automatically truncated and executed to continue creating.
• data_source : The source of the data, default is random data generated by taosBenchmark. Can be configured as "rand" or "sample". When set to "sample", the data will be sourced from the specified file using the sample_file parameter.
• insert_mode : The insert mode, with optional values of taosc, rest, stmt, sml, and sml-rest, corresponding to regular insert, RESTful interface insert, parameter binding interface insert, schemaless interface insert, and RESTful schemaless interface insert (provided by taosAdapter). The default value is taosc.
• non_stop_mode : Indicates whether to continue writing. If set to "yes", the insert_rows parameter will be ineffective until the program is stopped with Ctrl + C. The default value is "no", meaning that it will stop after writing the specified number of records. Note: Even in continuous write mode, insert_rows must be configured as a positive integer.
• line_protocol : Inserts data using line protocol, effective only when the insert mode is sml or sml-rest, with optional values of line, telnet, json.
• tcp_transfer : The communication protocol in telnet mode, effective only when the insert mode is sml-rest and line_protocol is telnet. If not configured, the default is HTTP protocol.
• insert_rows : The number of records to insert into each subtable, default is 0.
• childtable_offset : Effective only when child_table_exists is "yes", specifies the offset when obtaining the list of subtables from the supertable, i.e., starting from which subtable.
• childtable_limit : Effective only when child_table_exists is "yes", specifies the limit when obtaining the list of subtables from the supertable.
• interlace_rows : Enables interleaved insert mode and specifies the number of rows to insert into each subtable at a time. The default value is 0, meaning that data will be inserted into each subtable only after completing the data insertion into one subtable.
• insert_interval : Specifies the insertion interval for the interleaved insert mode in milliseconds, with a default value of 0. This only takes effect if -B/--interlace-rows is greater than 0.

Query Scenario Configuration Parameters

In the query scenario, filetype must be set to query. The parameter query_times specifies the number of times to execute the query.

The query scenario can control the execution of slow queries through the kill_slow_query_threshold and kill_slow_query_interval parameters. The threshold controls if queries exceeding the specified execution time (exec_usec) will be killed by taosBenchmark, measured in seconds; the interval controls the sleep duration to avoid consuming CPU resources with continuous slow queries, measured in seconds.

Other general parameters can be found in General Configuration Parameters.

Configuration Parameters for Executing Specified Query Statements

The configuration parameters for querying specified tables (including supertables, subtables, or basic tables) are set in the specified_table_query section.

• query_interval : The interval for querying, measured in seconds, default value is 0.
• threads : The number of threads executing the query SQL, default is 1.
• sqls：
  • sql: The SQL command to execute, required.
  • result: The file to save the query results; if not specified, it will not be saved.

Configuration Parameters for Querying Supertables

The configuration parameters for querying supertables are set in the super_table_query section.

• stblname : The name of the supertable to query, required.
• query_interval : The interval for querying, measured in seconds, default value is 0.
• threads : The number of threads executing the query SQL, default is 1.
• sqls ：
  • sql : The SQL command to execute, required. For querying supertables, the SQL command should retain "xxxx", which will be automatically replaced by the names of all the subtables in the supertable.

Subscription Scenario Configuration Parameters

In the subscription scenario, filetype must be set to subscribe. This parameter and other general parameters are detailed in General Configuration Parameters.

Configuration Parameters for Executing Specified Subscription Statements

The configuration parameters for subscribing to specified tables (including supertables, subtables, or basic tables) are set in the specified_table_query section.

• threads/concurrent: The number of threads executing the SQL, default is 1.
• sqls:
  • sql: The SQL command to execute, required.

Configuration File Data Type Reference Table

#	Engine	taosBenchmark
1	TIMESTAMP	timestamp
2	INT	int
3	INT UNSIGNED	uint
4	BIGINT	bigint
5	BIGINT UNSIGNED	ubigint
6	FLOAT	float
7	DOUBLE	double
8	BINARY	binary
9	SMALLINT	smallint
10	SMALLINT UNSIGNED	usmallint
11	TINYINT	tinyint
12	TINYINT UNSIGNED	utinyint
13	BOOL	bool
14	NCHAR	nchar
15	VARCHAR	varchar
16	VARBINARY	varbinary
17	GEOMETRY	geometry
18	JSON	json

Note: Data types in the taosBenchmark configuration file must be in lowercase to be recognized.