/influxdb-client-ruby

InfluxDB 2.0 Ruby Client

Primary LanguageRubyMIT LicenseMIT

influxdb-client-ruby

CircleCI codecov Gem Version License GitHub issues GitHub pull requests Slack Status

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+ (see details). For connecting to InfluxDB 1.7 or earlier instances, use the influxdb-ruby client library.

Installation

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

Install the Gem

The client can be installed manually or with bundler.

To install the client gem manually:

gem install influxdb-client -v 1.3.0

Usage

Creating a client

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

client = InfluxDB2::Client.new('https://localhost:9999', 'my-token')

Client Options

Option Description Type Default
bucket Default destination bucket for writes String none
org Default organization bucket for writes String none
precision Default precision for the unix timestamps within the body line-protocol String none
open_timeout Number of seconds to wait for the connection to open Integer 10
write_timeout Number of seconds to wait for one block of data to be written Integer 10
read_timeout Number of seconds to wait for one block of data to be read Integer 10
max_redirect_count Maximal number of followed HTTP redirects Integer 10
use_ssl Turn on/off SSL for HTTP communication bool true
client = InfluxDB2::Client.new('https://localhost:9999', 'my-token',
  bucket: 'my-bucket',
  org: 'my-org',
  precision: InfluxDB2::WritePrecision::NANOSECOND)

Queries

The result retrieved by QueryApi could be formatted as a:

  1. Raw query response
  2. Flux data structure: FluxTable, FluxColumn and FluxRecord
  3. Stream of FluxRecord

Query raw

Synchronously executes the Flux query and return result as unprocessed String

client = InfluxDB2::Client.new('https://localhost:9999', '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 FluxTables

client = InfluxDB2::Client.new('https://localhost:9999', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')

query_api = client.create_query_api
result = query_api.query(query: 'from(bucket:"' + bucket + '") |> range(start: 1970-01-01T00:00:00.000000001Z) |> last()')

Query stream

Synchronously executes the Flux query and return stream of FluxRecord

client = InfluxDB2::Client.new('https://localhost:9999', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')

query_api = client.create_query_api

query = 'from(bucket: "my-bucket") |> range(start: -10m, stop: now()) ' \
      "|> filter(fn: (r) => r._measurement == \"#{measurement}\")"

query_api.query_stream(query: query).each do |record|
  puts record.to_s
end

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:9999', '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:

Property Description Default Value
batchSize the number of data point to collect in batch 1000
flushInterval the number of milliseconds before the batch is written 1000
retry_interval the number of milliseconds to retry unsuccessful write. The retry interval is used when the InfluxDB server does not specify "Retry-After" header. 1000
jitter_interval the number of milliseconds to increase the batch flush interval by a random amount 0
write_options = InfluxDB2::WriteOptions.new(write_type: InfluxDB2::WriteType::BATCHING,
                                            batch_size: 10, flush_interval: 5_000)
client = InfluxDB2::Client.new('http://localhost:9999',
                               'my-token',
                               bucket: 'my-bucket',
                               org: 'my-org',
                               precision: InfluxDB2::WritePrecision::NANOSECOND,
                               use_ssl: false)

write_api = client.create_write_api(write_options: write_options)
write_api.write(data: 'h2o,location=west value=33i 15')

Time precision

Configure default time precision:

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

Configure precision per write:

client = InfluxDB2::Client.new('https://localhost:9999', '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:

client = InfluxDB2::Client.new('https://localhost:9999', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')

but there is also possibility to override configuration per write:

client = InfluxDB2::Client.new('https://localhost:9999', '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. Data Point structure
  4. Array of above items
client = InfluxDB2::Client.new('https://localhost:9999', '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' },
         fields: { level: 5, saturation: '99%' }, time: 123 }

write_api = client.create_write_api
write_api.write(data: ['h2o,location=west value=33i 15', point, hash])

Delete data

The DeleteApi supports deletes points from an InfluxDB bucket.

client = InfluxDB2::Client.new('http://localhost:9999', '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. DateTime - DateTime.rfc3339('2019-03-03T04:05:06+07:00')
  3. Time - Time.utc(2015, 10, 16, 8, 20, 15)

Advanced Usage

Check the server status

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

InfluxDB 1.8 API compatibility

InfluxDB 1.8.0 introduced forward compatibility APIs 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:

API Endpoint Description
query_api.rb /api/v2/query Query data in InfluxDB 1.8.0+ using the InfluxDB 2.0 API and Flux (endpoint should be enabled by flux-enabled option)
write_api.rb /api/v2/write Write data to InfluxDB 1.8.0+ using the InfluxDB 2.0 API
health_api.rb /health Check the health of your InfluxDB instance

For detail info see InfluxDB 1.8 example.

Local tests

brew install wget # on a mac, if not yet installed!
bin/influxdb-restart.sh
rake test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/influxdata/influxdb-client-ruby.

License

The gem is available as open source under the terms of the MIT License.