taosBenchmark

Introduction

taosBenchmark is a performance testing application for TDengine. taosBenchmark can test insertion, query and subscription functions of TDengine, it can simulate a large amount of data generated by a large number of devices, and it can also flexibly control the number of columns, data types, threads, etc. Previously called taosdemo, it is now renamed taosBenchmark. The installer provides taosdemo as a soft link to taosBenchmark. Configuration, one is command line configuration and the other is JSON file.

CLI

option name	description
-f/--file	JSON configuration file, cannot be used with other command line parameters
-c/--config-dir	The default path to the configuration file is /etc/taos/
-h/--host	The FQDN to connect to the taosd server, the default value is localhost.
-P/--port	The port number to connect to the taosd server, the default value is 6030.
-I/--interface	How taosBenchmark inserts data, the default value is taosc.
-u/--user	The username to connect to the taosd server, the default value is root.
-p/--password	The password to connect to the taosd server, the default value is taosdata.
-o/--output	Specify the path of the result output file, the default value is ./output.txt.
-T/--thread	Specify the number of threads to insert the data, the default value is 8
-i/--insert-interval	The insertion interval for interline insertion mode, in ms, the default value is 0.
-S/--timestampstep	The insert timestamp step for each row in each sub-table in ms, the default value is 1
-B/--interlace-rows	The number of interleaved rows to insert into the sub-table
-r/--rec-per-req	The number of rows per insert request, the default is 30000
-t/--tables	The number of sub-tables, the default value is 10000.
-n/--records	The number of records to insert per sub-table, the default value is 10000.
-d/--database	The name of the database, the default value is test.
-l/--columns	The number of columns in the sub-table, will use int data type columns.
-A/--tag-type	The data type of the tag of the sub-table.
-b/--data-type	The data type of the column of the sub-table.
-w/--binwidth	Adjusts the default length of nchar and binary data types, the default value is 64.
-m/--table-prefix	The prefix of the sub-table name, the default value is d
-E/--escape-character	Use escape characters in super table and sub table names, optional.
-C/--chinese	Whether nchar and binary are basic Unicode Chinese characters, optional.
-N/--normal-table	Create only normal tables, not super tables, optional.
-M/--random	Whether to use random data source, optional.
-x/--aggr-func	Query aggregate function after insert, optional.
-y/--answer-yes	Continue via confirmation prompt, optional.
-R/--disorder-range	Range of out-of-order timestamps, based on database precision, default is 1000
-O/--disorder	The probability of inserting data with out-of-order timestamp, default is 0.
-F/--prepare_rand	The number of random numbers to produce random data, default is 10000
-a/--replica	The number of copies to create the database, default is 1.
-V/--version	Display version information and exit
-?/--help	Show help information and exit.

JSON

1、insert json configuration file

{
    "filetype": "insert",
    "cfgdir": "/etc/taos",
    "host": "127.0.0.1",
    "port": 6030,
    "user": "root",
    "password": "taosdata",
    "connection_pool_size": 8,
    "thread_count": 4,
    "result_file": "./insert_res.txt",
    "confirm_parameter_prompt": "no",
    "insert_interval": 0,
    "interlace_rows": 100,
    "num_of_records_per_req": 100,
    "prepared_rand": 10000,
    "chinese":"no",
    "databases": [{
      "dbinfo": {
        "name": "db",
        "drop": "yes",
        "replica": 1,
        "days": 10,
        "cache": 16,
        "blocks": 8,
        "precision": "ms",
        "keep": 3650,
        "minRows": 100,
        "maxRows": 4096,
        "comp":2,
        "walLevel":1,
        "cachelast":0,
        "quorum":1,
        "fsync":3000,
        "update": 0
      },
      "super_tables": [{
        "name": "stb",
        "child_table_exists":"no",
        "childtable_count": 100,
        "childtable_prefix": "stb_",
        "escape_character": "yes",
        "auto_create_table": "no",
        "batch_create_tbl_num": 5,
        "data_source": "rand",
        "insert_mode": "taosc",
        "line_protocol": "line",
        "insert_rows": 100000,
        "childtable_limit": 10,
        "childtable_offset":100,
        "interlace_rows": 0,
        "insert_interval":0,
        "partial_col_num": 0,
        "disorder_ratio": 0,
        "disorder_range": 1000,
        "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": "INT", "name": "id"}, {"type": "DOUBLE", "count":10}, {"type": "BINARY", "len": 16, "count":3}, {"type": "BINARY", "len": 32, "count":6}],
        "tags": [{"type": "TINYINT", "count":2, "max": 10, "min": 98}, {"type": "BINARY", "len": 16, "count":5, "values":["beijing","shanghai"]}]
      }]
    }]
}

