node package manager

influx

InfluxDB Client

node-influx

An InfluxDB Node.js Client

- Reward the contributors for their efforts on upcoming tasks.

Interested in becoming a maintainer? Please help out with issues and pull-requests and open an issue introducing yourself! After we've seen you're involved with the project, we'll add you up 👍

$ npm install influx

Version 4.x.x is compatible with InfluxDB 0.9.x

Version 3.x.x is compatible with InfluxDB 0.8.x - 3.x will no longer have updates by core contributors, please consider upgrading.

Create a client instance (database not required for all methods):

var influx = require('influx')
 
var client = influx({
 
  //cluster configuration 
  hosts: [
    {
      host: 'localhost',
      port: 8060, //optional. default 8086 
      protocol: 'http' //optional. default 'http' 
    }
  ],
  // or single-host configuration 
  host: 'localhost',
  port: 8086, // optional, default 8086 
  protocol: 'http', // optional, default 'http' 
  username: 'dbuser',
  password: 'f4ncyp4ass',
  database: 'my_database'
})
 

A list of all configuration values can be found below.

You can either pass a single hostname or an array of hostnames. Node-influx uses round-robin balancing to distribute the requests across all configured hosts. When a host is unreachable, node-influx tries to resubmit the request to another host and disables the failed host for 60 seconds (timeout value is configurable). If all servers fail to respond, node-influx raises an error.

You can also pass an URL or an array of URLs:

var influx = require('influx')
 
var client = influx('http://dbuser:f4ncyp4ass@localhost:8060/my_database')
// or 
client = influx({
  hosts: ['http://127.0.0.1', 'https://127.0.0.2'],
  username: 'dbuser',
  password: 'f4ncyp4ass',
  database: 'my_database'
 })
Option Description
username username
password password
database database name
host hostname, e.g. 'localhost'
port [optional] influxdb port, default: 8086
protocol [optional] protocol, default: http
hosts [optional] Array of hosts for cluster configuration, e.g. [ {host: 'localhost', port: 8086},...] Port is optional
depreciatedLogging [optional] logging function for depreciated warnings, defaults to console.log
failoverTimeout [optional] number of ms node-influx will take a host out of the balancing after a request failed, default: 60000
requestTimeout [optional] number of ms to wait before a request times out. defaults to 'null' (waits until connection is closed). Use with caution!
maxRetries [options] max number of retries until a request raises an error (e.g. 'no hosts available'), default: 2
timePrecision [optional] Time precision, default: ms

Sets the default timeout for a request. When a request times out the host is removed from the list of available hosts and the request is resubmitted to the next configured host. The default value is null (will wait forever for a respose).

Be careful with this setting. If the value is too low, slow queries might disable all configured hosts.

client.setRequestTimeout( value )

Sets the failover timeout for a host. After a host has been removed from balancing, it will be re-enabled after 60 seconds (default). You can configure the timeout value using this function.

client.setFailoverTimeout( value )

Returns an array of available hosts.

getHostsAvailable( )

Returns an array of disabled hosts. This can be useful to check whether a host is unresponsive or not.

client.getHostsDisabled( )

Creates a new database - requires cluster admin privileges

client.createDatabase(databaseName, function (err, result) { })

Returns array of database names - requires cluster admin privileges

client.getDatabaseNames(function (err, arrayDatabaseNames) { })

Drops a database inluding all measurements/series - requires cluster admin privileges

dropDatabase (databaseName, function (err, response) { })

Returns array of measurements - requires database admin privileges

client.getMeasurements(function (err, arrayMeasurements) { })

Drops a measurement from a database - requires database admin privileges

dropSeries (measurementName, function (err, response) { })

Returns array of series names from given measurement, or database if measurementName is omitted - requires database admin privileges

client.getSeries([measurementName], function (err, arraySeriesNames) { })

Returns array of series names from given measurement - requires database admin privileges

client.getSeriesNames([measurementName], function (err, arraySeriesNames) { })

Drops a series from a database - requires database admin privileges

dropSeries (seriesId, function (err, response) { })

Returns an array of users - requires cluster admin privileges

client.getUsers(function (err, users) { } )

Creates a new database user - requires cluster admin privileges

client.createUser(username, password, isAdmin, function (err, response) { })

Sets the users password - requires admin privileges

client.setPassword(username, password, function (err, response) { })

Grants privilege for the given user - requires admin privileges

client.grantPrivilege(privilege, databaseName, userName, function (err, response) { })

Revokes privilege for the given user - requires admin privileges

client.revokePrivilege(privilege, databaseName, userName, function (err, response) { })

Grants admin privileges for the given user - requires admin privileges

client.grantAdminPrivileges(userName, function (err, response) { })

Revokes all admin privileges for the given user - requires admin privileges

client.revokeAdminPrivileges(userName, function (err, response) { })

Drops the given user - requires admin privileges

client.dropUser(userName, function (err, response) { })

Writes a point to a series - requires database user privileges

client.writePoint(seriesName, values, tags, [options], function (err) { })

values can be either an object or a single value. In the latter case, the field key is set to value. You can set the time by passing an object property called time. The time can be either an integer value or a Date object. When providing a single value, don't forget to adjust the time precision accordingly. The default value is ms.

The tags will be automatically sorted, for maximum write throughput performance.

The parameter options is an optional and can have following fields:

  • db: Database to work with
  • precision: Time precision
  • rp: Retention policy
