InfluxData.Net

Compatible with InfluxDB v1.3.x and Kapacitor v1.0.0 API's

NOTE: The library will most probably work just as fine with newer versions of the TICK stack as well but it hasn't been tested against them.

InfluxData.Net is a portable .NET library to access the REST API of an InfluxDB database and Kapacitor processing tool.

The library supports .Net Framework v4.6.1 and .Net Standard v2.0 (which implies .Net Core 2.0).

InfluxDB is the data storage layer in InfluxData's TICK stack which is an open-source end-to-end platform for managing time-series data at scale.

Kapacitor is a data processing engine. It can process both stream (subscribe realtime) and batch (bulk query) data from InfluxDB. Kapacitor lets you define custom logic to process alerts with dynamic thresholds, match metrics for patterns, compute statistical anomalies, etc.

Support for other TICK stack layers is also planned and will be implemented in the future when they become stable from InfluxData side.

Original Lib

This is a fork of InfluxDb.Net, (which is in turn a fork of InfluxDb.Net).

Support for older versions

Currently older supported versions:

• InfluxDB: v0.9.2, v0.9.6, v1.0.0, v1.3.x
• Kapacitor: v0.10.0, v0.10.1, v1.0.0

Table of contents

• Installation
• Usage
  • API reference
• InfluxDbStudio management tool
• Bugs & feature requests
• Contributing
• License
• Changelog

Installation

You can download the InfluxData.Net Nuget package to install the latest version of InfluxData.Net Lib.

Usage

To use InfluxData.Net InfluxDbClient you must first create an instance of InfluxDbClient:

var influxDbClient = new InfluxDbClient("http://yourinfluxdb.com:8086/", "username", "password", InfluxDbVersion.v_1_3);

Additional, optional params for InfluxDbClient are a custom HttpClient if you think you need control over it, and throwOnWarning which will throw an InfluxDataWarningException if the InfluxDb API returns a warning as a part of the response. That should preferably be used only for debugging purposes.

To use InfluxData.Net KapacitorClient you must first create an instance of KapacitorClient (Kapacitor doesn't support authentication yet, so use this overload for now):

var kapacitorClient = new KapacitorClient("http://yourkapacitor.com:9092/", KapacitorVersion.v_1_0_0);

Clients modules (properties of Client object) can then be consumed and methods for communicating with InfluxDb/Kapacitor can be consumed.

If needed, a custom HttpClient can be used for making requests. Simply pass it into the InfluxDbClient or KapacitorClient as the last (optional) parameter.

Supported InfluxDbClient modules and API calls <a name="api-reference"></a>

• Client
  • WriteAsync()
  • QueryAsync()
  • QueryChunkedAsync()
  • MultiQueryAsync()
  • MultiQueryChunkedAsync()
• Database
  • CreateDatabaseAsync()
  • GetDatabasesAsync()
  • DropDatabaseAsync()
• User
  • CreateUserAsync()
  • GetUsersAsync()
  • DropUserAsync()
  • SetPasswordAsync()
  • GetPrivilegesAsync()
  • GrantAdministratorAsync()
  • RevokeAdministratorAsync()
  • GrantPrivilegeAsync()
  • RevokePrivilegeAsync()
• ContinuousQuery
  • CreateContinuousQueryAsync()
  • GetContinuousQueriesAsync()
  • DeleteContinuousQueryAsync()
  • BackfillAsync()
• Serie
  • GetSeriesAsync()
  • DropSeriesAsync()
  • GetMeasurementsAsync()
  • DropMeasurementAsync()
  • GetTagKeysAsync()
  • GetTagValuesAsync()
  • GetFieldKeysAsync()
  • CreateBatchWriter()
    • Start()
    • AddPoint()
    • AddPoints()
    • Stop()
    • OnError()
    • SetMaxBatchSize()
• Retention
  • CreateRetentionPolicyAsync()
  • GetRetentionPoliciesAsync()
  • AlterRetentionPolicyAsync()
  • DropRetentionPolicyAsync()
• Diagnostics
  • PingAsync()
  • GetStatsAsync()
  • GetDiagnosticsAsync()
• Helpers
  • serie.As<T>()

Supported KapacitorClient modules and API calls

• Task
  • GetTaskAsync()
  • GetTasksAsync()
  • DefineTaskAsync()
  • DeleteTaskAsync()
  • EnableTaskAsync()
  • DisableTaskAsync()

InfluxDbClient

Client Module

Can be used to do the most basic operations against InfluxDb API.

WriteAsync

To write new data into InfluxDb, a Point object must be created first:

var pointToWrite = new Point()
{
    Name = "reading", // serie/measurement/table to write into
    Tags = new Dictionary<string, object>()
    {
        { "SensorId", 8 },
        { "SerialNumber", "00AF123B" }
    },
    Fields = new Dictionary<string, object>()
    {
        { "SensorState", "act" },
        { "Humidity", 431 },
        { "Temperature", 22.1 },
        { "Resistance", 34957 }
    },
    Timestamp = DateTime.UtcNow // optional (can be set to any DateTime moment)
};

Point is then passed into Client.WriteAsync method together with the database name:

var response = await influxDbClient.Client.WriteAsync(pointToWrite, "yourDbName");

If you would like to write multiple points at once, simply create an IEnumerable collection of Point objects and pass it into the second WriteAsync overload:

var response = await influxDbClient.Client.WriteAsync(pointsToWrite, "yourDbName");

QueryAsync

The Client.QueryAsync can be used to execute any officially supported InfluxDb query:

var query = "SELECT * FROM reading WHERE time > now() - 1h";
var response = await influxDbClient.Client.QueryAsync(query, "yourDbName"[, epochFormat = null][, ]);

The second QueryAsync overload will return the result of multiple queries executed at once. The response will be a flattened collection of multi-results series. This means that the resulting series from all queries will be extracted into a single collection. This has been implemented to make it easier on the developer in case he is querying the same measurement with different params multiple times at once.

var queries = new []
{
    "SELECT * FROM reading WHERE time > now() - 1h",
    "SELECT * FROM reading WHERE time > now() - 2h"
}
var response = await influxDbClient.Client.QueryAsync(queries, "yourDbName");

Chunked QueryAsync and MultiQueryAsync

Check the usage here.

Parameterized QueryAsync

With support for parameterized queries (#61), InfluxDB can also be queried in the following manner:

var serialNumber = "F2EA2B0CDFF";
var queryTemplate = "SELECT * FROM cpuTemp WHERE \"serialNumber\" = @SerialNumber";

var response = await influxDbClient.Client.QueryAsync(
    queryTemplate: queryTemplate,
    parameters: new
    {
        @SerialNumber = serialNumber
    },
    dbName: "yourDbName"
);

MultiQueryAsync

MultiQueryAsync also returns the result of multiple queries executed at once. Unlike the second QueryAsync overload, the results will not be flattened. This method will return a collection of results where each result contains the series of a corresponding query.

var queries = new []
{
    "SELECT * FROM reading WHERE time > now() - 1h",
    "SELECT * FROM reading WHERE time > now() - 2h"
}
var response = await influxDbClient.Client.MultiQueryAsync(queries, "yourDbName");

MultiQueryChunkedAsync

Check the usage here.

Database Module

The database module can be used to manage the databases on the InfluxDb system.

CreateDatabaseAsync

You can create a new database in the following way:

var response = await influxDbClient.Database.CreateDatabaseAsync("newDbName");

GetDatabasesAsync

Gets a list of all databases accessible to the current user:

var response = await influxDbClient.Database.GetDatabasesAsync();