Node.js Client Library

@tdengine/websocket is the official Node.js language connector for TDengine. Node.js developers can use it to develop applications that access the TDengine database.

The source code for the Node.js connector is hosted on GitHub.

Node.js Version Compatibility

Supports Node.js 14 and above.

Supported Platforms

Support all platforms that can run Node.js.

Version History

Node.js Connector Version	Major Changes	TDengine Version
3.1.2	Optimized data protocol and parsing, significantly improved performance.	-
3.1.1	Optimized data transmission performance.	3.3.2.0 and higher versions
3.1.0	New release, supports WebSocket connection.	3.2.0.0 and higher versions

Exception Handling

After an error occurs when calling the connector API, the error information and error code can be obtained through try-catch.

Error description: Node.js connector error codes range from 100 to 110, errors outside this range are from other TDengine modules.

For specific connector error codes, please refer to:

Error Code	Description	Suggested Actions
100	invalid variables	The parameters are illegal, please check the corresponding interface specifications and adjust the parameter types and sizes.
101	invalid url	URL error, please check if the URL is correctly filled.
102	received server data but did not find a callback for processing	Received server data but no upper layer callback was found
103	invalid message type	Received message type unrecognized, please check if the server is normal.
104	connection creation failed	Connection creation failed, please check if the network is normal.
105	websocket request timeout	Request timed out
106	authentication fail	Authentication failed, please check if the username and password are correct.
107	unknown sql type in tdengine	Please check the Data Type types supported by TDengine.
108	connection has been closed	The connection has been closed, please check if the Connection is used again after closing, or if the connection is normal.
109	fetch block data parse fail	Failed to parse the fetched query data
110	websocket connection has reached its maximum limit	WebSocket connection has reached its maximum limit

• TDengine Node.js Connector Error Code
• For errors from other TDengine modules, please refer to Error Codes

Data Type Mapping

The table below shows the mapping between TDengine DataType and Node.js DataType

TDengine DataType	Node.js DataType
TIMESTAMP	bigint
TINYINT	number
SMALLINT	number
INT	number
BIGINT	bigint
TINYINT UNSIGNED	number
SMALLINT UNSIGNED	number
INT UNSIGNED	number
BIGINT UNSIGNED	bigint
FLOAT	number
DOUBLE	number
BOOL	boolean
BINARY	string
NCHAR	string
JSON	string
VARBINARY	ArrayBuffer
GEOMETRY	ArrayBuffer

Note: JSON type is only supported in tags.

More Example Programs

Example Program	Description of Example Program
sql_example	Basic usage such as establishing connections, executing SQL, etc.
stmt_example	Example of binding parameters for insertion.
line_example	Line protocol writing example.
tmq_example	Example of using subscriptions.
all_type_query	Example supporting all types.
all_type_stmt	Example of parameter binding supporting all types.

Usage Restrictions

• The Node.js connector (@tdengine/websocket) supports Node.js version 14 and above. Versions below 14 may have package compatibility issues.
• Currently, only WebSocket connections are supported, and taosAdapter needs to be started in advance.
• After using the connector, you need to call taos.connectorDestroy(); to release the connector resources.

Common Issues

1. "Unable to establish connection" or "Unable to resolve FQDN"

   Reason: Generally, it is because the FQDN is not configured correctly.

API Reference

Node.js connector (@tdengine/websocket), which connects to a TDengine instance through the WebSocket interface provided by taosAdapter.

URL Specification

[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]
|------------|---|-----------|-----------|------|------|------------|-----------------------|
|   protocol |   | username  | password  | host | port |  database  |  params               |

• protocol: Use the websocket protocol to establish a connection. For example, ws://localhost:6041

• username/password: Username and password for the database.

• host/port: Host address and port number. For example, localhost:6041

• database: Database name.

• params: Other parameters. For example, token.

• Complete URL example:

    ws://root:taosdata@localhost:6041

WSConfig

