TempoDB .NET API Client

The TempoDB .NET API Client makes calls to the TempoDB API.

1. Download tempodb.

• From NuGet
• From source git clone https://github.com/tempodb/tempodb-net

2. After downloading tempodb, add the csproj file to your solution and add the reference to "Client" in your custom project.

Classes

Client

Stores the session information for authenticating and accessing TempoDB. Your api key and secret is required. The Client also allows you to specify the hostname, port, and protocol (http or https). This is used if you are on a private cluster.

Constructor

Client(key, secret, host, port, version, secure, restClient)

• key - api key (string)
• secret - api secret (string)
• host - [Optional] hostname for cluster (string)
• port - [Optional] port for the cluster (int)
• secure - [Optional] protocol to use (true=https, false=http)
• restClient - [Optional] rest client to use. Mainly used for testing.

var client = new Client("my-key", "my-secret");

All access to data is made through a client instance.

DataPoint

Represents one timestamp/value pair.

Constructor

var dp = new DataPoint(new DateTime(2013, 1, 1), 10.0); // Or
var dp2 = new DataPoint
{
  Timestamp = new DateTime(2013, 1, 1),
  Value = 10.0
};

Members

• Timestamp - timestamp (DateTime)
• Value - the datapoint's value (double)

Series

Represents metadata associated with the series. Each series has a globally unique id that is generated by the system and a user defined key. The key must be unique among all of your series. Each series may have a set of tags and attributes that can be used to filter series during bulk reads. Attributes are key/value pairs. Both the key and attribute must be strings. Tags are keys with no values. Tags must also be strings.

Constructor

var series = new Series
{
  Id = "series-id",
  Key = "series-key",
  Tags = new List<string> { "tag1", "tag2" },
  Attributes = new Dictionary<string,string> { { "key", "val" } }
};

Members

• Id - unique series id (string)
• Key - user defined key (string)
• Name - human readable name for the series (string)
• Attributes - key/value pairs providing metadata for the series (dictionary - keys and values are strings)
• Tags - (list of strings)

DataSet

Represents data from a time range of a series. This is essentially a list of DataPoints with some added metadata. This is the object returned from a query. The DataSet contains series metadata, the start/end times for the queried range, a list of the DataPoints and a statistics summary table. The Summary table contains statistics for the time range (sum, mean, min, max, count, etc.)

Members

• Series - Series metadata object (Series)
• Start - start time for the queried range (DateTime)
• End - end time for the queried range (DateTime)
• Data - datapoints ( List )
• Summary - a summary table of statistics for the queried range ( Dictionary<string, double> )

Bulk Writes

The Bulk classes exist to facilitate using the bulk write endpoint, which provides the ability to write to multiple series per timestamp.

BulkPoint

An abstract base class for the bulk data points is used, as well as 2 concrete implementations.

• BulkKeyPoint - Used to write a datapoint to a series by series key
• BulkIdPoint - Used to write a datapoint to a series by series id

Constructor

BulkPoint bpkey = new BulkKeyPoint("key", 10.0);
BulkPoint bpid = new BulkIdPoint("id", 10.0);

Members

• Value - [Common] datapoint's value (double)
• Key - [BulkKeyPoint] key of series being written to (string)
• Id - [BulkIdPoint] id of series being written to (string)

BulkDataSet

The object that represents a bulk write and is serialized and sent to the server.

Members

• Timestamp - timestamp for bulk write (DateTime)
• Data - list of bulk points ( List data )

Client API

Client instance members

public Series CreateSeries(string key = "")
public Series UpdateSeries(Series series)
public Series GetSeriesByKey(string key)
public Series GetSeriesById(string id)
public List<Series> ListSeries(Filter filter = null)
public void WriteById(string seriesId, IList<DataPoint> data)
public void WriteByKey(string seriesKey, IList<DataPoint> data)
public void WriteBulkData(BulkDataSet dataSet)
public void WriteMultiData(List<MultiPoint> data)
public void IncrementById(string seriesId, IList<DataPoint> data)
public void IncrementByKey(string seriesKey, IList<DataPoint> data)
private void IncrementDataPoints(string seriesProperty, string propertyValue, IList<DataPoint> data)
public void IncrementMultiData(List<MultiPoint> data)
public void DeleteById(string seriesId, DateTime start, DateTime end)
public void DeleteByKey(string seriesKey, DateTime start, DateTime end)
public DataSet ReadById(string seriesId, DateTime start, DateTime end, string interval = null, string function = null)
public DataSet ReadByKey(string seriesKey, DateTime start, DateTime end, string interval = null, string function = null)

