Time Series Database Cache Module by Automation Professionals
E-Mail Support

Dataset / timeSeriesCache

Query a table or view for time series data within a timestamp range, immediately returning any cached data when called, and accepting push notifications as data is delivered from the data source. Optionally insert null rows where timestamps are discontinuous. Available in all scopes.


timeSeriesCache(datasourcename, tablename, timestampcolumn, whereclause, [priority,] begints, endts, [gapTolerance,] valuecolumns...) returns Dataset

ArgumentData TypeDescription
datasourcenameStringProperly capitalized data source name to use for the background queries.
tablenameStringProperly capitalized table name or view name. May specify a schema if needed.
timestampcolumnStringColumn name that has the timestamps. This must be indexed or the cache will choke on large tables.

Optional WHERE clause to single out specific rows when multiple units are stored together in one table. Provide an empty string if not needed.

Different WHERE clauses are cached separately. Consistent case, whitespace, and internal quoting are significant. Columns referenced in the WHERE clause should be indexed with the timestamp column for best performance.

priorityIntegerOptional, non-negative. One if omitted. Systemwide bulk queries for missing data will be executed in priority order. EasyNoteChart uses priority=1 for chart data and priority=2 for histogram data.
begintsDateQuery start timestamp. Must not be null.
endtsDateQuery end timestamp. Must not be null.
gapToleranceLongOptional, Milliseconds. Insert a null row when consecutive timestamps are further apart than this tolerance.
valuecolumnsString/Dataset...One or more String or Dataset arguments, in any combination, defining the value columns to be delivered. When datasets are supplied, each dataset's first column must be of type String, and is expected to contain column names. (The same format as delivered by the split() function.)

Usage Notes

The Dataset returned is actually a subclass: TransientSeriesFragment. It carries additional properties that will report the actually completed query data, the raw data creation time, and cache expiration timestamp. It also excludes its rows from most serialization, avoiding storing large datasets in your projects.

When using this function to supply data to a classic chart, select "Discontinuous Lines" in the XY Renderer section of the Dataset settings. This will hide stray lines while data is arriving from the gateway. Also consider overriding the x-axis auto-range function. For example, if such a chart is driven from a Date Range component, you might use a configureChart() script like:

def configureChart(self, chart):
    """ Preloaded Help Text """
    config = chart.getXAxes().get("Default X Axis")
    config.minimumDate = self.startDate
    config.maximumDate = self.endDate
    axis = chart.getChart().getXYPlot().getDomainAxis()
    axis.autoRange = False
    axis.setRange(self.startDate, self.endDate)