Class: Sender

Sender(options)

The QuestDB client's API provides methods to connect to the database, ingest data, and close the connection. The supported protocols are HTTP and TCP. HTTP is preferred as it provides feedback in the HTTP response.
Based on benchmarks HTTP also provides higher throughput, if configured to ingest data in bigger batches.

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 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.

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 http.Agent({ keepAlive: false })})
If no custom agent is configured, the Sender will use its own agent which overrides some default values of http.Agent/https.Agent. The Sender's own agent uses persistent connections with 1 minute idle timeout, and limits the number of open connections to the server, which is set to 256 for each host.

Constructor

new Sender(options)

Creates an instance of Sender.
Parameters:
Name Type Description
options SenderOptions Sender configuration object.
See SenderOptions documentation for detailed description of configuration options.
Source:

Methods

(async) at(timestamp, unitopt)

Closing the row after writing the designated timestamp into the buffer of the sender.
Parameters:
Name Type Attributes Default Description
timestamp number | bigint Designated epoch timestamp, accepts numbers or BigInts.
unit string <optional>
 us Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
Source:

(async) atNow()

Closing the row without writing designated timestamp into the buffer of the sender.
Designated timestamp will be populated by the server on this record.
Source:

booleanColumn(name, value) → {Sender}

Write a boolean column with its value into the buffer of the sender.
Parameters:
Name Type Description
name string Column name.
value boolean Column value, accepts only boolean values.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

(async) close()

Closes the TCP connection to the database.
Data sitting in the Sender's buffer will be lost unless flush() is called before close().
Source:

connect(connectOptions) → {Promise.<boolean>}

Creates a TCP connection to the database.
Parameters:
Name Type Description
connectOptions net.NetConnectOpts | tls.ConnectionOptions Connection options, host and port are required.
Source:
Returns:
Resolves to true if the client is connected.
Type
Promise.<boolean>

floatColumn(name, value) → {Sender}

Write a float column with its value into the buffer of the sender.
Parameters:
Name Type Description
name string Column name.
value number Column value, accepts only number values.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

(async) flush() → {Promise.<boolean>}

Sends the buffer's content to the database and compacts the buffer. If the last row is not finished it stays in the sender's buffer.
Source:
Returns:
Resolves to true when there was data in the buffer to send.
Type
Promise.<boolean>

intColumn(name, value) → {Sender}

Write an integer column with its value into the buffer of the sender.
Parameters:
Name Type Description
name string Column name.
value number Column value, accepts only number values.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

reset() → {Sender}

Resets the buffer, data added to the buffer will be lost.
In other words it clears the buffer and sets the writing position to the beginning of the buffer.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

resize(bufferSize)

Extends the size of the sender's buffer.
Can be used to increase the size of buffer if overflown. The buffer's content is copied into the new buffer.
Parameters:
Name Type Description
bufferSize number New size of the buffer used by the sender, provided in bytes.
Source:

stringColumn(name, value) → {Sender}

Write a string column with its value into the buffer of the sender.
Parameters:
Name Type Description
name string Column name.
value string Column value, accepts only string values.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

symbol(name, value) → {Sender}

Write a symbol name and value into the buffer of the sender.
Parameters:
Name Type Description
name string Symbol name.
value any Symbol value, toString() will be called to extract the actual symbol value from the parameter.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

table(table) → {Sender}

Write the table name into the buffer of the sender.
Parameters:
Name Type Description
table string Table name.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

timestampColumn(name, value, unitopt) → {Sender}

Write a timestamp column with its value into the buffer of the sender.
Parameters:
Name Type Attributes Default Description
name string Column name.
value number | bigint Epoch timestamp, accepts numbers or BigInts.
unit string <optional>
 us Timestamp unit. Supported values: 'ns' - nanoseconds, 'us' - microseconds, 'ms' - milliseconds. Defaults to 'us'.
Source:
Returns:
Returns with a reference to this sender.
Type
Sender

(static) fromConfig(configurationString, extraOptions) → {Sender}

Creates a Sender options object by parsing the provided configuration string.
Parameters:
Name Type Description
configurationString string Configuration string.
extraOptions object Optional extra configuration.
- 'log' is a logging function used by the Sender.
Prototype: (level: 'error'|'warn'|'info'|'debug', message: string) => void.
- 'agent' is a custom http/https agent used by the Sender when http/https transport is used.
A http.Agent or https.Agent object is expected.
Source:
Returns:
A Sender object initialized from the provided configuration string.
Type
Sender

(static) fromEnv(extraOptions) → {Sender}

Creates a Sender options object by parsing the configuration string set in the QDB_CLIENT_CONF environment variable.
Parameters:
Name Type Description
extraOptions object Optional extra configuration.
- 'log' is a logging function used by the Sender.
Prototype: (level: 'error'|'warn'|'info'|'debug', message: string) => void.
- 'agent' is a custom http/https agent used by the Sender when http/https transport is used.
A http.Agent or https.Agent object is expected.
Source:
Returns:
A Sender object initialized from the QDB_CLIENT_CONF environment variable.
Type
Sender