Introduction

InfluxDB is a time series database, so it would make sense that the concept of time is moderately important when dealing with it.

By default, Influx will store all dates you give to it as a nanosecond precision timestamp, whereas in JavaScript, most of the time we’re dealing with millisecond precision timestamps, which we get from Date.now() or myDate.getTime(). This presents a bit of a problem for us JavaScripters, since nanosecond-precision timestamps are stored as 64-bit unsigned integers that JavaScript simply cannot represent accurately.

1
2
3
node-influx git:(master) node
> 1475985480231035677
1475985480231035600

This module tries to make dates as easy as possible for you to deal with, and out of the box everything should ‘just work’.

There are three places that dates can get passed around:

  • Dates coming rom Influx queries, like select * from my_series

  • Dates being interpolated into Influx queries

  • Dates being used when writing points on the line protocol, via .writePoints() or .writeMeasurement().

To deal with this, we introduce a new type called NanoDate. These dates behave just like the normal Date type, but have two additional methods: .getNanoTime() and .getNanoISOString(). They behave just like the normal .getTime() and getISOString methods, but they both return nanosecond-precision strings instead of millisecond-precision numbers and timestamps.

1
2
3
4
expect(myNanoDate.getTime()).to.equal(1475985480231)
expect(myNanoDate.getNanoTime()).to.equal('1475985480231035677')
expect(myNanoDate.toISOString()).to.equal('2016-10-09T03:58:00.231Z')
expect(myNanoDate.toNanoISOString()).to.equal('2016-10-09T03:58:00.231035677Z')

All times returned from Influx queries are parsed to INanoDates. For example you can do something like the following:

1
2
3
influx.query('select * from perf').then(results => {
  result.forEach(row => console.log(`Used ${row.cpu} at ${row.time.toNanoISOString()}`))
})

When writing data to Influx, all write methods accept INanoDates in all situation. This means if you select data from Influx and want to update a data point, you can pass the time right back into write method. (Remember, points within series are unique by their time) If you have a nanosecond timestamp from some external source, you can convert it to INanoDate using toNanoDate.

1
2
3
4
5
6
import { toNanoDate } from 'influx'

const myNanoDate = toNanoDate('1475985480231035600')
expect(myNanoDate.getTime()).to.equal(1475985480231)
expect(myNanoDate.getNanoTime()).to.equal('1475985480231035600')
expect(myNanoDate.toNanoISOString()).to.equal('2016-10-09T03:58:00.231035600Z')

Finally, if you want to embed a iNanoDate into an Influx query, you should use toNanoString to do so:

1
influx.query(`select * from perf where time > "${myNanoDate.toNanoISOString()}"`)

Browser Setup

For Node.js, influx can be installed and you can use it out of the box.

1
yarn add influx@next

You can tell Webpack to use this module by adding the following section in your webpack.config.js:

1
2
3
4
5
6
7
const http = path.resolve(__dirname, 'node_modules/stream-http/index.js')

module.exports = {
  resolve: {
    alias: { http, https: http },
  }
}

Reference

Class Summary

attr name
public ExponentialBackoff
public Expression:
Expression is used to build filtering expression, like those used in WHERE clauses
public InfluxDB:
InfluxDB is the public interface to run queries against your database
public Measurement:
Measurement creates a reference to a particular measurement
public Pool:
The Pool maintains a list available Influx hosts and dispatches requests to them
public Raw:
You can provide Raw values to Influx methods to prevent it from escaping your provided string.
public RequestError:
An RequestError is thrown when a query generates errorful results in a 300<= error <=500
public ResultError:
An ResultError is thrown when a query generates errorful results from Influx
public ServiceNotAvailableError:
An ServiceNotAvailableError is returned as an error from requests that result in a >500 error code

interface Summary

attr name
public IBackoffStrategy:
The IBackoffStrategy dictates behavior to use when hosts in the connection pool start failing
public INanoDate:
An INanoDate is a type of Date that holds a nanosecond-precision unix timestamp
public IResults:
IResults are returned from the InfluxBD#query mehtod

Function Summary

attr name
public toNanoDate(timestamp: String): NanoDate:
Covers a nanoseconds unix timestamp to a INanoDate for node-influx.

Variable Summary

attr name
public Precision: Object

<string, string=””>:
Precision is a map of available influx time precision</string,>
public | escape: Object:

tagEscaper escapes tag keys, tag values and field keys.

Typedef Summary

attr name
public FieldType: Number:
FieldType is an enumeration of influxDB field data types
public IClusterConfig: Object:
A IClusterConfig can be provided into new InfluxDB(config) when you have a multiple influx nodes to connect to
public IPingStats: Object:
IPingStats is returned from InfluxDB#ping
public IPoint: Object
IPoint is passed to the client’s write methods to store a point in InfluxDB
public IPoolOptions: Object
Pool options can be passed into the database to configure the behavior of the connection Pool
public IQueryOptions: Object
The IQueryOptions allows you to configure how queries are run against Influx
public ISchemaOptions: Object
Schema options can be passed into the new InfluxDB() constructor to help define the shape of your data.
public ISingleHostConfig: Object
A ISingleHostConfig can be provided into new InfluxDB(config) when you have a single Influx address to connect to
public IWriteOptions: Object
IWriteOptions configure how points are written in the database.