Write InfluxDB Flux queries in an ORM fashion with Ruby.

• 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

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

Here are some utility methods provided by the gem.

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)

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

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)

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.

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.

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

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

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)

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

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

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

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

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)

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

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

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

data.increase

# data
#   |> increase()

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)

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

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

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

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]
#   )

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)

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

data.median

# data
#   |> median()

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

TBD

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

data.cumulative_sum

# data
#   |> cumulativeSum()

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

data.first

# data
#   |> first()

data.last

# data
#   |> last()

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.

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

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