In addition to obtaining a connection through a specified URL, you can also use WSConfig to specify parameters when establishing a connection.

try {
    let url = 'ws://127.0.0.1:6041'
    let conf = WsSql.NewConfig(url)
    conf.setUser('root')
    conf.setPwd('taosdata')
    conf.setDb('db')
    conf.setTimeOut(500)
    let wsSql = await WsSql.open(conf);
} catch (e) {
    console.error(e);
}

The configurations in WSConfig are as follows:

• setUrl(url string) Set the taosAdapter connection address url, see the URL specification above.
• setUser(user: string) Set the database username.
• setPwd(pws:string) Set the database password.
• setDb(db: string) Set the database name.
• setTimeOut(ms : number) Set the connection timeout in milliseconds.
• setToken(token: string) Set the taosAdapter authentication token.

Connection Features

• static async open(wsConfig:WSConfig):Promise<WsSql>
  • Interface Description: Establish a taosAdapter connection.
  • Parameter Description:
    • wsConfig: Connection configuration, see the WSConfig section above.
  • Return Value: Connection object.
  • Exception: Connection failure throws TDWebSocketClientError exception.
• destroyed()
  • Interface Description: Release and destroy resources.
  • Exception: Connection failure throws TDWebSocketClientError exception.

Get taosc version number

• async version(): Promise<string>
  • Interface Description: Get the taosc client version.
  • Return Value: taosc client version number.
  • Exception: Connection failure throws TDWebSocketClientError exception.

Execute SQL

• async exec(sql: string, reqId?: number): Promise<TaosResult>

  • Interface Description: Execute an SQL statement.
  • Parameter Description:
    • sql: The SQL statement to be executed.
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Execution result

  TaosResult {
      affectRows: number,   // Number of rows affected
      timing: number,       // Execution duration
      totalTime: number,    // Total response time
  }    
  • Exception: Throws TDWebSocketClientError exception if connection fails.

• async query(sql: string, reqId?:number): Promise<WSRows>

  • Interface Description: Query data.
  • Parameter Description:
    • sql: The SQL query statement to be executed.
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: WSRows data set object.
  • Exception: Throws TDWebSocketClientError exception if connection fails.

Data Set

• getMeta():Array<TDengineMeta> | null

  • Interface Description: Get the number, type, and length of columns in the query result.

  • Return Value: Array of TDengineMeta data objects.

    export interface TDengineMeta {
        name: string,
        type: string,
        length: number,
    }

• async next(): Promise<boolean>

  • Interface Description: Moves the cursor forward one row from the current position. Used to traverse the query result set.
  • Return Value: Returns true if the new current row is valid; returns false if there are no more rows in the result set.
  • Exception: Throws TDWebSocketClientError exception if connection fails.

• getData(): Array<any>

  • Interface Description: Returns one row of queried data.
  • Return Value: Returns one row of queried data; this interface needs to be used together with the next interface.

• async close():Promise<void>

  • Interface Description: After data reading is complete, release the result set.
  • Exception: Throws TDWebSocketClientError exception if connection fails.

Schemaless Writing

• async schemalessInsert(lines: Array<string>, protocol: SchemalessProto, precision: Precision, ttl: number, reqId?: number): Promise<void>
  • Interface Description: Schemaless writing.
  • Parameter Description:
    • lines: Array of data to be written, the specific data format for schemaless can refer to Schemaless Writing.
    • protocol: Protocol type
      • SchemalessProto.InfluxDBLineProtocol: InfluxDB Line Protocol.
      • SchemalessProto.OpenTSDBTelnetLineProtocol: OpenTSDB Text Line Protocol.
      • SchemalessProto.OpenTSDBJsonFormatProtocol: JSON Protocol format.
    • precision: Time precision
      • Precision.HOURS: Hours
      • Precision.MINUTES: Minutes
      • Precision.SECONDS: Seconds
      • Precision.MILLI_SECONDS: Milliseconds
      • Precision.MICRO_SECONDS: Microseconds
      • Precision.NANO_SECONDS: Nanoseconds
    • ttl: Table expiration time, in days.
    • reqId: Optional, used for issue tracking.
  • Exception: Throws TaosResultError exception if connection fails.

