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. -u/-user The default value is root.
-p/--password The password to connect to the taosd server, the default value is taosdata. -o/--output 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 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. -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. -l/--columns
-A/--tag-type The data type of the tag of the sub-table. [-B
-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. -E/-escape-character
-C/--chinese Whether nchar and binary are basic Unicode Chinese characters, optional. C
-N/--normal-table Create only normal tables, not super tables, optional. N/--normal-table
-M/--random Whether to use random data source, optional. -M/--random
-x/--aggr-func Query aggregate function after insert, optional. --aggr-func
-y/--answer-yes Continue via confirmation prompt, optional. -x
-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/--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 The number of copies to create the database, default is 1.
-V/--version Display version information and exit
-? /--help Show help information and exit. --V/--version

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 (https://www.taosdata.com/docs/cn/v2.0/taos-sql#data-type) 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.