influxdb-client-ruby

This repository contains the reference Ruby client for the InfluxDB 2.x.

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.

• Installation
• Usage
  • Writing data
  • Delete data
• Advanced Usage
  • Proxy configuration
• License

This section contains links to the client library documentation.

• , Getting Started
• API Reference

Features

InfluxDB 2.x client consists of two packages

• • Querying data using the Flux language
  • Writing data
    • batched in chunks on background
    • automatic retries on write failures
• influxdb-client-apis
  • provides all other InfluxDB 2.x APIs for managing
    • buckets
    • labels
    • authorizations
    • …
  • built on top of influxdb-client

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:

For management API:

gem install influxdb-client-apis -v 2.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:8086', 'my-token')

Client Options

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

Queries

The result retrieved by could be formatted as a:

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

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 FluxTables

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

Query stream

Synchronously executes the Flux query and return stream of

Parameterized queries

InfluxDB Cloud inserts the params object into the Flux query as a Flux record named params. Use dot or bracket notation to access parameters in the params record in your Flux query. Parameterized Flux queries support only int , float, and string data types. To convert the supported data types into other Flux basic data types, use Flux type conversion functions.

Parameterized query example:

client = InfluxDB2::Client.new('https://localhost:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org')
query = 'from(bucket: params.bucketParam) |> range(start: duration(v: params.startParam))'
params = { 'bucketParam' => 'my-bucket', 'startParam' => '-1h' }
query_api = client.create_query_api
result = query_api.query(query: query, params: params)
result[0].records.each { |record| puts "#{record.time} #{record.measurement}: #{record.field} #{record.value}" }

The supports synchronous and batching writes into InfluxDB 2.x. 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 = 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:8086', 'my-token',
                              bucket: 'my-bucket',
                              org: 'my-org',

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. Data Point structure
4. Array of above items

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' },
         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])

Default Tags

Sometimes is useful to store same information in every measurement e.g. hostname, location, customer. The client is able to use static value, app settings or env variable as a tag value.

• 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))

Delete data

The supports deletes points 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. DateTime - DateTime.rfc3339('2019-03-03T04:05:06+07:00')
3. Time - Time.utc(2015, 10, 16, 8, 20, 15)

Management API

The client supports following management API:

The following example demonstrates how to use a InfluxDB 2.x Management API to create new bucket. For further information see docs and .

# This is an example how to create new bucket with permission to write.
#
# You could run example via: `cd apis && bundle exec ruby ../examples/create_new_bucket.rb`
#
$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
require 'influxdb-client'
$LOAD_PATH.unshift File.expand_path('../apis/lib', __dir__)
require 'influxdb-client-apis'
url = 'http://localhost:8086'
bucket = 'my-bucket'
org = 'my-org'
token = 'my-token'
client = InfluxDB2::Client.new(url,
                               token,
                               bucket: bucket,
                               org: org,
                               use_ssl: false,
                               precision: InfluxDB2::WritePrecision::NANOSECOND)
api = InfluxDB2::API::Client.new(client)
# Find my organization
organization = api.create_organizations_api
                  .get_orgs
                  .orgs
                  .select { |it| it.name == 'my-org' }
                  .first
#
# Create new Bucket
#
retention_rule = InfluxDB2::API::RetentionRule.new(type: 'expire', every_seconds: 3600)
bucket_name = 'new-bucket-name'
request = InfluxDB2::API::PostBucketRequest.new(org_id: organization.id,
                                                name: bucket_name,
                                                retention_rules: [retention_rule])
bucket = api.create_buckets_api
            .post_buckets(request)
#
# Create Permission to read/write from Bucket
#
resource = InfluxDB2::API::Resource.new(type: 'buckets',
                                        id: bucket.id,
                                        org_id: organization.id)
authorization = InfluxDB2::API::Authorization.new(description: "Authorization to read/write bucket: #{bucket.name}",
                                                  org_id: organization.id,
                                                  permissions: [
                                                    InfluxDB2::API::Permission.new(action: 'read', resource: resource),
                                                    InfluxDB2::API::Permission.new(action: 'write', resource: resource)
                                                  ])
result = api.create_authorizations_api
            .post_authorizations(authorization)
print("The token: '#{result.token}' is authorized to read/write from/to bucket: '#{bucket.name}'.")
client.close!

• sources - create_new_bucket.rb

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

Proxy configuration

You can configure the client to tunnel requests through an HTTP proxy. To configure the proxy use a http_proxy environment variable.

Client automatically follows HTTP redirects. The default redirect policy is to follow up to 10 consecutive requests. You can configure redirect counts by the client property: max_redirect_count.

Due to a security reason Authorization header is not forwarded when redirect leads to a different domain. To overcome this limitation you have to set the client property redirect_forward_authorization to true.

InfluxDB 1.8 API compatibility

InfluxDB 1.8.0 introduced forward compatibility APIs for InfluxDB 2.x. This allow you to easily move from InfluxDB 1.x to InfluxDB 2.x Cloud or open source.

The following forward compatible APIs are available:

For detail info see .

Local tests

brew install wget # on a mac, if not yet installed!

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

License