Trend logs

Trend log functions #

Load the library:

require('trends')

Library functions #

trends.fetch(name, dates, resolution, timestamps) #

trends.fetchone(name, dates, resolution) #

Fetch one or many values for the given period

Parameters:

  • name string, required - trend log name
  • dates table, required - must contain two keys - start and end, value for both keys must be either:
    • number - UTC timestamp (see examples below)
    • table containing year, month and day keys; time values (hours, minutes and seconds) are ignored
  • resolution number - default trend resolution is used if not specified, set to 86400 to retrieve daily data
  • timestamps boolean - (only for fetch) when set to true each returned data entry becomes an array-like table where the first element is timestamp and the second is value

Return values:

  • fetch returns a table with values for the given period or nil on error. Number of values depends on period, resolution and data retention settings
  • fetchone returns single value for the given period or nil on error

Examples #

Basic example # 

require('trends')

-- fetch data for the previous day
dates = {}
dates['start'] = os.date('*t')
dates['start'].day = dates['start'].day - 1
dates['end'] = os.date('*t')

-- fetch current value
day = trends.fetchone('Gas', dates)

-- fetch data for the past year
dates = {}
dates['start'] = os.date('*t')
dates['start'].year = dates['start'].year - 1
dates['end'] = os.date('*t')

-- fetch previous value
yearly = trends.fetch('Gas', dates, 86400)

Fetch using UTC timestamps # 

date = os.date('*t') -- current date as a table
time = os.time(date, true) -- convert UTC timestamp

-- fetch data for the past hour
datarange = {
  ['start'] = time - 3600, -- 1 hour in seconds
  ['end'] = time,
}

data = trends.fetch('trend name', datarange)
log(data)

Detecting invalid/missing data #

Data point values which contain invalid data or cannot be found are assigned to trends.NaN.

The default value for trends.NaN is 0, it can be set to 0 / 0 (NaN - not a number).

require('trends')

-- use "not a number" for invalid values
trends.NaN = 0 / 0

-- fetch data for the past year
dates = {}
dates['start'] = os.date('*t')
dates['start'].year = dates['start'].year - 1
dates['end'] = os.date('*t')

value = trends.fetchone('Hot Water', dates)

-- NaN ~= NaN means value was not found
if value ~= value then
  return
end