Parameter Binding

• async stmtInit(reqId?:number): Promise<WsStmt>
  • Interface Description Create a stmt object using a WsSql object.
  • Parameter Description:
    • reqId: Request id is optional, used for issue tracking.
  • Return Value: stmt object.
  • Exception: Throws TDWebSocketClientError if connection fails.
• async prepare(sql: string): Promise<void>
  • Interface Description Bind a precompiled SQL statement.
  • Parameter Description:
    • sql: Precompiled SQL statement.
  • Exception: Throws TDWebSocketClientError if connection fails.
• async setTableName(tableName: string): Promise<void>
  • Interface Description Set the table name for data to be written to.
  • Parameter Description:
    • tableName: Table name, to specify a database, use: db_name.table_name.
  • Exception: Throws TDWebSocketClientError if connection fails. Set binding data through StmtBindParams object.
• setBoolean(params :any[])
  • Interface Description Set boolean values.
  • Parameter Description:
    • params: List of boolean types.
  • Exception: Throws TDWebSocketClientError if connection fails.
• The following interfaces are similar to setBoolean except for the type of value to be set:
  • setTinyInt(params :any[])
  • setUTinyInt(params :any[])
  • setSmallInt(params :any[])
  • setUSmallInt(params :any[])
  • setInt(params :any[])
  • setUInt(params :any[])
  • setBigint(params :any[])
  • setUBigint(params :any[])
  • setFloat(params :any[])
  • setDouble(params :any[])
  • setVarchar(params :any[])
  • setBinary(params :any[])
  • setNchar(params :any[])
  • setJson(params :any[])
  • setVarBinary(params :any[])
  • setGeometry(params :any[])
  • setTimestamp(params :any[])
• async setTags(paramsArray:StmtBindParams): Promise<void>
  • Interface Description Set table Tags data for automatic table creation.
  • Parameter Description:
    • paramsArray: Tags data.
  • Exception: Throws TDWebSocketClientError if connection fails.
• async bind(paramsArray:StmtBindParams): Promise<void>
  • Interface Description Bind data.
  • Parameter Description:
    • paramsArray: Binding data.
  • Exception: Throws TDWebSocketClientError if connection fails.
• async batch(): Promise<void>
  • Interface Description Submit bound data.
  • Exception: Throws TDWebSocketClientError if connection fails.
• async exec(): Promise<void>
  • Interface Description Execute all bound data to be written.
  • Exception: Throws TDWebSocketClientError if connection fails.
• getLastAffected()
  • Interface Description Get the number of writes.
  • Return Value: Number of writes.
• async close(): Promise<void>
  • Interface Description Close the stmt object.
  • Exception: Throws TDWebSocketClientError if connection fails.

Data Subscription

• List of Supported Properties for Creating Consumers:
  • taos.TMQConstants.CONNECT_USER: Username.
  • taos.TMQConstants.CONNECT_PASS: Password.
  • taos.TMQConstants.GROUP_ID: Group ID.
  • taos.TMQConstants.CLIENT_ID: Client ID.
  • taos.TMQConstants.WS_URL: URL address of taosAdapter.
  • taos.TMQConstants.AUTO_OFFSET_RESET: Determines whether to consume the latest data (latest) or include old data (earliest).
  • taos.TMQConstants.ENABLE_AUTO_COMMIT: Whether to enable auto commit.
  • taos.TMQConstants.AUTO_COMMIT_INTERVAL_MS: Auto commit interval.
  • taos.TMQConstants.CONNECT_MESSAGE_TIMEOUT: Data transfer timeout parameter, in ms, default is 10000 ms.