Parameters

Group	Option Name	Description
	filetype	filetype, specifies which test, for insert test, it needs to be insert.
	cfgdir	The directory where the taosd configuration file is located, the default value is /etc/taos.
	host	The FQDN of the taosd server, the default is localhost.
	port	The port number of the taosd server, the default is 6030.
	user	The username to connect to the taosd server, default is root.
	password	The password to connect to the taosd server, default is taosdata.
	connection_pool_size	The size of the taos connection pool, the default is the number of threads.
	thread_count	The number of threads to insert and create tables, defaults to 8.
	result_file	The path to the file where the output will be saved, defaults to . /output.txt.
	confirm_parameter_prompt	Passes a confirmation prompt during execution, defaults to none.
	insert_interval	The interval for inserting interlace mode, default is 0.
	interlace_rows	The number of interleaved rows per child table, default is 0.
	num_of_records_per_req	The number of records per request, the default is 30000.
	prepare_rand	The number of randomly generated data, the default is 10000
	chinese	Both nchar and binary are rand Chinese, default is no.
dbinfo	name	The database name, required
dbinfo	drop	Whether to delete the database before inserting tests.
dbinfo	replica	The number of replicas, the default value is 1.
dbinfo	days	The span of time to store data in the file, the default value is 10.
dbinfo	cache	The size of the memory blocks in MB, the default value is 16.
dbinfo	blocks	The number of memory blocks per vnode(tsdb) for the cache size, the default is 6.
dbinfo	precision	The database time precision, the default value is "ms".
dbinfo	keep	The number of days to keep the data, the default value is 3650.
dbinfo	minRows	The minimum number of records in the file block, the default value is 100
dbinfo	minRows	The maximum number of records in the file block, the default value is 4096.
dbinfo	comp	The file compression flag, the default value is 2.
dbinfo	walLevel	The wal level, the default value is 1.
dbinfo	cachelast	Whether to allow the last record of each table to be kept in memory, with a default value of 0
dbinfo	quorum	The number of confirmations required for asynchronous writes, the default is 1.
dbinfo	fsync	The interval for fsync when wal is set to 2, in ms, default is 3000.
dbinfo	update	Whether to support data updates, the default is 0.
super_tables	name	The name of the super table, must be filled in.
super_tables	child_table_exists	Whether the child table already exists, default is no.
super_tables	child_table_count	The number of child tables, required.
super_tables	child_table_prefix	The prefix of the child table name, required.
super_tables	escape_character	The names of the super and child tables include escape characters, default is no.
super_tables	auto_create_table	Whether the SQL statement automatically creates sub-tables.
super_tables	batch_create_tbl_num	The number of sub-tables to create for each request, default is 10.
super_tables	data_source	Data resource type, options: rand, sample.
super_tables	insert_mode	Insert mode, options: taosc, rest, stmt, sml, default is taosc.
super_tables	non-stop_mode	Whether the insertion mode is a continuous non-stop write, default is no
super_tables	line_protocol	Line protocol, optional: line, telnet, json, default is line.
super_tables	tcp_transfer	Whether to use tcp or http protocol, default is http.
super_tables	insert_rows	The number of rows in each sub-table, default is 0.
super_tables	childtable_offset	The offset of the child table.
super_tables	childtable_limit	The number of child tables to insert data into.
super_tables	interlace_rows	The interval rows of each child table, default is 0.
super_tables	insert_interval	The insert interval between two requests, valid when interlace_rows is greater than 0.
super_tables	partial_col_num	Specifies the number of columns to be written to, default is 0.
super_tables	disorder_ratio	The data ratio for disorder timestamps, default is 0
super_tables	disorder_range	The range of the disorder timestamp, valid only if disorder_ratio is greater than 0, defaults to 1000.
super_tables	timestamp_step	The timestamp step for each record, defaults to 1.
super_tables	start_timestamp	The timestamp start value for each sub-table, the default is now.
super_tables	sample_format	The type of the sample data file, now only csv is supported.
super_tables	sample_file	The sample file, only valid if data_source is "sample".
super_tables	use_sample_ts	Whether the sample file contains a timestamp, defaults to no.
super_tables	tags_file	Same principle as sample_file, tags data sample file, only supports taosc, rest insert mode.
columns/tags	type	Data type, required
columns/tags	len	The length of the data, default is 8.
columns/tags	count	The number of consecutive columns, default is 1.
columns/tags	name	The name of this column, the consecutive column name will be name_#<number>.
columns/tags	min	The minimum value of the numeric data type column/tag
columns/tags	max	The maximum value of the numeric data type column/label
columns/tags	values	nchar/binary The values of the columns/tags will be chosen randomly from the values.

