Node.js Client Library

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

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

Connection Method

The Node.js connector currently only supports WebSocket connections, which connect to TDengine instances through the WebSocket interface provided by taosAdapter.

For a detailed introduction to connection methods, please refer to: Connection Methods

Supported Platforms

Supports Node.js version 14 and above.

Version History

Node.js Connector Version	Major Changes	TDengine Version
3.1.0	New version released, supports WebSocket connection	3.2.0.0 and higher

Error Handling

After calling the connector API and encountering an error, you can retrieve the error information and error code using try-catch.

Error Description: Node.js connector error codes range from 100 to 110; any other errors correspond to errors from other TDengine functional modules.

For specific connector error codes, please refer to:

Error Code	Description	Suggested Actions
100	invalid variables	Invalid parameters, please check the respective interface specifications and adjust the parameter types and sizes.
101	invalid url	Invalid URL, please check if the URL is correct.
102	received server data but did not find a callback for processing	Received data from the server but did not find an upper callback for processing.
103	invalid message type	The received message type is unrecognized, please check if the server is functioning normally.
104	connection creation failed	Connection creation failed, please check if the network is functioning normally.
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 types supported by TDengine.
108	connection has been closed	The connection has been closed, please check if the connection is closed before trying to use it again, or if the connection is functioning normally.
109	fetch block data parse fail	Failed to parse the fetched query data.
110	websocket connection has reached its maximum limit	WebSocket connection limit reached.

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

Data Type Mapping

The following table maps TDengine DataType to 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	Example Program Description
sql_example	Basic usage such as establishing connections, executing SQL, etc.
stmt_example	Example of binding parameters for insertion.
line_example	Example of line protocol insertion.
tmq_example	Example of subscription usage.
all_type_query	Example supporting all types.
all_type_stmt	Example supporting all types for parameter binding.

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; taosAdapter needs to be started in advance.
• After using the connector, you need to call taos.connectorDestroy(); to release connector resources.

API Reference

The Node.js connector (@tdengine/websocket) connects to TDengine instances 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: Database username and password.

• 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 connections through the specified URL, you can also use WSConfig to specify parameters for establishing connections.

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 configuration in WSConfig is as follows:

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

Connection Features

• static async open(wsConfig: WSConfig): Promise<WsSql>

  • Interface Description: Establishes a taosAdapter connection.
  • Parameter Description:
    • wsConfig: Connection configuration, as detailed in the WSConfig section above.
  • Return Value: Connection object.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• destroyed()

  • Interface Description: Releases and destroys resources.
  • Exception: Throws TDWebSocketClientError if the connection fails.

Get taosc Version

• async version(): Promise<string>
  • Interface Description: Gets the taosc client version.
  • Return Value: taosc client version number.
  • Exception: Throws TDWebSocketClientError if the connection fails.

Execute SQL

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

  • Interface Description: Executes 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 affected rows
        timing: number,       // Execution duration
        totalTime: number,    // Total response time
    }    

  • Exception: Throws TDWebSocketClientError if the connection fails.

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

  • Interface Description: Queries data.
  • Parameter Description:
    • sql: The SQL statement to be executed.
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: WSRows dataset object.
  • Exception: Throws TDWebSocketClientError if the connection fails.

Dataset

• getMeta(): Array<TDengineMeta> | null

  • Interface Description: Gets the number, type, and length of the query result's columns.

  • 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 from the current position to the next row. Used to iterate through 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 if the connection fails.

• getData(): Array<any>

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

• async close(): Promise<void>

  • Interface Description: Releases the result set after data reading is complete.
  • Exception: Throws TDWebSocketClientError if the connection fails.

Schemaless Insertion

• async schemalessInsert(lines: Array<string>, protocol: SchemalessProto, precision: Precision, ttl: number, reqId?: number): Promise<void>
  • Interface Description: Performs schemaless insertion.
  • Parameter Description:
    • lines: Array of data to be written; for specific data formats for schemaless writing, 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: Hour
      • Precision.MINUTES: Minute
      • Precision.SECONDS: Second
      • Precision.MILLI_SECONDS: Millisecond
      • Precision.MICRO_SECONDS: Microsecond
      • Precision.NANO_SECONDS: Nanosecond
    • ttl: Table expiration time, in days.
    • reqId: Used for issue tracking, optional.
  • Exception: Throws TaosResultError if the connection fails.

Parameter Binding

• async stmtInit(reqId?: number): Promise<WsStmt>

  • Interface Description: Creates a stmt object using the WsSql object.
  • Parameter Description:
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: stmt object.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• async prepare(sql: string): Promise<void>

  • Interface Description: Binds a precompiled SQL statement.
  • Parameter Description:
    • sql: Precompiled SQL statement.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• async setTableName(tableName: string): Promise<void>

  • Interface Description: Sets the name of the table where data will be written.
  • Parameter Description:
    • tableName: The table name; if you need to specify the database, use db_name.table_name.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• To set the bound data, use the following interfaces, which are similar to setBoolean except for the value types:

  • setBoolean(params: any[])
  • 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: Sets the table tags data for automatic table creation.
  • Parameter Description:
    • paramsArray: Tags data.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• async bind(paramsArray: StmtBindParams): Promise<void>

  • Interface Description: Binds data.
  • Parameter Description:
    • paramsArray: Data to be bound.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• async batch(): Promise<void>

  • Interface Description: Submits bound data.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• async exec(): Promise<void>

  • Interface Description: Executes all the bound data for writing.
  • Exception: Throws TDWebSocketClientError if the connection fails.

