🌊
InfluxDB javascript driver
Overview
This is a InfluxDB driver for Javascript apps. It could work both in Node or browser1.
Install
For node.js/iojs usage:
$ npm install --save influent
For usage in browser:
bower install --save influent
Usage
var influent = ; influent ;
Type System
According to InfluxDB@0.9 docs there are four data types:
Field values may be stored as float64, int64, boolean, or string. All subsequent field values must match the type of the first point written to given measurement.
float64
values are the default numerical type.1
is a float,1i
is an integer;int64
value must have a trailingi
. The fieldbikes_present=15i
stores an integer and the fieldbikes_present=15
stores a float;boolean
values aret
,T
,true
,True
, orTRUE
for TRUE, andf
,F
,false
,False
, orFALSE
for FALSE;string
values for field values must be double-quoted. Double-quotes contained within the string must be escaped. All other characters are supported without escaping.
There is a little bit problem with Javascript numbers, cause it could be both integer or float. So to solve it there is the influent.Value
abstraction for you:
var influent = ; // client creation somewhere client ;
Usage without decorator
When you call influent.createAnyClient
you get a decorated client, that allows you to pass simple object
literals to write
and query
. This, of course, get some performance overhead and unnecessary object casting and type checks.
You could use this way, to be more explicit:
// create client var client = username: "gobwas" password: "xxxx" ; // use line serializer client; // use http client (this is for node, XhrHttp is for browser) client; // use stub elector, that always elects first host client; // create batch of points var batch = database: "mydb" ; batch // send batch client; // create query object var query = "select * from key" database: "mydb" ; // eval query client;
API
influent.createHttpClient(config: Object)
-> Promise[influent.DecoratorClient[influent.HttpClient]]
Creates influent.DecoratorClient
instance, with influent.HttpClient
inside.
This method makes client.ping()
, to sure that connection is OK.
The config
should have structure like this:
// required // -------- server: protocol: string host: string port: number // or server: serverA... serverN username: string password: string // optional // -------- database: string // write options precision: enumn u ms s m h consistency: enumone quorum all any rp: string max_batch: number // query options epoch: enumn u ms s m h chunk_size: number
influent.createUdpClient(config: Object)
-> Promise[influent.DecoratorClient[influent.UdpClient]]
Default factory for creating udp client. Creates influent.DecoratorClient
instance, with influent.UdpClient
inside.
The config
should have structure like:
// required // -------- server: protocol: string host: string port: number // or server: serverA... serverN // optional // -------- // write options precision: enumn u ms s m h // unsupported yet max_batch: number safe_limit: number
influent.Batch
Class: new influent.Batch([options: Object])
Where options could be:
database: string precision: enumn u ms s m h consistency: enumone quorum all any rp: string
batch.add(m: influent.Measurement)
batch.options()
-> Object
batch.measurements()
-> Array[Measurement]
influent.Query
Class: new influent.Query(command: string[, options: Object])
Where options could be:
database: string epoch: enumn u ms s m h chunk_size: number
query.command()
-> string
query.options()
-> Object
influent.Client
Class: Abstract class of InfluxDB client. Has several abstract methods:
new influent.Client([options: Object])
client.ping()
-> Promise[Object{ info: influent.Info, host: influent.Host }]
Pings host.
client.query(query: influent.Query)
-> Promise[Object]
Asks for data.
client.write(batch: influent.Batch)
-> Promise[]
Writes measurements.
influent.NetClient
Class: Abstract ancessor of influent.Client
. Has several injector methods:
client.injectElector(elector: influent.Elector)
client.injectSerializer(serializer: influent.Serializer)
influent.HttpClient
Class: Implementation of influent.NetClient
for http usage.
new influent.HttpClient(options: Object)
Where options could be like:
// required // -------- username: string password: string
httpClient.query(query: influent.Query)
-> Promise[Object]
httpClient.write(batch: influent.Batch)
-> Promise[]
httpClient.injectHttp(http: hurl.Http)
Injector of http service, that is implementation of abstract hurl.Http
class. hurl
is just npm dependency.
influent.UdpClient
Class: Implementation of influent.NetClient
for udp usage.
new influent.UdpClient(options: Object)
Where options could be like:
// optional // -------- safe_limit: number
udpClient.query(query: influent.Query)
-> Promise[Object]
This method returns rejected Promise
, cause there is no ability to fetch some data through udp from InfluxDB.
udpClient.write(batch: influent.Batch)
-> Promise[]
httpClient.injectUdp(http: influent.Udp)
Injector of udp service.
influent.DecoratorClient[T: influent.Client]
Class: Wrapper around influent.Client
for better usability purposes.
new DecoratorClient([options: Object])
If options are present, the could contain these optional fields:
database: string // write optionsprecision: enumn u ms s m hconsistency: enumone quorum all anyrp: stringmax_batch: number // query optionsepoch: enumn u ms s m hchunk_size: number
decoratorClient.write(data: influent.Batch | Object | influent.Measurement | Array[Object | influent.Measurement][, options: Object])
-> Promise[]
When measurement is Object
, it should have structure like:
// required key: string // one of or both `value` or non-empty `fields` should be present value: string | number | boolean | influentType fields: fieldName: string | number | boolean | influentType // optional tags: tagName: string // optional timestamp: number | string | Date
decoratorClient.injectClient(client: influent.Client)
influent.Elector
Class: Represents strategy of electing host to send request.
new influent.Elector(hosts: Array[influent.Host][, options])
elector.getHost()
-> Promise[Host]
influent.RoundRobinElector
Class: Round robin strategy of host election.
influent.BaseElector
Class: Base strategy of election. Uses influent.Ping
to check health.
new influent.BaseElector(hosts: Array[influent.Host][, options])
Where options:
period: number
baseElector.injectPing(ping: influent.Ping)
influent.Ping
Class: Represents strategy of checking host health.
new influent.Ping([, options])
ping.pong()
-> Promise[]
influent.HttpPing
Class: Checks health via http request.
new influent.HttpPing([, options])
Where options:
timeout: number
httpPing.injectHttp(http: hurl.Http)
influent.CmdPing
Class: Checks health via exec ping ...
.
new influent.CmdPing([, options])
Where options:
timeout: number count: number
influent.LineSerializer
Class: Line protocol implementation of influent.Serializer
.
influent.Type
Class: influent.I64
Class: new influent.I64(data: number)
influent.F64
Class: new influent.F64(data: number)
influent.Bool
Class: new influent.Bool(data: boolean)
influent.Str
Class: new influent.Str(data: string)
influent.Measurement
Class: new influent.Measurement(key: string)
measurement.addTag(key: string, value: string)
measurement.addField(key: string, value: influent.Value)
measurement.setTimestamp(timestamp: string)
Sets timestamp to the measurement. Using numeric string
, cause it make sense
on a big numbers with precision in nanoseconds.
influent.Host
Class: new influent.Host(protocol: string, host: string, port: number)
host.toString()
-> String
influent.Info
Class: Represents client.ping()
meta information.
new influent.Info()
Notes
1: Browser version is about 41KB minified, and 13KB gzipped. There are no polyfills in bundle for old browsers! Be sure, that you have at least these global objects and object methods:
Promise
;Object.keys
;Array.forEach
;XMLHttpRequest
.
Some Node.js specific classes are excluded from the influent
API browser build.
Compatibility
InfluxDB | Influent |
---|---|
<0.9.3 |
^0.2.3 |
>0.9.3 |
^0.3.0 |
License
MIT © Sergey Kamardin