CreateSeries(string key="")

Creates and returns a series object, optionally with the given key.

Parameters

• key - [Optional] key for the series (string)

Returns

The newly created Series object

Example

The following example creates two series, one with a given key of "my-custom-key", one with a randomly generated key.

var client = new Client("api-key", "api-secret");

var series1 = client.CreateSeries('my-custom-key');
var series2 = client.CreateSeries();

GetSeriesById(string id)

Gets a specific series object.

Parameters

• id - Series id (string)

Returns

A Series object

Example

The following example returns the series with the id: series-id

var client = new Client("api-key", "api-secret");
var series  = client.GetSeriesById("series-id");

GetSeriesByKey(string key)

Gets a specific series object.

Parameters

• key - Series key (string)

Returns

A Series object

Example

The following example returns the series with the key: series-key.

var client = new Client("api-key", "api-secret");
var series  = client.GetSeriesByKey("series-key");

ListSeries(Filter filter = null)

Returns a list of series based on a Filter object.

Using the Filter class you can construct a filter based on:

• IDs
• Tags
• Attributes

Parameters

• Filter - [Optional] Filter object (Filter)

Returns

A list of series that match the criteria

Example

This will return the series' tagged with "tag" and with the attribute { "key", "val" }

var client = new Client("api-key", "api-secret");

var filter = new Filter();
filter.AddTag("tag");
filter.AddAttribute("key", "val");

var series = client.ListSeries(filter);

UpdateSeries(Series series)

Updates a series. The series id is taken from the passed-in series object. Currently, only tags and attributes can be modified. The easiest way to use this method is through a read-modify-write cycle.

Parameters

• series - the post updated series (Series)

Returns

The updated Series

Example

The following example reads the list of series with key test1 and replaces the tags with tag3.

var client = new Client("api-key", "api-secret");

var series = client.GetSeriesByKey("test1") ;
series.Tags.Append("tag3");

client.UpdateSeries(series);

##ReadById(string seriesId, DateTime start, DateTime end, string interval = null, string function = null) Gets a DataSet for the specified start/end times. The interval parameter allows you to specify a rollup period. For example, "1hour" will roll the data up on the hour using the provided function. The function parameter specifies the folding function to use while rolling the data up. A rollup is selected automatically if no interval or function is given. The auto rollup interval is calculated by the total time range (end - start) as follows:

• range <= 2 days - raw data is returned
• range <= 30 days - data is rolled up on the hour
• else - data is rolled up by the day

Rollup intervals are specified by a number and a time period. For example, 1day or 5min. You should use the static class IntervalParameter for this operation. Supported time periods:

• min
• hour
• day
• month
• year

Supported rollup functions, You should use the static class FoldingFunction to address these:

• sum
• max
• min
• avg or mean
• stddev (standard deviation)
• count

You can also retrieve raw data by specifying "raw" as the interval. The series to query can be filtered using the remaining parameters.

Parameters

• seriesId - the seriesId to include (string)
• start - start time for the query (DateTime)
• end - end time for the query (DateTime)
• interval - the rollup interval (string)
• function - the rollup folding function (string)

Returns

A DataSet

Example

The following example returns a DataSet from 2012-01-01 to 2012-01-02 for the series with id "38268c3b231f1266a392931e15e99231", with the maximum value for each hour as well as the raw data.

var client = new Client("api-key", "api-secret");

var resultsRolledUp = client.ReadById("38268c3b231f1266a392931e15e99231", new DateTime(2012, 1, 1), new DateTime(2012, 1, 2), IntervalParameter.Hour(1), FoldingFunction.Max);
var resultsRaw = client.ReadById("38268c3b231f1266a392931e15e99231", new DateTime(2012, 1, 1), new DateTime(2012, 1, 2));

ReadByKey(string seriesId, DateTime start, DateTime end, string interval = null, string function = null)

Gets a DataSet by series key. The key, start, and end times are required. The same rollup rules apply as for the ReadByKey read (above).

Parameters

• seriesKey - key for the series to read from (string)
• start - start time for the query (DateTime)
• end - end time for the query (DateTime)
• interval - the rollup interval (string)
• function - the rollup folding function (string)

Returns

A DataSet

Example

