Creates an instance of Sender.
Sender configuration object.
See SenderOptions documentation for detailed description of configuration options.
StaticfromCreates a Sender object by parsing the provided configuration string.
Configuration string.
OptionalextraOptions: ExtraOptionsOptional extra configuration.
A Sender object initialized from the provided configuration string.
StaticfromCreates a Sender object by parsing the configuration string set in the QDB_CLIENT_CONF environment variable.
OptionalextraOptions: ExtraOptionsOptional extra configuration.
A Sender object initialized from the QDB_CLIENT_CONF environment variable.
Resets the sender's buffer, data sitting in the buffer will be lost.
In other words it clears the buffer, and sets the writing position to the beginning of the buffer.
Returns with a reference to this sender.
Creates a TCP connection to the database.
Resolves to true if the client is connected.
Sends the content of the sender's buffer to the database and compacts the buffer. If the last row is not finished it stays in the sender's buffer.
Resolves to true when there was data in the buffer to send, and it was sent successfully.
Closes the connection to the database.
Data sitting in the Sender's buffer will be lost unless flush() is called before close().
Writes the table name into the buffer of the sender of the sender.
Table name.
Returns with a reference to this sender.
Writes a symbol name and value into the buffer of the sender.
Use it to insert into SYMBOL columns.
Symbol name.
Symbol value, toString() is called to extract the actual symbol value from the parameter.
Returns with a reference to this sender.
Writes a string column with its value into the buffer of the sender.
Use it to insert into VARCHAR and STRING columns.
Column name.
Column value, accepts only string values.
Returns with a reference to this sender.
Writes a boolean column with its value into the buffer of the sender.
Use it to insert into BOOLEAN columns.
Column name.
Column value, accepts only boolean values.
Returns with a reference to this sender.
Writes a 64-bit floating point value into the buffer of the sender.
Use it to insert into DOUBLE or FLOAT database columns.
Column name.
Column value, accepts only number values.
Returns with a reference to this sender.
Writes an array column with its values into the buffer of the sender.
Column name
Array values to write (currently supports double arrays)
Returns with a reference to this sender.
Writes a 64-bit signed integer into the buffer of the sender.
Use it to insert into LONG, INT, SHORT and BYTE columns.
Column name.
Column value, accepts only number values.
Returns with a reference to this sender.
Writes a timestamp column with its value into the buffer of the sender.
Use it to insert into TIMESTAMP columns.
Column name.
Epoch timestamp, accepts numbers or BigInts.
Optionalunit: TimestampUnit = "us"Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
Returns with a reference to this sender.
Closes the row after writing the designated timestamp into the buffer of the sender.
Designated epoch timestamp, accepts numbers or BigInts.
Optionalunit: TimestampUnit = "us"Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
Closes the row without writing designated timestamp into the buffer of the sender.
Designated timestamp will be populated by the server on this record.
The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection.
The client supports multiple transport protocols.
Transport Options:
The client supports authentication.
Authentication details can be passed to the Sender in its configuration options.
The client supports Basic username/password and Bearer token authentication methods when used with HTTP protocol, and JWK token authentication when ingesting data via TCP.
Please, note that authentication is enabled by default in QuestDB Enterprise only.
Details on how to configure authentication in the open source version of QuestDB: https://questdb.io/docs/reference/api/ilp/authenticate
The client also supports TLS encryption for both, HTTP and TCP transports to provide a secure connection.
Please, note that the open source version of QuestDB does not support TLS, and requires an external reverse-proxy, such as Nginx to enable encryption.
The client supports multiple protocol versions for data serialization. Protocol version 1 uses text-based serialization, while version 2 uses binary encoding for doubles and supports array columns for improved performance. The client can automatically negotiate the protocol version with the server when using HTTP/HTTPS by setting the protocol_version to 'auto' (default behavior).
The client uses a buffer to store data. It automatically flushes the buffer by sending its content to the server. Auto flushing can be disabled via configuration options to gain control over transactions. Initial and maximum buffer sizes can also be set.
It is recommended that the Sender is created by using one of the static factory methods, Sender.fromConfig(configString, extraOptions) or Sender.fromEnv(extraOptions). If the Sender is created via its constructor, at least the SenderOptions configuration object should be initialized from a configuration string to make sure that the parameters are validated.
Detailed description of the Sender's configuration options can be found in the SenderOptions documentation.
Transport Configuration Examples:
HTTP Transport Implementation:
By default, HTTP/HTTPS transport uses the high-performance Undici library for connection management and request handling. For compatibility or specific requirements, you can enable the standard HTTP transport using Node.js built-in modules by setting stdlib_http=on in the configuration string. The standard HTTP transport provides the same functionality but uses Node.js http/https modules instead of Undici.
Extra options can be provided to the Sender in the extraOptions configuration object.
A custom logging function and a custom HTTP(S) agent can be passed to the Sender in this object.
The logger implementation provides the option to direct log messages to the same place where the host application's log is saved. The default logger writes to the console.
The custom HTTP(S) agent option becomes handy if there is a need to modify the default options set for the HTTP(S) connections. A popular setting would be disabling persistent connections, in this case an agent can be passed to the Sender with keepAlive set to false.
For example: Sender.fromConfig(`http::addr=host:port`, { agent: new undici.Agent({ connect: { keepAlive: false } })})
If no custom agent is configured, the Sender will use its own agent which overrides some default values of undici.Agent. The Sender's own agent uses persistent connections with 1 minute idle timeout, pipelines requests default to 1.