2、Query test json configuration file

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

Query test JSON file's parameters

Group	Options	Description
	filetype	file type to specify which kind of test, for query test, required
	cfgdir	the directory where taos configuration file in
	host	FQDN of taosd server, default is localhost
	port	port number of taosd server, default is 6030
	user	username to connect taosd server, default is root
	password	password to connect taosd server, default is taosdata
	confirm_parameter_prompt	pass the confirmation prompt during execution, the default is no
	databases	name of database, required
	query_times	number of query times
	query_mode	query mode, options: taosc and rest, default is taosc
specified_table_query/super_table_query	query_interval	query interval, unit is second, default is 0
specified_table_query/super_table_query	concurrent/threads	number of thread to execute sql, default is 1
super_table_query	stblname	supertable name, required
sqls	sql	sql command, required
sqls	result	result file for query result, empty for none

3、Subscribe json configuration file

{
  "filetype":"subscribe",
  "cfgdir": "/etc/taos",
  "host": "127.0.0.1",
  "port": 6030,
  "user": "root",
  "password": "taosdata",
  "databases": "db",
  "confirm_parameter_prompt": "no",
  "specified_table_query":
    {
      "concurrent":1,
      "interval":0,
      "restart":"yes",
      "keepProgress":"yes",
      "sqls": [
        {
          "sql": "select * from stb00_0 ;",
          "result": "./subscribe_res0.txt"
        }
        ]
      },
      "super_table_query":
      {
        "stblname": "stb0",
        "threads":1,
        "interval":10000,
        "restart":"yes",
        "keepProgress":"yes",
        "sqls": [
        {
          "sql": "select * from xxxx where ts > '2021-02-25 11:35:00.000' ;",
          "result": "./subscribe_res1.txt"
        }]
      }
}

Subscribe test JSON file's parameters

Group	Options	Description
	filetype	file type to specify which kind of test, for subscribe test, required
	cfgdir	the directory of taos configuration file
	host	FQDN of taosd server, default is localhost
	port	port number of taosd server, default is 6030
	user	username to connect taosd server, default is root
	password	password to connect taosd server, default is taosdata
	databases	database name, required
	confirm_parameter_prompt	whether pass the confirmation prompt during execution
specified_table_query/super_table_query	concurrent/threads	number of thread to execute sqls, default is 1
specified_table_query/super_table_query	interval	interval to execute subscribe, default is 0
specified_table_query/super_table_query	restart	no: continue previous subscription, yes: start a new subscription
specified_table_query/super_table_query	keepProgress	whether keep the subscribe progress
specified_table_query/super_table_query	resubAfterConsume	whether unsubscribe and then subscribe again
super_table_query	stblname	name of supertable, required
sqls	sql	sql command, required
sqls	result	result file for query result, empty for none

Parameter specifics

return

insert mode

Options are taosc, rest, stmt, sml, sml-rest, corresponding to c-interface, restful, parameter binding, schemaless c-interface, taosAdapter schemaless write

insert interval

Only works if interlace rows is greater than 0. Means that the thread will wait for that value for as long as it takes before doing the next round of writes after inserting interlace rows for each child table.

partial col num

If the value is 5, only the first 5 columns are written to, only if insert_mode is taosc and rest, and 0 is written to all columns.

batch create tbl num

The number of batches to create the child table, default is 10.

Note: The actual number of batches may not be the same as this value. When the executed SQL statement is longer than the maximum supported length, it will be automatically truncated and re-executed to continue creating.

auto create table

Only when insert_mode is taosc, rest, stmt and childtable_exists is "no", this parameter means execute the written SQL statement, if it is " yes" then insert into tb using stb tags (xxx,xxx,...) values (xxx,xxx,...) This format, if "no", would be insert into tb values (xxx,xxx,...) The former does not need to create a sub-table in advance, the latter does.

interlace rows

If its value is 0, it means insert sub-table by sub-table, if its value is greater than zero, for example, 5, it will insert first to the first subtable with 5 rows, then the second subtable with 5 rows, then the third, and so on. After all sub-tables have been written to with 5 records, the thread will continue writing from the first sub-table, and so on.

record per request

