https://github.com/taosdata/node-red-node-tdengine
https://github.com/taosdata/node-red-node-tdengine
node-red
Last synced: 6 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/taosdata/node-red-node-tdengine
- Owner: taosdata
- Created: 2025-05-29T01:56:09.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-06-14T08:25:05.000Z (7 months ago)
- Last Synced: 2025-06-14T08:33:31.076Z (7 months ago)
- Topics: node-red
- Homepage:
- Size: 108 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TDengine Integration with Node-RED
- [TDengine Integration with Node-RED](#tdengine-integration-with-node-red)
- [Overview](#overview)
- [Features](#features)
- [tdengine-operator](#tdengine-operator)
- [tdengine-consumer](#tdengine-consumer)
- [Prerequisites](#prerequisites)
- [Configure Data Source](#configure-data-source)
- [Installation](#installation)
- [Node Status](#node-status)
- [Input Format](#input-format)
- [tdengine-operator](#tdengine-operator-1)
- [tdengine-consumer](#tdengine-consumer-1)
- [Output Format](#output-format)
- [tdengine-operator](#tdengine-operator-2)
- [tdengine-consumer](#tdengine-consumer-2)
- [Quick Start](#quick-start)
- [Input](#input)
- [Output](#output)
- [Documents](#documents)
- [Resources](#resources)
## Overview
[Node-RED](https://nodered.org/) is an open-source visual programming tool developed by IBM based on Node.js. It enables users to assemble and connect various nodes via a graphical interface to create connections for IoT devices, APIs, and online services. Supporting multi-protocol and cross-platform capabilities, it has an active community and is ideal for event-driven application development in smart home, industrial automation, and other scenarios, with its main strengths being low-code and visual programming.
The deep integration between TDengine and Node-RED provides a comprehensive solution for industrial IoT scenarios. Through Node-RED's MQTT/OPC UA/Modbus protocol nodes, data from PLCs, sensors and other devices can be collected at millisecond-level speed. Real-time queries of TDengine can trigger physical control actions like relay operations and valve switching for immediate command execution.
node-red-node-tdengine is the official plugin developed by TDengine for Node-RED. Composed of two nodes:
- **tdengine-operator**: Provides SQL execution capabilities for data writing/querying and metadata management.
- **tdengine-consumer**: Offers data subscription and consumption capabilities from specified subscription servers and topics.
## Features
### tdengine-operator
- Supports TDengine local deployment or cloud service data sources.
- Full coverage of all TDengine SQL operations (SELECT/INSERT/CREATE/ALTER/SHOW, etc.).
- Unified interface for handling both read and write operations using `msg.topic` to pass SQL statements.
### tdengine-consumer
- Support TDengine local deployment or cloud service data sources.
- Flexible configuration of subscription properties.
- Support subscribing to multiple topics simultaneously.
- Automatically submit and save consumption progress.
- Automatically reconnect after server disconnection.
## Prerequisites
Prepare the following environment:
- TDengine >= 3.3.2.0 (Enterprise/Community/Cloud Edition are available).
- taosAdapter is running, refer to [taosAdapter](https://docs.tdengine.com/tdengine-reference/components/taosadapter/).
- Node-RED >= 3.0.0, [Node-RED installation](https://nodered.org/docs/getting-started/).
- Node.js Connector for TDengine >= 3.1.8, get from [npmjs.com](https://www.npmjs.com/package/@tdengine/websocket).
## Configure Data Source
TDengine WebSocket connection string format:
- tdengine-operator: `ws://user:password@host:port`
- tdengine-consumer: `ws://host:port`
See detail [here](https://docs.tdengine.com/tdengine-reference/client-libraries/node/#url-specification).
## Installation
Run the following command in your Node-RED user directory - typically ~/.node-red .
``` bash
npm i node-red-node-tdengine
```
## Node Status
- Grey: Connecting.
- Green: Operational.
- Red: Malfunction.
## Input Format
### tdengine-operator
Pass SQL statement via topic:
``` javascript
msg = { topic: "SQL statement" }
```
Special characters and escape sequences in SQL must follow JSON string specifications.
### tdengine-consumer
Input node (no input).
## Output Format
### tdengine-operator
- Write Operations
The payload contains write results, and the topic passes through the SQL statement:
``` javascript
msg = {
topic: "insert into ...",
isQuery: false, // true for query operations
payload: {
affectRows: 2, // affect rows
totalTime: 3, // Total write time (ms)
timing: 1683311 // Server-side execution time (ns)
}
}
```
- Query Operations
payload contains query results, topic passes through SQL:
``` javascript
{
topic: "select * from ...",
isQuery: true, // true for query operations
payload: [
{ ts: 1749609744000, current: 20, voltage: 200, phase: 5 },
{ ts: 1749609200001, current: 31, voltage: 210, phase: 4 },
...
]}
```
Query results are row data objects where properties correspond to column names. For data type mappings:
[TDengine NodeJS Connector Type Mapping](https://docs.tdengine.com/tdengine-reference/client-libraries/node/#data-type-mapping).
### tdengine-consumer
payload outputs array of objects where properties correspond to column names:
[TDengine NodeJS Connector Type Mapping](https://docs.tdengine.com/tdengine-reference/client-libraries/node/#data-type-mapping).
``` javascript
{
topic: Subscription topic,
database: Database name,
vgroup_id: Data partition,
precision: Database precision
payload: [{
column_name1: value1,
column_name2: value2,
...
},
...
],
}
```
## Quick Start
### Input
``` javascript
// Example: Inserting data
msg.topic = "insert into test.d0 values ('2025-06-10 10:00:02.001', 23.5, 220, 3)";
return msg;
// Example: Querying data
msg.topic = "select * from test.d0";
return msg;
```
### Output
- Insert Result
``` json
{
"topic": "insert into test.d0 values ('2025-06-10 10:00:02.001', 23.5, 220, 3)",
"_msgid": "8f50fe84338387d7",
"isQuery": false,
"payload":{
"affectRows": 1,
"totalTime": 2,
"timing": "961982"
}
}
```
- Query Result
``` json
{
"topic": "select * from test.d0",
"_msgid": "0d19e9b82ae3841a",
"isQuery": true,
"payload": [
{ "ts": 1749609744000, "current": 10, "voltage": 219, "phase": 0.32 },
{ "ts": 1749609200001, "current": 31, "voltage": 210, "phase": 4 }
]
}
```
- Subscribe Result
``` json
{
"topic": "topic_overload",
"payload": [
{
"tbname": "d1",
"ts": "1750140456777",
"current": 31,
"voltage": 217,
"phase": 2,
"groupid": 4,
"location": "California.MountainView"
}
],
"database": "test",
"vgroup_id": 4,
"precision": 0
}
```
## Documents
- Full documentation is available in Node-RED's in-editor help system (click the book icon).
- [Introduce usage scenarios with Node-RED Plugin for TDengine](https://docs.tdengine.com/third-party/collection/Node-RED/).
## Resources
- [TDengine Official Website](http://www.tdengine.com).
- [Node.js Connector for TDengine](https://docs.tdengine.com/tdengine-reference/client-libraries/node/).