Module `airvantage.table`

Racon objects handling staging database tables, to buffer, consolidate and send structured data.

#table instances should be created with airvantage.asset#asset.newTable.

NOTE: The #table API is currently in BETA, and is subject to change in the subsequent release.

Type `airvantage.asset`

airvantage.asset:newTable(path, columns, storage, sendPolicy, purge)

Creates and returns a #table instance.

Type `columnspec`

columnspec.asfloat	boolean to force encoding of doubles as float (default: false).
columnspec.consolidation	consolidation method, mandatory for table:airvantage.table#table.newConsolidation calls. Possible values are `first`, `last`, `max`, `mean`, `median`, `middle`, `min`, `sum`. Note: QuasiPeriodic Vector is not part of AWT-DA 2 and should not be used (it will not be choosen by `smallest` encoding).
columnspec.factor	this is the DeltasVector factor, i.e. the precision to use when serializing floating point numbers. Set it to 1 to round to integer, 0.1 to round all numbers to 1/10 (that is 12.345 will be sent as 12.3). This field is mandatory for `deltasvector` serialization and optional for `smallest` (otherwise GCD will be computed, and non-integer numbers will cause fallback to vector).
columnspec.name	column name
columnspec.period	period for Quasi-periodic vector (number). Mandatory for `quasiperiodicvector` serialization.
columnspec.serialization	serialization method. Possible values are `fastest`, `smallest`, `list`, `deltasvector`, `quasiperiodicvector`. Optional, defaults to `list`.

Type `table`

table:consolidate(dont_reset)	Consolidates the table content into its consolidation table, and empties it unless `dont_reset` is true.
table:newConsolidation(path, columns, storage, consoPolicy, sendPolicy, purge)	Creates a table where data will be consolidated.
table:pushRow(row)	Adds a row of data to the table.
table:reset()	Empties all content in the table.
table:send(dont_reset)	Sends the table content to the server and empties it unless dont_reset is true.
table:setMaxRows(n)	Sets the maximum number of rows for a given table.

Type `airvantage.asset`

Field(s)

airvantage.asset:newTable(path, columns, storage, sendPolicy, purge)

Creates and returns a #table instance.

Parameters

path : (relative to the asset root) where the data will be sent.
columns : list of either airvantage.table#columnspec or column names (to use default values).
storage : either "file" or "ram", how the table must be persisted.
sendPolicy : name of the policy controlling when the table content is sent to the server.
purge : boolean indicating if existing table (if any) is recreated (true) or reused (false/nil). Recreated means the table will be dropped and then created from scratch (so any data inside table will be lost).

Return values

#table to store and consolidate structured data.
#nil, #string: error message.

Type `columnspec`

Column descriptors describes a table column with a name, a serialization method and some serialization options.

Depending on serialization methods, some fields can be either unused, optional or mandatory. Whenever a full column descriptor is expected, a simple string can be passed: in this case, the default serialization method and options will be used.

Field(s)

columnspec.asfloat: boolean to force encoding of doubles as float (default: false).

columnspec.consolidation

consolidation method, mandatory for table:airvantage.table#table.newConsolidation calls. Possible values are first, last, max, mean, median, middle, min, sum.

Note: QuasiPeriodic Vector is not part of AWT-DA 2 and should not be used (it will not be choosen by smallest encoding).

columnspec.factor: this is the DeltasVector factor, i.e. the precision to use when serializing floating point numbers. Set it to 1 to round to integer, 0.1 to round all numbers to 1/10 (that is 12.345 will be sent as 12.3). This field is mandatory for deltasvector serialization and optional for smallest (otherwise GCD will be computed, and non-integer numbers will cause fallback to vector).

#string columnspec.name: column name

columnspec.period: period for Quasi-periodic vector (number). Mandatory for quasiperiodicvector serialization.

columnspec.serialization: serialization method. Possible values are fastest, smallest, list, deltasvector, quasiperiodicvector. Optional, defaults to list.

Type `table`

Field(s)

table:consolidate(dont_reset)

Consolidates the table content into its consolidation table, and empties it unless dont_reset is true.

Parameter

dont_reset : if true, the table content is not emptied after being consolidated.

Return values

"ok" on success.
nil followed by an error message otherwise.

