Creates an instance of Sender.
Sender configuration object.
See SenderOptions documentation for detailed description of configuration options.
Highest cumulative QWP ACK watermark, or -1n when unavailable.
Highest stable QWP frame sequence published, or -1n when unavailable.
Writes an array column with its values into the buffer of the sender.
Column name
Array values to write (currently supports double arrays). A null or undefined value omits the column entirely when arrays are supported; protocol v1 rejects the call for every value.
Returns with a reference to this sender.
Closes the row after writing the designated timestamp.
On ILP, a row is discarded -- its columns and its table selection alike --
only when it can never be closed, which means it carries no symbol and no
column; rows completed earlier remain staged, and the next row starts from
table again. Every other rejection leaves the row open and this
call retryable: an invalid designated timestamp, its unit or its value, is
caught before closing begins, so a corrected argument closes the same row,
and a row that does not fit max_buf_size has its partial close rewound,
so the same call succeeds once a flush() frees space. A rejected column
or symbol call likewise writes nothing. If this call triggers an
auto-flush that fails, ILP transports have already removed the entire
staged batch from the sender buffer. Applications that need to retry ILP
rows must retain and resubmit them. QWP retains successfully closed rows
for its retry and replay path.
Precision rules:
'ns' (nanoseconds) are sent with full nanosecond precision.
All other timestamps are sent with microsecond precision.Designated epoch timestamp. Must be an integer or a BigInt.
Optionalunit: TimestampUnit = "us"The time unit of the timestamp. Supported values:
'ns' — nanoseconds (requires BigInt)'us' — microseconds (default)'ms' — millisecondsResolves after the row is closed and any triggered auto-flush completes.
Closes the row without writing a designated timestamp.
Designated timestamp will be populated by the server on this record.
On ILP, a row is discarded -- its columns and its table selection alike --
only when it can never be closed, which means it carries no symbol and no
column; rows completed earlier remain staged, and the next row starts from
table again. Every other rejection leaves the row open and this
call retryable: a row that does not fit max_buf_size has its partial
close rewound, so the same call succeeds once a flush() frees space, and
a rejected column or symbol call writes nothing. If this call triggers an
auto-flush that fails, ILP transports have already removed the entire
staged batch from the sender buffer. Applications that need to retry ILP
rows must retain and resubmit them. QWP retains successfully closed rows
for its retry and replay path.
Resolves after the row is closed and any triggered auto-flush completes.
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. A null or undefined value omits the column entirely (stored as NULL).
Returns with a reference to this sender.
Closes the connection to the database. QWP publishes completed rows and performs a bounded acknowledgement drain first. Other transports retain their legacy behavior and require an explicit flush().
Establishes the transport connection for TCP, TCPS, WS, WSS, and UDP. HTTP and HTTPS connect per request and reject this call because no explicit connection step is required.
Resolves to true if the client is connected.
Writes a decimal value into the buffer using the binary format.
Use it to insert into DECIMAL database columns.
Column name.
The unscaled value of the decimal in two's complement representation and big-endian byte order. A null or undefined value omits the column entirely when decimals are supported; ILP protocol v1/v2 reject the call for every value. An empty array also represents NULL, but the two are not encoded alike: on the ILP transports an empty array writes an explicit NULL decimal field, while the QWP transports omit the column exactly as they do for null. QuestDB records NULL either way for a column that already exists.
The scale of the decimal value.
Returns with a reference to this buffer.
Writes a decimal value into the buffer using the text format.
Use it to insert into DECIMAL database columns.
Column name.
Column value, accepts only number/string values. A null or undefined value omits the column entirely when decimals are supported; ILP protocol v1/v2 reject the call for every value.
Returns with a reference to this buffer.
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. A null or undefined value omits the column entirely (stored as NULL).
Returns with a reference to this sender.
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.
Flushes pending rows and returns the highest QWP frame sequence published by this call. Non-QWP transports flush normally and return -1n because they do not expose frame sequences.
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. A null or undefined value omits the column entirely (stored as NULL).
Returns with a reference to this sender.
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.
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. A null or undefined value omits the column entirely (stored as NULL).
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. A null or undefined value omits the symbol entirely (stored as NULL).
Returns with a reference to this sender.
Writes the table name into the buffer of the sender of the sender.
Table name.
Returns with a reference to this sender.
Writes a timestamp column and its value into the buffer of the sender.
Use this method to insert data into TIMESTAMP or TIMESTAMP_NS columns.
Precision rules:
'ns' (nanoseconds) are sent with full nanosecond precision.
All other timestamps are sent with microsecond precision.The column name.
The epoch timestamp. Must be an integer or a BigInt. A null or undefined value omits the column entirely (stored as NULL).
Optionalunit: TimestampUnit = "us"The time unit of the timestamp. Supported values:
'ns' — nanoseconds (requires BigInt)'us' — microseconds (default)'ms' — millisecondsReturns with a reference to this buffer.
Waits independently for a cumulative QWP ACK watermark.
OptionaltimeoutMs: numberCompiles a table-bound object-row writer for QWP transports. Legacy ILP transports continue to use the fluent row API.
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.
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 } })})
An undici.Agent applies only to the default HTTP(S) transport. QWP WS/WSS uses the ws package and requires a Node.js http.Agent/https.Agent; an incompatible top-level agent is ignored with a warning.
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.
QWP authenticates the WebSocket upgrade with HTTP Basic (username and password) or Bearer (token); it has no JWK path, so auth, jwk, token_x and token_y are rejected rather than ignored. tls_verify and tls_ca apply to wss only. Supplying qwp.webSocket.authorization alongside username/password or token is rejected as ambiguous, the same way a custom agent cannot be combined with tls_verify/tls_ca.