knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.path = "README-" ) Sys.setenv(LANG = "en")
R interface to InfluxDB
This package allows you to fetch and write time series data from/to an InfluxDB server. Additionally, handy wrappers for the Influx Query Language (IQL) to manage and explore a remote database are provided.
Installation is easy thanks to CRAN:
install.packages("influxdbr")
You can install the dev version from github with:
# install.packages("remotes") remotes::install_github("dleutnant/influxdbr")
This is a basic example which shows you how to communicate (i.e. query and write data) with the InfluxDB server.
library(dplyr) library(influxdbr) library(xts)
Let's create first some sample data from the xts package and assign arbitrary attributes:
# attach data "sample_matrix" data("sample_matrix") # create xts object xts_data <- xts::as.xts(x = sample_matrix) # assign some attributes xts::xtsAttributes(xts_data) <- list(info = "SampleDataMatrix", UnitTesting = TRUE, n = 180, source = "xts") # print structure to inspect the object str(xts_data)
To connect to an InfluxDB server, we need a connection object. A connection object
can be created by providing usual server details (e.g. host
, port
, ...) or with
help of a group file, which conveniently holds all information for us (s. package
documentation):
# create connection object # (here: based on a config file with group "admin" in it (s. package documentation)) con <- influx_connection(group = "admin")
The influxdbr
package provides handy wrappers to manage a remote InfluxDB:
# create new database create_database(con = con, db = "mydb") # list all databases show_databases(con = con) %>% filter(name == "mydb") # show the db created above only
Writing an xts-object to the server can be achieved with influx_write
. In this
case, columnnames of the xts
object are used as InfluxDB's field keys,
xts
's coredata represent field values. Attributes are preserved and written
as tag keys and values, respectively.
# write example xts-object to database influx_write(con = con, db = "mydb", x = xts_data, measurement = "sampledata")
Writing a data.frame (or tibble) to the server can also be achieved with
influx_write
. In this case, we need to specify which columns of the data.frame
represent time and tags. Fields are automatically determined.Each row represents
a unique data point. NA
's are not supported and need to be removed.
Timestamps should be located in column time
.
Remember that time and tags are optional: InfluxDB uses the server’s local nanosecond timestamp in UTC if the timestamp is not included with the point.
# convert the existing xts-object to data.frame df_data <- dplyr::bind_cols(time = zoo::index(xts_data), # timestamp data.frame(xts_data)) %>% # coredata dplyr::mutate(info = "SampleDataMatrix", # add tag 'info' UnitTesting = TRUE, # add tag 'UnitTesting' n = row_number(), # add tag 'n' source = "df") # add source 'df' df_data # write example data.frame to database influx_write(con = con, db = "mydb", x = df_data, time_col = "time", tag_cols = c("info", "UnitTesting", "n", "source"), measurement = "sampledata")
We can now check if the time series were successfully written:
# check if measurements were succefully written show_measurements(con = con, db = "mydb")
To query the database, two functions influx_query
and influx_select
are available.
influx_select
wraps around influx_query
and can be useful for simple requests
because it provides default query parameters. The return type can be configured
to be of class tibble
or of class xts
.
If return_xts = FALSE
a list of tibbles per query statement is returned. Each tibble contains columns with statement_id, series_names, tags, time and fields.
# fetch time series data by using the helper function `influx_select` result <- influx_select(con = con, db = "mydb", field_keys = "Open, High", measurement = "sampledata", where = "source = 'df'", group_by = "*", limit = 10, order_desc = TRUE, return_xts = FALSE) result
If return_xts = TRUE
a list of xts objects per query statement is returned. Because xts objects are basically matrices (which can store one data type only), a single xts object is created for each InfluxDB field. This ensures a correct representation of the field values data type (instead of getting all into a "character" matrix). InfluxDB tags are now xts attributes.
# fetch time series data by using the helper function `influx_select` result <- influx_select(con = con, db = "mydb", field_keys = "Open, High", measurement = "sampledata", where = "source = 'xts'", group_by = "*", limit = 10, order_desc = TRUE, return_xts = TRUE) str(result)
In case the InfluxDB response is expected to be a single series only,
we can flatten the list (simplifyList = TRUE
) to directly get to the data.
This enhances a pipeable work flow.
result <- influx_select(con = con, db = "mydb", field_keys = "Open", measurement = "sampledata", where = "source = 'df'", group_by = "*", limit = 10, order_desc = TRUE, return_xts = FALSE, simplifyList = TRUE) str(result)
This Git repository contains the latest contributions to the R package influxdbr
and other code that will appear in the next CRAN release.
Contributing to this package is easy. Just send a pull request. Your PR should pass R CMD check --as-cran
, which will also be checked by Travis CI when the PR is submitted.
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
citation("influxdbr")
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.