Skip to main content

Get Started with TDengine TSDB Using Docker

You can install TDengine TSDB in a Docker container and perform some basic tests to verify its performance.

To install TDengine TSDB on your local machine instead of in a container, see Get Started with TDengine TSDB Using an Installation Package.

Before You Begin​

  • Install Docker. For more information, see the Docker website.
  • Ensure that the network ports required by TDengine TSDB are not currently in use. For more information, see Network Port Requirements.

Procedure​

  1. Pull the latest TDengine TSDB image:

    docker pull tdengine/tsdb-ee:latest
    note

    You can also pull a specific version of the image. For example:

    docker pull tdengine/tsdb-ee:{{VERSION}}

  2. Start a container with the following command:

    docker run -d -p 6030:6030 -p 6041:6041 -p 6043-6060:6043-6060 -p 6043-6060:6043-6060/udp tdengine/tsdb-ee

    To persist data to your local machine, use the following command:

    docker run -d -v <local-data-directory>:/var/lib/taos -v <local-log-directory>:/var/log/taos -p 6030:6030 -p 6041:6041 -p 6043-6060:6043-6060 -p 6043-6060:6043-6060/udp tdengine/tsdb-ee

  3. Verify that the container is running properly:

    docker ps

  4. Enter the container and open a shell:

    docker exec -it <container-name> bash

You can now work with TDengine TSDB inside your container. For example, you can run the taos command to open the TDengine TSDB command-line interface.

Quick Start​

TDengine TSDB CLI​

To easily check the status of TDengine TSDB and perform various ad-hoc database queries, TDengine TSDB provides a command-line interface. To enter the TDengine CLI, simply execute taos (on Linux/Mac) or taos.exe (on Windows) in your terminal. The prompt appears as:

taos>

In the TDengine TSDB CLI, you can use SQL commands to create or delete databases and tables, as well as perform data insertion and query operations. Each SQL statement executed in the terminal must end with a semicolon (;). For example:

CREATE DATABASE demo;
USE demo;
CREATE TABLE t (ts TIMESTAMP, speed INT);
INSERT INTO t VALUES ('2019-07-15 00:00:00', 10);
INSERT INTO t VALUES ('2019-07-15 01:00:00', 20);
SELECT * FROM t;
           ts            |    speed    |
========================================
 2019-07-15 00:00:00.000 |          10 |
 2019-07-15 01:00:00.000 |          20 |

Query OK, 2 row(s) in set (0.003128s)

You can also use the TDengine TSDB CLI to monitor system status, manage users, and perform administrative tasks.

The CLI and client drivers can be installed separately on other machines. For more details, see TDengine CLI Reference.

Data Ingestion​

taosBenchmark is a tool designed to evaluate TDengine’s performance in data ingestion, querying, and subscription. It can simulate data generated by numerous devices, allowing flexible configuration of database, supertable, tag columns, data columns, subtable counts, record counts, data intervals, number of threads, and whether to include out-of-order data.

To use taosBenchmark, ensure that TDengine is installed and running, and then execute the following command:

taosBenchmark -y

This automatically creates a database named test containing a supertable named meters. Within the supertable, 10,000 subtables named d0 through d9999 are generated, each containing 10,000 records. Each record has four fields: ts (timestamp), current, voltage, and phase, with timestamps ranging from 2017-07-14 10:40:00 000 to 2017-07-14 10:40:09 999. Each table also contains two tags: location and groupId, where groupId ranges from 1 to 10 and location includes cities in California such as California.Campbell and California.Cupertino.

After executing the taosBenchmark command, the system quickly writes 100 million records. The time required depends on your hardware, but on an average server, this process typically takes only a few seconds.

To customize testing parameters such as table counts or record numbers, taosBenchmark provides a wide range of options. To see all available parameters, run the following command:

taosBenchmark --help

For detailed usage instructions, see taosBenchmark Reference.

Data Querying​

After inserting data with taosBenchmark, you can run the following queries in the TDengine CLI to verify query performance.

Count total records in the supertable meters:

SELECT COUNT(*) FROM test.meters;

Calculate the average, maximum, and minimum of all records:

SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters;

Count records where location = California.SanFrancisco:

SELECT COUNT(*) FROM test.meters WHERE location = "California.SanFrancisco";

Query the average, maximum, and minimum for all records where groupId = 10:

SELECT AVG(current), MAX(voltage), MIN(phase) FROM test.meters WHERE groupId = 10;

Aggregate table d1001 in 10-second intervals and compute averages, maxima, and minima:

SELECT _wstart, AVG(current), MAX(voltage), MIN(phase) FROM test.d1001 INTERVAL(10s);
note

In the above query, the pseudocolumn _wstart represents the start time of each aggregation window.

TDengine TSDB Explorer​

TDengine TSDB Explorer is a web-based interface that allows you to manage and interact with TDengine directly from your browser.

To use TDengine TSDB Explorer, access its address in a web browser. The default port is 6060. For example, if TDengine is running locally, visit http://localhost:6060.

Enter your username and password and click Login. The default username is root and password taosdata.

If you have not logged in to TDengine TSDB Explorer before, you must register first. Enter your name and email address and click Get verification code. Then enter the verification code sent to your email address and click Submit.

