net.opentsdb.core

Interface Query

public interface Query

A query to retreive data from the TSDB.

Method Summary

Methods

Modifier and Type	Method and Description
void	downsample(long interval, Aggregator downsampler) Downsamples the results by specifying a fixed interval between points.
long	getEndTime() Returns the end time of the graph.
long	getStartTime() Returns the start time of the graph.
DataPoints[]	run() Runs this query.
com.stumbleupon.async.Deferred<DataPoints[]>	runAsync() Executes the query asynchronously
void	setEndTime(long timestamp) Sets the end time of the graph.
void	setStartTime(long timestamp) Sets the start time of the graph.
void	setTimeSeries(List<String> tsuids, Aggregator function, boolean rate) Sets up a query for the given timeseries UIDs.
void	setTimeSeries(List<String> tsuids, Aggregator function, boolean rate, RateOptions rate_options) Sets up a query for the given timeseries UIDs.
void	setTimeSeries(String metric, Map<String,String> tags, Aggregator function, boolean rate) Sets the time series to the query.
void	setTimeSeries(String metric, Map<String,String> tags, Aggregator function, boolean rate, RateOptions rate_options) Sets the time series to the query.

Method Detail

setStartTime

void setStartTime(long timestamp)

Sets the start time of the graph.

Parameters:

timestamp - The start time, all the data points returned will have a timestamp greater than or equal to this one.

Throws:

IllegalArgumentException - if timestamp is less than or equal to 0, or if it can't fit on 32 bits.

IllegalArgumentException - if timestamp >= getEndTime.

getStartTime

long getStartTime()

Returns the start time of the graph.

Returns:

A strictly positive integer.

Throws:

IllegalStateException - if setStartTime(long) was never called on this instance before.

setEndTime

void setEndTime(long timestamp)

Sets the end time of the graph.

Parameters:

timestamp - The end time, all the data points returned will have a timestamp less than or equal to this one.

Throws:

IllegalArgumentException - if timestamp is less than or equal to 0, or if it can't fit on 32 bits.

IllegalArgumentException - if timestamp <= getStartTime.

getEndTime

long getEndTime()

Returns the end time of the graph.

If setEndTime(long) was never called before, this method will automatically execute setEndTime(System.currentTimeMillis() / 1000) to set the end time.

Returns:

A strictly positive integer.

setTimeSeries

void setTimeSeries(String metric,
                 Map<String,String> tags,
                 Aggregator function,
                 boolean rate,
                 RateOptions rate_options)
                   throws NoSuchUniqueName

Sets the time series to the query.

Parameters:

metric - The metric to retreive from the TSDB.

tags - The set of tags of interest.

function - The aggregation function to use.

rate - If true, the rate of the series will be used instead of the actual values.

rate_options - If included specifies additional options that are used when calculating and graph rate values

Throws:

NoSuchUniqueName - if the name of a metric, or a tag name/value does not exist.

Since:

2.0

setTimeSeries

void setTimeSeries(String metric,
                 Map<String,String> tags,
                 Aggregator function,
                 boolean rate)
                   throws NoSuchUniqueName

Sets the time series to the query.

Parameters:

metric - The metric to retreive from the TSDB.

tags - The set of tags of interest.

function - The aggregation function to use.

rate - If true, the rate of the series will be used instead of the actual values.

Throws:

NoSuchUniqueName - if the name of a metric, or a tag name/value does not exist.

setTimeSeries

void setTimeSeries(List<String> tsuids,
                 Aggregator function,
                 boolean rate)

Sets up a query for the given timeseries UIDs. For now, all TSUIDs in the group must share a common metric. This is to avoid issues where the scanner may have to traverse the entire data table if one TSUID has a metric of 000001 and another has a metric of FFFFFF. After modifying the query code to run asynchronously and use different scanners, we can allow different TSUIDs. Note: This method will not check to determine if the TSUIDs are valid, since that wastes time and we *assume* that the user provides TUSIDs that are up to date.

Parameters:

tsuids - A list of one or more TSUIDs to scan for

function - The aggregation function to use on results

rate - Whether or not the results should be converted to a rate

Throws:

IllegalArgumentException - if the tsuid list is null, empty or the TSUIDs do not share a common metric

Since:

2.0

setTimeSeries

void setTimeSeries(List<String> tsuids,
                 Aggregator function,
                 boolean rate,
                 RateOptions rate_options)

Sets up a query for the given timeseries UIDs. For now, all TSUIDs in the group must share a common metric. This is to avoid issues where the scanner may have to traverse the entire data table if one TSUID has a metric of 000001 and another has a metric of FFFFFF. After modifying the query code to run asynchronously and use different scanners, we can allow different TSUIDs. Note: This method will not check to determine if the TSUIDs are valid, since that wastes time and we *assume* that the user provides TUSIDs that are up to date.

Parameters:

tsuids - A list of one or more TSUIDs to scan for

function - The aggregation function to use on results

rate - Whether or not the results should be converted to a rate

rate_options - If included specifies additional options that are used when calculating and graph rate values

Throws:

IllegalArgumentException - if the tsuid list is null, empty or the TSUIDs do not share a common metric

Since:

2.0

downsample

void downsample(long interval,
              Aggregator downsampler)

Downsamples the results by specifying a fixed interval between points.

Technically, downsampling means reducing the sampling interval. Here the idea is similar. Instead of returning every single data point that matched the query, we want one data point per fixed time interval. The way we get this one data point is by aggregating all the data points of that interval together using an Aggregator. This enables you to compute things like the 5-minute average or 10 minute 99th percentile.

Parameters:

interval - Number of seconds wanted between each data point.

downsampler - Aggregation function to use to group data points within an interval.

run

DataPoints[] run()
                 throws org.hbase.async.HBaseException

Runs this query.

Returns:

The data points matched by this query.

Each element in the non-null but possibly empty array returned corresponds to one time series for which some data points have been matched by the query.

Throws:

org.hbase.async.HBaseException - if there was a problem communicating with HBase to perform the search.

runAsync

com.stumbleupon.async.Deferred<DataPoints[]> runAsync()
                                                      throws org.hbase.async.HBaseException

Executes the query asynchronously

Returns:

The data points matched by this query.

Each element in the non-null but possibly empty array returned corresponds to one time series for which some data points have been matched by the query.

Throws:

org.hbase.async.HBaseException - if there was a problem communicating with HBase to perform the search.

Since:

1.2