influx

Ruby InfluxDB Flux

Write InfluxDB Flux queries in an ORM fashion with Ruby.

Table of contents

• Table of contents
• Installation
• Utilities
  • Now
• Flux points
• Flux queries
  • From
  • Range
• Query data with Flux
  • From
  • Range
  • Query fields and tags
  • Group
  • Sort and limit
  • Window & aggregate
  • Increase
  • Moving Average
  • Rate
  • Histograms
  • Fill
  • Median
  • Percentile & quantile
  • Join (TBD)
  • Cumulative sum
  • First & last
• Contributing
• License
• Code of Conduct

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add influx

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install influx

Utilities

Here are some utility methods provided by the gem.

Now

The gem provides a method to return the Clock timestamp in nanoseconds.

Influx.now # Default precision is Nanoseconds

You can also pass other precisions if needed:

Influx.now(:second)
Influx.now(:millisecond)
Influx.now(:microsecond)
Influx.now(:nanosecond)

Flux points

Influx::Point.new(
  'h2o', # measurement
  tags: { location: 'west' },
  fields: { value: 33 },
  time: Influx.now # The default value is Influx.now, you can also use Time or Integer
).to_flux # h2o,location=west value=33 1652720908000000

Flux queries

The gem acts as an ORM therefore you can chain methods to build your Flux query string.

You can always call the to_flux method to see a preview or your query:

flux_query = Influx.from(bucket: 'my-bucket').range(start: '-1d')
flux_query.to_flux # from(bucket: "my-bucket") |> range(start: -1d)

From

The from method is the starting point of all queries, it allows you to specify the InfluxDB bucket.

Influx.from(bucket: 'my-bucket')

⚠️ This is mandatory to perform any query.

Range

The range method allows you to specify the time-range you want to query.

Influx.from(bucket: 'my-bucket').range(start: '-1d', stop: 'now()')

It supports the Flux sytanx as well as Time.

Influx.from(bucket: 'my-bucket').range(start: Time.new.yesterday, stop: Time.new)

⚠️ This is mandatory to perform any query.

Query data with Flux

The following guides are based on top of the original InfluxData Flux Documentation, available here.

Example data variable Many of the examples provided in the following guides use a data variable, which represents a basic query that filters data by measurement and field. data is defined as:

data = Influx.from(bucket: 'my-bucket').range(start: '-1d', stop: 'now()')

# from(bucket: "my-bucket")
#   |> range(start: -1d, stop: now())

From

The from method allows you to specify the InfluxDB bucket. Every query starts with the from method.

Influx.from(bucket: 'my-bucket')

# from(bucket: "my-bucket")

Range

The range method allows you to bind your query to a time range, it supports native Flux syntax as well as the Ruby Time class and Integer.

Influx.from(bucket: 'my-bucket').range(start: '-1d', stop: 'now()')

# from(bucket: "my-bucket")
#   |> range(start: -1d, stop: now())

Influx.from(bucket: 'my-bucket').range(start: Time.new(2018, 1, 1, 0, 0, 0, '+00:00').utc, stop: 1514768400)

# from(bucket: "my-bucket")
#   |> range(start: 2018-01-01T00:00:00Z, stop: 2018-01-01T01:00:00Z)

Query fields and tags

Use filter() to query data based on fields, tags, or any other column value.

data.filter("_measurement": "example-measurement", tag: "example-tag")

# data
#   |> filter(fn: (r) => r._measurement == "example-measurement" and r.tag == "example-tag")

Group

Use group() to group data with common values in specific columns.

data.group(columns: ["host"], mode: "by")

# data
#   |> group(columns: ["host"], mode: "by")

Sort and limit

Use sort() to order records within each table by specific columns and limit() to limit the number of records in output tables to a fixed number, n.

data.sort(columns: ["host", "_value"]).limit(4)

# data
#   |> sort(columns: ["host","_value"])
#   |> limit(n: 4)

Window & aggregate

data.aggregate_window(every: "20m", fn: "mean")

# data
#   |> aggregateWindow(every: 20m, fn: mean)

Increase

Use increase() to track increases across multiple columns in a table.

data.increase

# data
#   |> increase()

Moving Average

Use moving_average() or timed_moving_average() to return the moving average of data.

data.moving_average(5)

# data
#   |> movingAverage(n: 5)

data.timed_moving_average(every: "2m", period: "4m")

# data
#   |> timedMovingAverage(every: 2m, period: 4m)

Rate

Use derivative() to calculate the rate of change between subsequent values.

data.derivative(unit: "1m", non_negative: true)

# data
#   |> derivative(unit: 1m, nonNegative: true)

Histograms

Use histogram() to create cumulative histograms with Flux.

data.histogram(column: "_value", upper_bound_column: "le", count_column: "_value", bins: [100.0, 200.0, 300.0, 400.0])

# data
#   |> histogram(
#     column: "_value",
#     upperBoundColumn: "le",
#     countColumn: "_value",
#     bins: [100.0,200.0,300.0,400.0]
#   )

Fill

Use fill() function to replace null values.

data.fill(use_previous: true)

# data
#   |> fill(usePrevious: true)

data.fill(value: 0.0)
# data
#   |> fill(value: 0.0)

Median

Use median() to return a value representing the 0.5 quantile (50th percentile) or median of input data.

data.median

# data
#   |> median()

Percentile & quantile

Use the quantile() function to return all values within the q quantile or percentile of input data.

data.quantile(q: 0.99, method: "estimate_tdigest")

# data
#   |> quantile(q: 0.99, method: "estimate_tdigest")

Join (TBD)

TBD

Cumulative sum

Use the cumulativeSum() function to calculate a running total of values.

data.cumulative_sum

# data
#   |> cumulativeSum()

First & last

Use first() or last() to return the first or last point in an input table.

data.first

# data
#   |> first()

data.last

# data
#   |> last()

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/influx. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Influx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.