• getLastAffected()

  • Interface Description: Gets the number of rows written.
  • Return Value: Number of rows written.

• async close(): Promise<void>

  • Interface Description: Closes the stmt object.
  • Exception: Throws TDWebSocketClientError if the connection fails.

Data Subscription

• Supported Attributes for Creating a Consumer:

  • taos.TMQConstants.CONNECT_USER: Username.
  • taos.TMQConstants.CONNECT_PASS: Password.
  • taos.TMQConstants.GROUP_ID: The group the consumer belongs to.
  • taos.TMQConstants.CLIENT_ID: Client ID.
  • taos.TMQConstants.WS_URL: URL address of the 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 allow automatic commits.
  • taos.TMQConstants.AUTO_COMMIT_INTERVAL_MS: Interval for automatic commits.
  • taos.TMQConstants.CONNECT_MESSAGE_TIMEOUT: Data transmission 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 attribute configuration for creation.
  • Return Value: WsConsumer consumer object.
  • Exception: Throws TDWebSocketClientError if an exception occurs during execution.

• async subscribe(topics: Array<string>, reqId?: number): Promise<void>

  • Interface Description: Subscribes to a group of topics.
  • Parameter Description:
    • topics: List of topics to subscribe to.
    • reqId: Request ID (optional), used for issue tracking.
  • Exception: Throws TDWebSocketClientError if the operation fails.

• async unsubscribe(reqId?: number): Promise<void>

  • Interface Description: Unsubscribes.
  • Parameter Description:
    • reqId: Request ID (optional), used for issue tracking.
  • Exception: Throws TDWebSocketClientError if the operation fails.

• async poll(timeoutMs: number, reqId?: number): Promise<Map<string, TaosResult>>

  • Interface Description: Polls for messages.
  • Parameter Description:
    • timeoutMs: The timeout for polling, in milliseconds.
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: Map<string, TaosResult> corresponding data for each topic.
  • Exception: Throws TDWebSocketClientError if the operation fails.

• async subscription(reqId?: number): Promise<Array<string>>

  • Interface Description: Gets all currently subscribed topics.
  • Parameter Description:
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: Array<string> list of topics.
  • Exception: Throws TDWebSocketClientError if the operation fails.

• async commit(reqId?: number): Promise<Array<TopicPartition>>

  • Interface Description: Commits the offset of the currently processed message.
  • Parameter Description:
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: Array<TopicPartition> consumption progress for each topic.
  • Exception: Throws TDWebSocketClientError if the operation fails.

• async committed(partitions: Array<TopicPartition>, reqId?: number): Promise<Array<TopicPartition>>

  • Interface Description: Gets the last committed offset for a set of partitions.
  • Parameter Description:
    • partitions: A parameter of type Array<TopicPartition>, representing the set of partitions to query.
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: Array<TopicPartition>, the last committed offset for the set of partitions.
  • Exception: Throws TDWebSocketClientError if an error occurs while fetching the committed offsets.

• async seek(partition: TopicPartition, reqId?: number): Promise<void>

  • Interface Description: Sets the offset for the given partition to a specified position.
  • Parameter Description:
    • partition: A parameter of type TopicPartition, representing the partition to operate on and the offset to set.
    • reqId: Request ID (optional), used for issue tracking.
  • Exception: Throws TDWebSocketClientError if an error occurs while setting the offset.

• async positions(partitions: Array<TopicPartition>, reqId?: number): Promise<Array<TopicPartition>>

  • Interface Description: Gets the current offset for a given partition.
  • Parameter Description:
    • partitions: A parameter of type Array<TopicPartition>, representing the partitions to query.
    • reqId: Request ID (optional), used for issue tracking.
  • Return Value: Array<TopicPartition>, the last committed offset for the set of partitions.
  • Exception: Throws TDWebSocketClientError if an error occurs while fetching the offsets.

• async seekToBeginning(partitions: Array<TopicPartition>): Promise<void>

  • Interface Description: Sets the offset for a set of partitions to the earliest offset.
  • Parameter Description:
    • partitions: A parameter of type Array<TopicPartition>, representing the set of partitions to operate on.
  • Exception: Throws TDWebSocketClientError if an error occurs while setting the offset.

• async seekToEnd(partitions: Array<TopicPartition>): Promise<void>

  • Interface Description: Sets the offset for a set of partitions to the latest offset.
  • Parameter Description:
    • partitions: A parameter of type Array<TopicPartition>, representing the set of partitions to operate on.
  • Exception: Throws TDWebSocketClientError if an error occurs while setting the offset.

• async assignment(topics?: string[]): Promise<Array<TopicPartition>>

  • Interface Description: Gets the currently assigned partitions for the consumer, either for specified partitions or all.
  • Parameter Description:
    • topics: Specifies the partitions to retrieve (optional); if not filled, retrieves all partitions.
  • Return Value: Returns an Array<TopicPartition>, representing all currently assigned partitions for the consumer.
  • Exception: Throws TDWebSocketClientError if an error occurs while fetching the assigned partitions.

• async close(): Promise<void>

  • Interface Description: Closes the TMQ connection.
  • Exception: Throws TDWebSocketClientError if the operation fails.