The number of rows included in each insert request/api call is also the batch count. When the batch count is too large, the taos client will return the corresponding error message, and this number needs to be adjusted to meet the write requirement.

columns

If both this parameter and -b/--data-type are set, the number of columns of the column type set by this parameter and -b/--data-type will be compared, if the former is greater than the latter, for example: -l 5 -b float,double, then the last column will be FLOAT,DOUBLE,INT,INT,INT. If the former is less than or equal to the latter, for example: -l 3 -b float,double,float,bigint, then the last column is FLOAT,DOUBLE,FLOAT,BIGINT.

tag type

Set the tag type of the super table, nchar and binary can also set the length, for example:

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

The default is INT,BINARY(16).

Note: In some shells, such as bash, "()" needs to be escaped, so the above command should be

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

data type

Same as -A/--tag-type but for columns, defaults to FLOAT,INT,FLOAT

random

By default, the data is the data of the collection point of the analog meter with a specific size range of data values. If the sub-parameter is configured, the data will be randomly generated from the largest supported plus or minus 32-bit integer. If there are other parameters to modify the table structure, such as -l, -b, -A, etc... The data will be automatically generated randomly from the largest supported plus or minus 32-bit integers.

disorder ratio

The probability of random disorder timestamps, up to 50, i.e. 50%. The random disorder timestamp is the timestamp within a random disorder-range backwards of the timestamp of the current data to be inserted.

disorder range

Valid only if -O/--disorder is greater than 0, in the same units as the database's time precision.

prepared rand

As the number of random data pre-generated by the data source, a small prepared_rand will save memory, but will reduce the variety of data. If it is 1, then all data of the same type is generated equally.

connection pool size

All interactions with taos c clients require taos instances, which are created in advance to prevent failures due to interruptions during operation, this value determines the number of taos instances to be created in advance. If not configured, it is the same as the number of threads.

data source

The source of the data, which by default is randomly generated by taosBenchmark and can be configured as sample, i.e. data from the file specified with the sample_file parameter.

line protocol

Line protocol, only if insert_mode is sml and sml-rest, options are line, telnet, json.

non stop mode

If "yes", insert_rows will not work until Ctrl + C stops the program, then writing will stop.

Note: even though insert_rows is invalid, it must be a non-zero positive integer.

tcp transfer

Only works if insert_mode is sml-rest and line-protocol is telnet, two protocols are supported: tcp and http, default is http.

normal table

Only available when insert_mode is taosc, stmt, rest mode, no super table is created, only normal table is created.

childtable limit

Only works if childtable_exists is yes, for use with the statement select tbname from stable limit x offset y; The value x of limit in the statement ``` is the number of existing child tables to get inserted.

childtable offset

Only works if childtable_exists is yes, for the use of the statement select tbname from stable limit x offset y; to get the offset y of the inserted child table.

sample file

Whether to use data in csv format as data source, only when data_source is sample.

If the number of rows in the csv file is smaller than prepared_rand, then the csv file data will be read cyclically until it is the same as prepared_rand, if it is larger, then only the number of rows of prepared_rand will be read. If it is greater than that, only the rows with the number of prepared_rand will be read.

use sample ts

Only works when data_source is sample. sample_file specifies whether the csv file contains the first column timestamp, the default is no. If yes, the timestamp of the first column of the csv file is used. rows will be invalid.

tags file

Only works when insert_mode is taosc, rest.

Note: The principle here is similar to sample-file, the final tag value is related to the childtable_count, if the tag data rows in the csv file are smaller than the given number of child tables, then the csv file data will be read cyclically until the number of child tables is the same, if it is larger, then only the childtable_count rows of tag data.

type

Please refer to the officially supported data types for optional values.

Note: JSON data type is special, only in tags can be selected, and there is only one JSON tag column, at this time count and len represent the meaning of the number of key-value pairs within the JSON tag and the length of the value of each KV pair, respectively. The default value is string.

count

For example, if we want to test the performance of 4096 columns, instead of listing 4096 columns, we can just use "count": 4096.

len

The length of this data type, valid for NCHAR, BINARY and JSON data types, if configured for other data types, if it is 0, it means the column is always written with null value, if it is other numbers, it is meaningless and not recommended.

name

The name of the column, if used together with count, e.g. ```"name": "current", "count":3``, then the names of the 3 columns are current, current_2. current_3

sql

For the query SQL of super table, keep "xxxx" in the SQL command, the program will replace it with all the sub-table names of the super table automatically. Replace it with all the sub-table names in the super table.