The following example reads data for the series with id "my-key" from 2012-01-01 to 2012-02-01 and returns a minimum datapoint per day.

var client = new Client("api-key", "api-secret");
var data = client.ReadByKey("my-key", new DateTime(2012, 1, 1), new DateTime(2012, 2, 1), IntervalParameters.Days(1), FoldingFunction.Min);

WriteById(string seriesId, IList data)

Writes datapoints to the specified series. The series id and a list of DataPoints are required.

Parameters

• seriesId - id for the series to write to (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example write three datapoints to the series with id "38268c3b231f1266a392931e15e99231".

var client = new Client("api-key", "api-secret");

var data = new List<DataPoint>
{
  new DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
  new DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
  new DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
};
client.WriteById("38268c3b231f1266a392931e15e99231", data);

WriteByKey(string seriesKey, IList data)

Writes datapoints to the specified series. The series key and a list of DataPoints are required. Note: a series will be created if the provided key does not exist. Otherwise usage is identical to WriteById.

Parameters

• seriesKey - key for the series to write to (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example write three datapoints to the series with key "my-custom-key".

var client = new Client("api-key", "api-secret");

var data = new List<DataPoint>
{
  new DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
  new DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
  new DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
};
client.WriteByKey("my-custom-key", data);

WriteBulkData(BulkDataSet dataSet)

Writes values to multiple series for a particular timestamp. This function takes a BulkDataSet which contains a timetstamp and list of BulkPoints.

Parameters

• dataSet - a bulk data set representing a timestamp and multiple values (BulkDataSet)

Returns

Nothing

Example

The following example writes datapoints to four separate series (2 by id, 2 by key) at the same timestamp.

var client = new Client("api-key", "api-secret");

var data = new List<BulkPoint>
{
  new BulkIdPoint("38268c3b231f1266a392931e15e99231", 20.31),
  new BulkIdPoint("c3b23826836a391f12629392311e15e9", 13.351),
  new BulkKeyPoint("my-key-1", 0.631),
  new BulkKeyPoint("my-key-2", 612.23)
};
var bulkSet = new BulkDataSet(new DateTime(2012, 1, 1), data);

client.WriteBulkData(bulkSet);

WriteMultiData(List data)

Writes values to multiple series for multiple timestamps. This function takes a List of MultiPoints each of which contain a timetstamp, a value, and a key or id.

Parameters

• data - The List of MultiPoints

Returns

Nothing

Example

The following example writes datapoints to four separate series (2 by id, 2 by key) at the different timestamps.

var client = new Client("api-key", "api-secret");

var data = new List<MultiPoint>
{
  new MultiIdPoint(new DateTime(2013, 1, 1), "38268c3b231f1266a392931e15e99231", 20.31),
  new MultiIdPoint(new DateTime(2013, 1, 2), "c3b23826836a391f12629392311e15e9", 13.351),
  new MultiKeyPoint(new DateTime(2013, 1, 3), "my-key-1", 0.631),
  new MultiKeyPoint(new DateTime(2013, 1, 4), "my-key-2", 612.23)
};

client.WriteMutliData(data);

IncrementById(string seriesId, IList data)

Increments the value of the specified series at the given timestamp. The value of the datapoint is the amount to increment. This is similar to a write. However the value is incremented by the datapoint value instead of overwritten. Values are incremented atomically, so this is useful for counting events. The series id and a list of DataPoints are required.

Parameters

• seriesId - id for the series to increment (string)
• data - the data to increment (list of DataPoints)

Returns

Nothing

Example

The following example increments three datapoints to the series with id "38268c3b231f1266a392931e15e99231".

var client = new Client("api-key", "api-secret");

var data = new List<DataPoint>
{
  new DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
  new DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
  new DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
};
client.IncrementById("38268c3b231f1266a392931e15e99231", data);

IncrementByKey(string seriesKey, IList data)

Increments the value of the specified series at the given timestamp. The value of the datapoint is the amount to increment. This is similar to a write. However, the value is incremented by the datapoint value instead of overwritten. Values are incremented atomically, so this is useful for counting events. The series key and an array of DataPoints are required. Note: a series will be created if the provided key does not exist.

Parameters

• seriesKey - key for the series to increment (string)
• data - the data to increment (list of DataPoints)

Returns

Nothing

Example

The following example increments three datapoints to the series with key "my-custom-key".

var client = new Client("api-key", "api-secret");

var data = new List<DataPoint>
{
  new DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
  new DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
  new DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
};
client.IncrementByKey("my-custom-key", data);

IncrementBulkData(BulkDataSet dataSet)

Increments values to multiple series for a particular timestamp. This function takes a BulkDataSet which contains a timestamp and list of BulkPoints.

Parameters

• dataSet - a bulk data set representing a timestamp and multiple values (BulkDataSet)

Returns

Nothing

Example

The following example increments datapoints to four separate series (2 by id, 2 by key) at the same timestamp.

var client = new Client("api-key", "api-secret");

var data = new List<BulkPoint>
{
  new BulkIdPoint("38268c3b231f1266a392931e15e99231", 20.31),
  new BulkIdPoint("c3b23826836a391f12629392311e15e9", 13.351),
  new BulkKeyPoint("my-key-1", 0.631),
  new BulkKeyPoint("my-key-2", 612.23)
};
var bulkSet = new BulkDataSet(new DateTime(2012, 1, 1), data);

client.IncrementBulkData(bulkSet);

IncrementMultiData(List data)

Increments values to multiple series for multiple timestamps. This function takes a List of MultiPoints each of which contain a timetstamp, a value, and a key or id.

Parameters

• data - The List of MultiPoints

Returns

Nothing

Example

The following example increments datapoints to four separate series (2 by id, 2 by key) at the different timestamps.

var client = new Client("api-key", "api-secret");

var data = new List<MultiPoint>
{
  new MultiIdPoint(new DateTime(2013, 1, 1), "38268c3b231f1266a392931e15e99231", 20),
  new MultiIdPoint(new DateTime(2013, 1, 2), "c3b23826836a391f12629392311e15e9", 13),
  new MultiKeyPoint(new DateTime(2013, 1, 3), "my-key-1", 6),
  new MultiKeyPoint(new DateTime(2013, 1, 4), "my-key-2", 63)
};

client.IncrementMultiData(data);

DeleteById(string seriesId, DateTime start, DateTime end)

Deletes a range of data specified by series id. The id, start, and end times are required. As with the read api, the start datetime is inclusive and the end datetime is exclusive. i.e. [start, end).

Parameters

• seriesId - id for the series to delete from (string)
• start - start time for the query (DateTime, inclusive)
• end - end time for the query (DateTime, exclusive)

Returns

Nothing

Example

The following example deletes data for the series with id "38268c3b231f1266a392931e15e99231" from 2012-01-01 to 2012-02-01.

var client = new Client("api-key", "api-secret");
client.DeleteById("38268c3b231f1266a392931e15e99231", new DateTime(2012, 1, 1), new DateTime(2012, 2, 1);

DeleteByKey(string serieskey, DateTime start, DateTime end)

Deletes a range of data specified by series key. The key, start, and end times are required. As with the read api, the start datetime is inclusive and the end datetime is exclusive. i.e. [start, end).

Parameters

• seriesKey - key for the series to delete from (string)
• start - start time for the query (DateTime, inclusive)
• end - end time for the query (DateTime, exclusive)

Returns

Nothing

Example

The following example deletes data for the series with key "my-key" from 2012-01-01 to 2012-02-01.

var client = new Client("api-key", "api-secret");
client.DeleteByKey("my-key", new DateTime(2012, 1, 1), new DateTime(2012, 2, 1);

DeleteSeries(Filter filter)

Delete series objects by the given filter object. Series can be deleted by id, key, tag and attribute. You must specify at least one filter query param for deletion. If you want to truncate your database (remove all series), you can use the DeleteAllSeries method.

Parameters

• Filter object (Filter)

Returns

A DeleteSummary object that represents the delete operation, the value deleted is the number of series deleted.

Example

The following example deletes two series with the key's "key1" and "key2"

var client = new Client("api-key", "api-secret");
var filter = new Filter();
filter.AddKey("key1");
filter.AddKey("key2");
var summary = client.DeleteSeries(filter);
Console.WriteLine("Number of series deleted: " + summary.deleted);

DeleteAllSeries()

Delete all series in your database

Parameters

• None

Returns

A DeleteSummary object that represents the delete operation, the value deleted is the number of series deleted. This should be the total count of all your series

Example

The following example deletes all series

var client = new Client("api-key", "api-secret");
var summary = client.DeleteAllSeries();
Console.WriteLine("Number of series deleted: " + summary.deleted);