influxdb-client-ruby

This repository contains the reference Ruby client for the InfluxDB 2.0.

Note: Use this client library with InfluxDB 2.x and InfluxDB 1.8+ (). For connecting to InfluxDB 1.7 or earlier instances, use the influxdb-ruby client library.

The InfluxDB 2 client is bundled as a gem and is hosted on .

The client can be installed manually or with bundler.

To install the client gem manually:

Usage

Creating a client

Use InfluxDB::Client to create a client connected to a running InfluxDB 2 instance.

Client Options

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
  bucket: 'my-bucket',
  org: 'my-org',
  precision: InfluxDB2::WritePrecision::NANOSECOND)

The result retrieved by QueryApi could be formatted as a:

1. Raw query response
2. Flux data structure:
3. Stream of FluxRecord

Query raw

Synchronously executes the Flux query and return result as unprocessed String

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')
query_api = client.create_query_api
result = query_api.query_raw(query: 'from(bucket:"' + bucket + '") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()')

Synchronous query

Synchronously executes the Flux query and return result as a Array of

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')
result = query_api.query(query: 'from(bucket:"' + bucket + '") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()')

Query stream

Writing data

The WriteApi supports synchronous and batching writes into InfluxDB 2.0. In default api uses synchronous write. To enable batching you can use WriteOption.

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org',
                              precision: InfluxDB2::WritePrecision::NANOSECOND)
write_api = client.create_write_api
write_api.write(data: 'h2o,location=west value=33i 15')

Batching

The writes are processed in batches which are configurable by WriteOptions:

write_options = InfluxDB2::WriteOptions.new(write_type: InfluxDB2::WriteType::BATCHING,
                                            batch_size: 10, flush_interval: 5_000, 
                                            max_retries: 3, max_retry_delay: 15_000,
                                            exponential_base: 2)
client = InfluxDB2::Client.new('http://localhost:8086',
                               'my-token',
                               bucket: 'my-bucket',
                               org: 'my-org',
                               precision: InfluxDB2::WritePrecision::NANOSECOND,
                               use_ssl: false)
write_api.write(data: 'h2o,location=west value=33i 15')

Time precision

Configure default time precision:

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org',
                              precision: InfluxDB2::WritePrecision::NANOSECOND)

Configure precision per write:

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                                  bucket: 'my-bucket',
                                  org: 'my-org')
write_api = client.create_write_api
write_api.write(data: 'h2o,location=west value=33i 15', precision: InfluxDB2::WritePrecision::SECOND)

Allowed values for precision are:

• InfluxDB2::WritePrecision::NANOSECOND for nanosecond
• InfluxDB2::WritePrecision::MICROSECOND for microsecond
• InfluxDB2::WritePrecision::MILLISECOND for millisecond
• InfluxDB2::WritePrecision::SECOND for second

Configure destination

Default bucket and organization destination are configured via InfluxDB::Client:

but there is also possibility to override configuration per write:

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token')
write_api = client.create_write_api
write_api.write(data: 'h2o,location=west value=33i 15', bucket: 'production-data', org: 'customer-1')

Data format

The data could be written as:

1. String that is formatted as a InfluxDB’s line protocol
2. Hash with keys: name, tags, fields and time
3. structure

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org',
                              precision: InfluxDB2::WritePrecision::NANOSECOND)
point = InfluxDB2::Point.new(name: 'h2o')
                       .add_tag('location', 'europe')
                       .add_field('level', 2)
hash = { name: 'h2o',
         tags: { host: 'aws', region: 'us' },
write_api = client.create_write_api
write_api.write(data: ['h2o,location=west value=33i 15', point, hash])

Default Tags

The expressions:

• California Miner - static value
• ${env.hostname} - environment property

Via API

client = InfluxDB2::Client.new('http://localhost:8086', 'my-token',
                               bucket: 'my-bucket',
                               org: 'my-org',
                               precision: InfluxDB2::WritePrecision::NANOSECOND,
                               use_ssl: false,
                               tags: { id: '132-987-655' })
point_settings = InfluxDB2::PointSettings.new(default_tags: { customer: 'California Miner' })
point_settings.add_default_tag('data_center', '${env.data_center}')
write_api = client.create_write_api(write_options: InfluxDB2::SYNCHRONOUS,
                                    point_settings: point_settings)
write_api.write(data: InfluxDB2::Point.new(name: 'h2o')
                                      .add_tag('location', 'europe')
                                      .add_field('level', 2))

The DeleteApi supports deletes from an InfluxDB bucket.

client = InfluxDB2::Client.new('http://localhost:8086', 'my-token',
                               bucket: 'my-bucket',
                               org: 'my-org',
                               precision: InfluxDB2::WritePrecision::NANOSECOND)
client.create_delete_api.delete(DateTime.rfc3339('2019-02-03T04:05:06+07:00'),
                                DateTime.rfc3339('2019-03-03T04:05:06+07:00'),
                                predicate: 'key1="value1" AND key2="value"')

The time range could be specified as:

1. String - "2019-02-03T04:05:06+07:00"
2. Time - Time.utc(2015, 10, 16, 8, 20, 15)

Check the server status

Server availability can be checked using the client.health method. That is equivalent of the influx ping.

for InfluxDB 2.0. This allow you to easily move from InfluxDB 1.x to InfluxDB 2.0 Cloud or open source.

The following forward compatible APIs are available:

For detail info see InfluxDB 1.8 example.

Local tests

Bug reports and pull requests are welcome on GitHub at .

License