docs/en/14-reference/03-taos-sql/94-datain.md
This document introduces SQL commands for managing the data synchronization functionality of TDengine, including Xnode nodes, synchronization tasks, Job shards, and Agent nodes.
Xnodes are the basic execution units of the data synchronization service, responsible for specific data transmission tasks.
CREATE XNODE 'url'
CREATE XNODE 'url' USER name PASS 'password'
CREATE XNODE 'url' TOKEN 'token'
host:port with port to taosx GRPC service (6055 by default)taos> CREATE XNODE "h1:6055";
Create OK, 0 row(s) affected (0.050798s)
taos> CREATE XNODE 'x1:6055' USER root PASS 'taosdata';
Create OK, 0 row(s) affected (0.050798s)
taos> CREATE XNODE 'x2:6055' TOKEN 'C8V3o0ZVvYQ6sMEnjfixjtw0OvN9nIPFAL1HWvSKmHbQsds8vBpVbrEZn2hrzar';
Create OK, 0 row(s) affected (0.050798s)
Modifying authentication will restart the daemon xnoded. This command alters the credentials used by the single xnoded daemon to connect to taosd.
ALTER XNODE SET USER name PASS 'password'
ALTER XNODE SET TOKEN 'token'
taos> ALTER XNODE SET TOKEN 'C8V3o0ZVvYQ6sMEnjfixjtw0OvN9nIPFAL1HWvSKmHbQsds8vBpVbrEZn2hrzar';
Query OK, 0 row(s) affected (0.024293s)
taos> ALTER XNODE SET USER root PASS 'taosdata';
Query OK, 0 row(s) affected (0.025161s)
SHOW XNODES [WHERE condition]
taos> SHOW XNODES;
Output result:
id | url | status | create_time | update_time |
===============================================================================
1 | h1:6050 | online | 2025-12-14 01:01:34.655 | 2025-12-14 01:01:34.655 |
Query OK, 1 row(s) in set (0.005518s)
Reassign existing tasks of a node to other nodes for execution.
DRAIN XNODE id
taos> DRAIN XNODE 4;
Query OK, 0 row(s) affected (0.014246s)
DROP XNODE [FORCE] id | 'url'
taos> DROP XNODE 1;
Drop OK, 0 row(s) affected (0.038173s)
taos> DROP XNODE "h2:6050";
Drop OK, 0 row(s) affected (0.038593s)
Tasks define the source, destination, and data parsing rules for data synchronization.
CREATE XNODE TASK 'name'
FROM { 'from_dns' | DATABASE 'dbname' | TOPIC 'topic' }
TO { 'to_dns' | DATABASE 'dbname' }
[ WITH task_options ]
task_options:
[ PARSER 'parser' ]
[ STATUS 'status' ]
[ VIA viaId ]
[ XNODE_ID xnodeId ]
[ REASON 'reason' ]
[ LABELS 'labels' ]
Syntax note: All task_options can be used simultaneously, separated by spaces, order independent
| Parameter | Description |
|---|---|
| name | Task name |
| from_dns | Source connection string (e.g., mqtt://...) |
| dbname | Database name |
| topic | Topic name |
| to_dns | Destination connection string (e.g., taos://...) |
| parser | Data parsing configuration (JSON format) |
| status | Task status |
| xnodeId | The xnode node ID where the task resides |
| viaId | The agent ID where the task resides |
| reason | Reason for recent task execution failure |
| labels | Task labels, stored as a JSON string |
taos> CREATE XNODE TASK "t4" FROM 'kafka://localhost:9092?topics=abc&group=abcgroup' TO 'taos+ws://localhost:6041/test' WITH parser '{"model":{"name":"cc_abc","using":"cc","tags":["g"],"columns":["ts","b"]},"mutate":[{"map":{"ts":{"cast":"ts","as":"TIMESTAMP(ms)"},"b":{"cast":"a","as":"VARCHAR"},"g":{"value":"1","as":"INT"}}}]}';
Create OK, 0 row(s) affected (0.038959s)
SHOW XNODE TASKS [WHERE condition]
taos> SHOW XNODE TASKS;
Output result:
taos> SHOW XNODE TASKS \G;
*************************** 1.row ***************************
id: 3
name: t4
from: kafka://localhost:9092?topics=abc&group=abcgroup
to: taos+ws://localhost:6041/test
parser: {"model":{"name":"cc_abc","using":"cc","tags":["g"],"columns":["ts","b"]},"mutate":[{"map":{"ts":{"cast":"ts","as":"TIMESTAMP(ms)"},"b":{"cast":"a","as":"VARCHAR"},"g":{"value":"1","as":"INT"}}}]}
via: NULL
xnode_id: NULL
status: NULL
reason: NULL
created_by: root
labels: NULL
create_time: 2026-01-13 07:56:18.076
update_time: 2026-01-13 07:56:18.076
Query OK, 2 row(s) in set (0.019692s)
START XNODE TASK id | 'name'
taos> START XNODE TASK 1;
DB error: Xnode url response http code not 200 error [0x8000800C] (0.002160s)
STOP XNODE TASK id | 'name'
taos> STOP XNODE TASK 1;
DB error: Xnode url response http code not 200 error [0x8000800C] (0.002047s)
ALTER XNODE TASK { id | 'name' }
[ FROM { 'from_dns' | DATABASE 'dbname' | TOPIC 'topic' } ]
[ TO { 'to_dns' | DATABASE 'dbname' } ]
[ WITH alter_options ]
alter_options:
[ PARSER 'parser' ]
[ NAME 'name' ]
[ STATUS 'status' ]
[ VIA viaId ]
[ XNODE_ID xnodeId ]
[ REASON 'reason' ]
[ LABELS 'labels' ]
Syntax note: The meaning of task_options is the same as when creating a task
taos> ALTER XNODE TASK 3 FROM 'pulsar://zgc...' TO 'testdb' WITH xnode_id 33 via 333 reason 'zgc_test';
Query OK, 0 row(s) affected (0.036077s)
DROP XNODE TASK id | 'name'
taos> DROP XNODE TASK 3;
Drop OK, 0 row(s) affected (0.038191s)
Job is the execution shard of a Task, supporting both manual and automatic load balancing.
SHOW XNODE JOBS [WHERE condition]
taos> SHOW XNODE JOBS\G;
*************************** 1.row ***************************
id: 1
task_id: 3
config: config_json
via: -1
xnode_id: 11
status: running
reason: NULL
create_time: 2025-12-14 02:52:31.281
update_time: 2025-12-14 02:52:31.281
Query OK, 1 row(s) in set (0.004714s)
REBALANCE XNODE JOB jid WITH XNODE_ID xnodeId;
Syntax note: Manual rebalance currently only supports the xnode_id parameter, which must include xnode id information.
taos> REBALANCE XNODE JOB 1 WITH xnode_id 1;
Query OK, 0 row(s) affected (0.011808s)
REBALANCE XNODE JOBS [ WHERE job_conditions ]
Syntax note: WHERE job_conditions is optional, used to filter job data that meets the conditions. Functions are not supported, all fields that appear in the SHOW XNODE JOBS command are supported. Without a WHERE condition statement, it means all jobs will undergo automatic load balancing.
taos> REBALANCE XNODE JOBS WHERE id>1;
Query OK, 0 row(s) affected (0.014246s)
taos> REBALANCE XNODE JOBS WHERE task_id=1 and (xnode_id=3 or xnode_id=4);
Query OK, 0 row(s) affected (0.007237s)
taos> REBALANCE XNODE JOBS;
Query OK, 0 row(s) affected (0.023245s)
The Agent node serves as the data collection and forwarding unit in the data synchronization service, responsible for collecting data and forwarding it to Xnode nodes.
CREATE XNODE AGENT 'name' [WITH agent_options]
agent_options:
[STATUS 'status']
WITHclausetaos> create xnode agent 'a1';
Create OK, 0 row(s) affected (0.013910s)
taos> create xnode agent 'a2' with status 'running';
Create OK, 0 row(s) affected (0.013414s)
SHOW XNODE AGENTS [WHERE condition]
taos> show xnode agents\G;
*************************** 1.row ***************************
id: 1
name: a1
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjgxODI3MDEzNjQsInN1YiI6MX0.FP5rfzQplBrJrbV7Dj_R8fCpiN5uLaADegcnqExwepg
status: NULL
create_time: 2026-01-12 09:51:41.364
update_time: 2026-01-12 09:51:41.364
ALTER XNODE AGENT agent_id WITH alter_options
alter_options {
STATUS 'status'
| NAME 'name'
}
WITHclausetaos> alter xnode agent 1 with name 'test1';
Query OK, 0 row(s) affected (0.008387s)
taos> alter xnode agent 'a2' with name 'test2' status 'online';
Query OK, 0 row(s) affected (0.008685s)
DROP XNODE AGENT agent_id
taos> drop xnode agent 1;
Drop OK, 0 row(s) affected (0.012281s)