table:newConsolidation(path, columns, storage, consoPolicy, sendPolicy, purge)

Creates a table where data will be consolidated.

When a consolidation is declared, a new table (destination), whose column names must be a subset of the source table column names, will be created. Everytime the source table is consolidated, it will flush everything from source and create in a single row in destination. The values in this row depend on consolidation method (average value, minimum, median, ...) which is set for each column.

A table can have only one consolidation table (trying to set a consolidation twice will result in a error).

Example : 
--create the polices:
agent.config.data.policy.everyminute={period=60}  --consolidation policy every minute
agent.config.data.policy.every10minutes={period=10*60}  --sending data policy every 10 minutes
--create source and destination tables
local src = asset:newTable('example', {'timestamp', 'temp'}, 'ram', 'never')
local dst = src:newConsolidation('consolidated', 
        { timestamp='median', temp='mean' }, 'everyminute', 'every10minutes')
-- fill data into src
src:pushRow{ timestamp=1, temp=25 }
src:pushRow{ timestamp=2, temp=28 }
src:pushRow{ timestamp=3, temp=25 }

--Every minute, the source table will be consolidated and a row { timestamp=2, temp=26 } will be created in destination
--Every 10 minutes, the consolidated data destination will be sent to server

The data can be consolidated by:

Calling table.consolidate
Setting table.setMaxRows on source table
Giving the consoPolicy parameter (see next paragraph)

Note: a consolidation policy can be set only if the send policy of the source table is never (trying to call this method otherwise will result in a error). This means that automatic policies are mutually exclusive for sending and consolidating data. However airvantage.table and airvantage.table methods are always available for more advanced use cases.

Note 2: when the policies of the consolidation of a source and the sending of its destination are the same, consolidation is guaranteed to be done first. However, they are in different policies and if both are triggered at the same time, the behavior is undefined.

Note 3: in order to be consolidated, data must be numeric, any other kind of value will result in inserting null in destination table.

Parameters

path : (relative to the asset root) where the data will be sent.
columns : either a list of airvantage.table.columnspec with consolidation field and the same names as source table which associate each column name (key) to its consolidation method (value), like in example.
storage : either "file" or "ram", how the table must be persisted.
consoPolicy : name of the policy controlling when the source table content is consolidated.
sendPolicy : name of the policy controlling when the destination table content is sent to the server.
purge : boolean indicating if existing table (if any) is supposed to be recreated (true) or reused (false/nil). If you want to use this feature in consolidation, you have to recreate tables in the same order as they have been created (that is start by recreate the main source and then its consolidation, and so on). In particular you cannot recreate a destination table as long as its source is still active.

Return values

#table: where consolidated data will be stored.
nil followed by an error message otherwise.

table:pushRow(row)

Adds a row of data to the table.

The table needs to be created with airvantage.asset:newTable().

Parameter

row : table of key/value pairs, value must be a #columnspec, keys must match creation column names.

Return values

#string: "ok" on success.
#nil, #string: error message otherwise.

table:reset()

Empties all content in the table.

Return values

"ok" on success.
nil followed by an error message otherwise.

table:send(dont_reset)

Sends the table content to the server and empties it unless dont_reset is true.

Parameter

#boolean dont_reset : if true, the table content is not emptied after being sent.

Return values

"ok" on success.
#nil, #string: error message otherwise.

table:setMaxRows(n)

Sets the maximum number of rows for a given table.

Once a table's number of rows reaches its max, table content is either sent or consolidated, depending on policies: never policies are not triggered. This means that if a table is consolidated (that is, its send policy is never), data will be consolidated and not sent. Table is emptyed after trigering policy.

Parameter

n : max number of rows accepted in the table.

Return values

"ok" on success.
nil followed by an error message otherwise.

Module airvantage.table

Type airvantage.asset

Type columnspec

Type table

Type airvantage.table

Type airvantage.asset

Field(s)

Parameters

Return values

Type columnspec

Field(s)

Type table

Field(s)

Parameter

Return values

Parameters

Return values

Parameter

Return values

Return values

Parameter

Return values

Parameter

Return values

Module `airvantage.table`

Type `airvantage.asset`

Type `columnspec`

Type `table`

Type `airvantage.table`

Type `airvantage.asset`

Type `columnspec`

Type `table`