//write a single point with two values and two tags. time is omitted 
client.writePoint(info.series.name, {value: 232, value2: 123}, {foo: 'bar', foobar: 'baz'}, done)
 
//write a single point with the value "1". The value "1" corresponds to {value: 1} 
client.writePoint(info.series.name, 1, {foo: 'bar', foobar: 'baz'}, done)
 
//write a single point, providing an integer timestamp and time precision 's' for seconds 
client.writePoint(info.series.name, {time: 1234567890, value: 232}, null, {precision: 's'}, done)
 
//write a single point, providing a Date object. Precision is set to default 'ms' for milliseconds. 
client.writePoint(info.series.name, {time: new Date(), value: 232}, null,  done)
 
 

Writes multiple points to a series - requires database user privileges

 client.writePoints(seriesName, points, [options], function (err) { })

Points is an array of points. Each point is an array of two objects - the field set, and the tag set. If you want to add a timestamp, add a time key in the first object. (We're looking for input on this API - see #182.)

var points = [
  // One field with one tag 
  [{value: 232}, {tag: 'foobar'}],
  // One field with two tags 
  [{value: 212}, {tag1: 'baz', tag2: 'quux'}],
  // Field with just value (key defaults to 'value'). Different tag. 
  [123, {foobar: 'baz'}],
  // Timestamp, one field, no tags 
  [{value: 122, time: new Date()}]
];
client.writePoints(seriesName, points, [options], callback)

The parameter options is an optional and can have following fields:

  • db: Database to work with
  • precision: Time precision
  • rp: Retention policy

Writes multiple point to multiple series - requires database user privileges

var points1 = [
  // One field with one tag 
  [{value: 232}, {tag: 'foobar'}],
  // One field with two tags 
  [{value: 212}, {tag1: 'baz', tag2: 'quux'}],
  // Field with just value (key defaults to 'value'). Different tag. 
  [123, {foobar: 'baz'}],
  // Timestamp, one field, no tags 
  [{value: 122, time: new Date()}]
]
 
var points2 = [
  // One field with one tag 
  [{value: 1232}, {tag: 'foobar'}],
  // Another field with a different tag 
  [{value: 223212}, {someothertag: 'baz'}],
  // Third field 
  [12345, {foobar: 'baz'}],
  // Timestamp, one field, no tags 
  [{value: 23122, time: new Date()}]
];
var series = {
    series_name_one: points1,
    series_name_two: points2
};
 
client.writeSeries(series, [options], function (err, response) { })

The parameter options is an optional and can have following fields:

  • db: Database to work with
  • precision: Time precision
  • rp: Retention policy

Please note that there's a POST limit at about 2MB per request. Do not submit too many points at once.

Queries the database and returns an array of parsed responses. - requires database user privileges.

var query = 'SELECT MEDIAN(column) FROM myseries WHERE time > now() - 24h';
client.query([database], query, function (err, results) { })
 

If database is omitted, node-influx uses the database defined in the default options. Since InfluxDB 0.9, all values with different tags are stored in different timeseries. The response from InfluxDB contains an array of values for each series that matches the request. To make things easier the query function now returns a parsed response, meaning that all points from all series are merged into a single array of points and their tags. You can still retrieve the raw response from InfluxDB using client.queryRaw().

You can also pass multiple queries at once. The callback returns an array of series, one series per query.

client.query('SELECT * FROM myseries; SELECT AVG(VALUE) as avgvalue from myseries', function (err, results) {});
 
// -> results =[ 
//   [ {value: 1, tagname: 'tagvalue'}, {value: 3, othertag: 'value}], 
//   [ {avgvalue: 2.345}] 
// ] 
 

Same as function query but returns the raw response from InfluxDB.

var query = 'SELECT MEDIAN(column) FROM myseries WHERE time > now() - 24h';
client.queryRaw([database], query, function (err, results) { })
 

Creates a continuous query - requires admin privileges

client.createContinuousQuery('testQuery', 'SELECT COUNT(value) INTO valuesCount_1h FROM ' + info.series.name + ' GROUP BY time(1h) ', function (err, results) {} )

Fetches all continuous queries from a database - requires database admin privileges

client.getContinuousQueries(function (err, arrayContinuousQueries) { })

Drops a continuous query from a database - requires database admin privileges

client.dropContinuousQuery(queryName, [databaseName], function (err, results) { })

Fetches all retention policies from a database.

client.getRetentionPolicies(databaseName, function (err, response) { })

Creates a new retention policy - requires admin privileges.

client.createRetentionPolicy(rpName, databaseName, duration, replication, isDefault, function (err, response) { })
client.createRetentionPolicy('my_ret_pol_name', 'my_database', '1d', 1, true, function (err, response) { })

Alters an existing retention policy - requires admin privileges.

client.alterRetentionPolicy(rpName, databaseName, duration, replication, isDefault, function (err, response) { })

As Jeff Atwood puts it... Read the source, Luke. If you're still stuck, read the ./examples/* files and the ./test.js file.

Either install InfluxDB or use a docker container to run the service:

docker run -d -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 tutum/influxdb:0.13

Then to run the test harness use npm test.

If you want to add features, fix bugs or improve node-influx, please open a pull-request. Please note, we are following Javascript Standard Style. Before opening a PR, your code should pass Standard:

npm run lint

MIT