• static async newConsumer(wsConfig:Map<string, any>):Promise<WsConsumer>
  • Interface Description Consumer constructor.
  • Parameter Description:
    • wsConfig: Consumer property configuration.
  • Return Value: WsConsumer object.
  • Exception: Throws TDWebSocketClientError error if an exception occurs during execution.
• async subscribe(topics: Array<string>, reqId?:number): Promise<void>
  • Interface Description Subscribe to a set of topics.
  • Parameter Description:
    • topics: List of topics to subscribe.
    • reqId: Request ID, optional, used for issue tracking.
  • Exception: Throws TDWebSocketClientError exception on failure.
• async unsubscribe(reqId?:number): Promise<void>
  • Interface Description Unsubscribe.
  • Parameter Description:
    • reqId: Request ID, optional, used for issue tracking.
  • Exception: Throws TDWebSocketClientError exception on failure.
• async poll(timeoutMs: number, reqId?:number):Promise<Map<string, TaosResult>>
  • Interface Description Poll messages.
  • Parameter Description:
    • timeoutMs: Polling timeout in milliseconds.
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Map<string, TaosResult> Data corresponding to each topic.
  • Exception: Throws TDWebSocketClientError exception on failure.
• async subscription(reqId?:number):Promise<Array<string>>
  • Interface Description Get all currently subscribed topics.
  • Parameter Description:
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Array<string> List of topics.
  • Exception: Throws TDWebSocketClientError exception on failure.
• async commit(reqId?:number):Promise<Array<TopicPartition>>
  • Interface Description Commit the offset of the messages currently being processed.
  • Parameter Description:
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Array<TopicPartition> Consumption progress for each topic.
  • Exception: Throws TDWebSocketClientError exception on failure.
• async committed(partitions:Array<TopicPartition>, reqId?:number):Promise<Array<TopicPartition>>
  • Interface Description: Get the last committed offsets for a set of partitions.
  • Parameter Description:
    • partitions: An Array<TopicPartition> parameter, representing the set of partitions to query.
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Array<TopicPartition>, the last committed offsets for a set of partitions.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while retrieving committed offsets.
• async seek(partition:TopicPartition, reqId?:number):Promise<void>
  • Interface Description: Set the offset for a given partition to a specified position.
  • Parameter Description:
    • partition: A TopicPartition parameter, representing the partition and the offset to set.
    • reqId: Request ID, optional, used for issue tracking.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while setting the offset.
• async positions(partitions:Array<TopicPartition>, reqId?:number):Promise<Array<TopicPartition>>
  • Interface Description: Get the current offsets for a given set of partitions.
  • Parameter Description:
    • partitions: An Array<TopicPartition> parameter, representing the partitions to query.
    • reqId: Request ID, optional, used for issue tracking.
  • Return Value: Array<TopicPartition>, the current offsets for a set of partitions.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while retrieving offsets.
• async seekToBeginning(partitions:Array<TopicPartition>):Promise<void>
  • Interface Description: Set the offset for a set of partitions to the earliest offset.
  • Parameter Description:
    • partitions: An Array<TopicPartition> parameter, representing the set of partitions to operate on.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while setting the offset.
• async seekToEnd(partitions:Array<TopicPartition>):Promise<void>
  • Interface Description: Set the offset for a set of partitions to the latest offset.
  • Parameter Description:
    • partitions: An Array<TopicPartition> parameter, representing the set of partitions to operate on.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while setting the offset.
• async assignment(topics?:string[]):Promise<Array<TopicPartition>>
  • Interface Description: Get the currently assigned partitions for the consumer, either specified or all.
  • Parameter Description:
    • topics: Partitions to retrieve (optional), if not specified, retrieves all partitions.
  • Return Value: Array<TopicPartition>, the currently assigned partitions for the consumer.
  • Exception: Throws TDWebSocketClientError exception if an error occurs while retrieving assigned partitions.
• async close():Promise<void>
  • Interface Description: Close the TMQ connection.
  • Exception: Throws TDWebSocketClientError exception on failure.