After logging in, the Explorer page is displayed, where you can view databases, supertables, subtables, and run SQL queries.

On the Programming page, you can view client library examples for various programming languages, all of which can be executed directly via copy/paste.

The Tools page lists visualization tools that integrate with TDengine such as Grafana and Power BI. You can follow the on-screen guidance to create dashboards and reports easily.

Click the ? icon in the upper-right corner of the interface to access the TDengine documentation. This is installed locally and does not require an internet connection.

Integration with Grafana​

Grafana is a popular open-source platform for data visualization and monitoring. TDengine integrates seamlessly with Grafana to create dashboards and alert systems, all without writing a single line of code. The example below uses smart meter data generated by taosBenchmark to create a panel that displays current fluctuations.

Prerequisites​

  • Install and start Grafana (version 7.5 or above is supported).

  • Insert test data using the following command, which creates a supertable meters in the test database with 100 subtables, each containing 1,000 records starting from one hour ago:

    taosBenchmark --start-timestamp=$(date --date="1 hours ago" +%s%3N) \
      --time-step=1000 --records=1000 \
      --tables=100 --answer-yes

Install the Grafana Plugin​

Communication between Grafana and TDengine is handled via the TDengine Datasource plugin.

On Linux, you can install the plugin by running the following command:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/taosdata/grafanaplugin/master/install.sh)"

For other platforms, refer to the plugin installation guide.

After installation, restart the Grafana service:

sudo systemctl restart grafana-server.service

Create a Connection​

In Grafana, go to Connections > Add new connection, search for TDengine, and click Add new data source.

Configure the data source as follows:

  • TDengine Host: Enter the address and port of your taosAdapter. For local setups, use http://localhost:6041.
  • TDengine Authentication: Use the database’s username and password authentication (default: root/taosdata).

Click Save & test. If you see the message TDengine Data source is working, the connection is successful.

Create a Dashboard​

Select Dashboards > New and click Add a new panel. Choose the TDengine data source that you configured earlier.

In the Input SQL field, enter the following query and click Apply. This displays the average variation of the current column:

SELECT _wstart AS ts, avg(voltage) AS voltage, avg(phase) AS phase FROM test.meters
WHERE groupid =1 and ts > $from AND ts < $to interval($interval) fill(null)

For more details, see Grafana.

Zero-Code Data Ingestion​

TDengine TSDB can ingest data from various sources, including PI System, OPC, InfluxDB, MQTT, Kafka, CSV, MySQL, PostgreSQL, Oracle, and MongoDB.

The following example shows how to create an MQTT data ingestion task to subscribe to data from an MQTT broker and write it into TDengine.

Configure Basic Task Information​

  1. In a web browser, access TDengine TSDB Explorer.

  2. From the main menu on the left, select Data In.

  3. On the Data In Task tab, click + Add Source to open the task configuration page.

  4. Configure the MQTT task as follows:

    • Name: Enter a unique name for the data ingestion task.
    • Type: Select MQTT.
    • Agent: Leave this field blank.
    • Target: Click + Create Database, enter test-mqtt as the name, and click Create.

  5. Configure the connection and authentication:

    • MQTT Host: broker.emqx.io
    • Port: 1883
    • TLS Verification: Disable
    • Username/Password: Leave these fields blank.

  6. Configure MQTT protocol settings:

    • MQTT Protocol Version: 3.1
    • Client ID: Enter a unique ID for the data ingestion task.
    • Topics QoS Config: Must be separated by two colons, e.g. tdengine-topic1::0
    • Retain the default value for all other settings.

  7. Click Check Connectivity. If the message Your data source is reachable appears, the connection is successful.

  8. Configure payload transformation:

    1. Enter the following JSON sample representing smart meter readings (voltage, current, and phase) for meter ID 1 in Beijing:
    { "id": 1, "current": 10.42, "phase": 1.38, "voltage":200, "groupid": 7, "location": "beijing" }

    1. Click the Preview icon on the right to preview parsing results.

    2. Under Mapping, create a supertable with the following schema:

      Columns:

      Data TypeName
      TIMESTAMPts
      INTid
      DOUBLEcurrent
      DOUBLEphase
      INTvoltage

      Tags:

      Data TypeName
      INTgroupid
      VARCHAR(128)location

      After creating and selecting the supertable, click Submit.

  9. Your task is now displayed in the Data In Task list. When its status changes to Running, data from the MQTT topic will be consumed and written into TDengine TSDB automatically.

Send Test Data​

You can use the MQTT client tool MQTTX to send test data. For more information, see the documentation.

Use the same broker and topic configuration as your MQTT task:

  • Broker Address: broker.emqx.io

  • Port: 1883

  • Topic: tdengine-topic1

  • Sample Data:

    { "id": 1, "current": 10.42, "phase": 1.38, "voltage":200, "groupid": 7, "location": "beijing" }

Verify Data​

After sending test data, you can check whether it has been successfully written to TDengine TSDB. In TDengine TSDB Explorer, run the following SQL statement:

SELECT * FROM `test-mqtt`.`meters`;

If data is returned, it confirms successful ingestion.

You can also view the task’s running status, ingestion rate, and error logs on the Data In page.

What to Do Next​

After completing this quick start, you can continue exploring TDengine’s advanced capabilities and features.