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.
The InfluxDB 2 client is bundled as a gem and is hosted on Rubygems.
The client can be installed manually or with bundler.
To install the client gem manually:
gem install influxdb-client -v 1.5.0
Use InfluxDB::Client to create a client connected to a running InfluxDB 2 instance.
client = InfluxDB2::Client.new('https://localhost:9999', 'my-token')
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)
The result retrieved by QueryApi could be formatted as a:
- Raw query response
- Flux data structure: FluxTable, FluxColumn and FluxRecord
- Stream of FluxRecord
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()')
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()')
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
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')
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')
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 nanosecondInfluxDB2::WritePrecision::MICROSECOND
for microsecondInfluxDB2::WritePrecision::MILLISECOND
for millisecondInfluxDB2::WritePrecision::SECOND
for second
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')
The data could be written as:
String
that is formatted as a InfluxDB's line protocolHash
with keys: name, tags, fields and time- Data Point structure
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])
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:
- String -
"2019-02-03T04:05:06+07:00"
- DateTime -
DateTime.rfc3339('2019-03-03T04:05:06+07:00')
- Time -
Time.utc(2015, 10, 16, 8, 20, 15)
Server availability can be checked using the client.health
method. That is equivalent of the influx ping.
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.
brew install wget # on a mac, if not yet installed!
bin/influxdb-restart.sh
rake test
Bug reports and pull requests are welcome on GitHub at https://github.com/influxdata/influxdb-client-ruby.
The gem is available as open source under the terms of the MIT License.