Selection of all datasets within adjustable time limits.
Exposure of datasets of a Device/Reading-combination within adjustable time limits.
Selection of datasets by usage of dynamically calclated time limits at execution time.
Highlighting doublets when select and display datasets (fetchrows)
Calculation of quantity of datasets of a Device/Reading-combination within adjustable time limits and several aggregations.
The calculation of summary-, difference-, maximum-, minimum- and averageValues of numeric readings within adjustable time limits and several aggregations.
write back results of summary-, difference-, maximum-, minimum- and average calculation into the database
The deletion of datasets. The containment of deletion can be done by Device and/or Reading as well as fix or dynamically calculated time limits at execution time.
export of datasets to file (CSV-format).
import of datasets from file (CSV-Format).
rename of device/readings in datasets
change of reading values in the database (changeValue)
automatic rename of device names in datasets and other DbRep-definitions after FHEM "rename" command (see DbRep-Agent)
Execution of arbitrary user specific SQL-commands (non-blocking)
Execution of arbitrary user specific SQL-commands (blocking) for usage in user own code (dbValue)
creation of backups of the database in running state non-blocking (MySQL, SQLite)
transfer dumpfiles to a FTP server after backup incl. version control
restore of SQLite- and MySQL-Dumps non-blocking
optimize the connected database (optimizeTables, vacuum)
report of existing database processes (MySQL)
purge content of current-table
fill up the current-table with a (tunable) extract of the history-table
delete consecutive datasets with different timestamp but same values (clearing up consecutive doublets)
Repair of a corrupted SQLite database ("database disk image is malformed")
transmission of datasets from source database into another (Standby) database (syncStandby)
reduce the amount of datasets in database (reduceLog)
delete of duplicate records (delDoublets)

Autorename

DbRep-Agent

UserExit

Modul 93_DbRep - Reporting and Management of database content (DbLog)

DbReadingsVal

DbReadingsVal("<name>","<device:reading>","<timestamp>","<default>")

Examples:

<name>	: name of the DbRep-Device to request
<device:reading>	: device:reading whose value is to deliver
<timestamp>	: timestamp of reading whose value is to deliver (*) in the form "YYYY-MM-DD hh:mm:ss"
<default>	: default value if no reading value can be retrieved

Preparations


  CREATE INDEX Report_Idx ON `history` (TIMESTAMP, READING) USING BTREE;

Definition


    define <name> DbRep <name of DbLog-instance>

Set

averageValue [display | writeToDB] - calculates the average value of database column "VALUE" between period given by timestamp-attributes which are set. The reading to evaluate must be specified by attribute "reading".
By attribute "averageCalcForm" the calculation variant for average determination will be configured. Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculated results are stored in the database with a new reading name.
The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute "readingNameMap". The prefix is made up of the creation function and the aggregation.
The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".

Example of building a new reading name from the original reading "totalpac":

Summarized the relevant attributes to control this function are:

averageCalcForm	: choose the calculation variant for average determination
device	: include or exclude <device> from selection
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
reading	: include or exclude <reading> from selection
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

cancelDump - stops a running database dump.

changeValue - changes the saved value of readings. If the selection is limited to particular device/reading-combinations by attribute "device" respectively "reading", it is considered as well as possibly defined time limits by time attributes (time.*).
If no limits are set, the whole database is scanned and the specified value will be changed.

Syntax:

<old string> :	a simple string with/without spaces, e.g. "OL 12" a string with usage of SQL-wildcard, e.g. "%OL%"
<new string> :	a simple string with/without spaces, e.g. "12 kWh" Perl code embedded in "{}" with quotes, e.g. "{($VALUE,$UNIT) = split(" ",$VALUE)}". The perl expression the variables $VALUE and $UNIT are committed to. The variables are changable within the perl code. The returned value of VALUE and UNIT are saved into the database field VALUE respectively UNIT of the dataset.

Examples:

device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
time.*	: a number of attributes to limit selection by time
executeBeforeProc	: execute a FHEM command (or perl-routine) before start of changeValue
executeAfterProc	: execute a FHEM command (or perl-routine) after changeValue is finished
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

Note:

countEntries [history|current] - provides the number of table entries (default: history) between time period set by time.* -attributes if set. If time.* attributes not set, all entries of the table will be count. The attributes "device" and "reading" can be used to limit the evaluation.
By default the summary of all counted datasets, labeled by "ALLREADINGS", will be created. If the attribute "countEntriesDetail" is set, the number of every reading is reported additionally.

The relevant attributes for this function are:

aggregation	: aggregatiion/grouping of time intervals
countEntriesDetail	: detailed report the count of datasets (per reading)
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

delDoublets [adviceDelete | delete] - show respectively delete duplicate/multiple datasets. Therefore the fields TIMESTAMP, DEVICE, READING and VALUE of records are compared.
The attributes to define the scope of aggregation,time period, device and reading are considered. If attribute aggregation is not set or set to "no", it will change to the default aggregation period "day".

adviceDelete	: simulates the datasets to delete in database (nothing will be deleted !)
delete	: deletes the doublets

Due to security reasons the attribute attribute "allowDeletion" needs to be set for execute the "delete" option.
The amount of datasets to show by commands "delDoublets adviceDelete" is initially limited (default: 1000) and can be adjusted by attribute "limit". The adjustment of "limit" has no impact to the "delDoublets delete" function, but affects ONLY the display of the data.
Before and after this "delDoublets" it is possible to execute a FHEM command or Perl script (please see attributes "executeBeforeProc", "executeAfterProc").

Example:

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

allowDeletion	: needs to be set to execute the delete option
aggregation	: choose the aggregation period
limit	: limits ONLY the count of datasets to display
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
executeBeforeProc	: execute a FHEM command (or perl-routine) before start of the function
executeAfterProc	: execute a FHEM command (or perl-routine) after the function is finished
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

delEntries - deletes all database entries or only the database entries specified by attributes Device and/or Reading and the entered time period between "timestamp_begin", "timestamp_end" (if set) or "timeDiffToNow/timeOlderThan".

from

until

between

older

from

allowDeletion	: unlock the delete function
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
time.*	: a number of attributes to limit selection by time
executeBeforeProc	: execute a FHEM command (or perl-routine) before start of delEntries
executeAfterProc	: execute a FHEM command (or perl-routine) after delEntries is finished

delSeqDoublets [adviceRemain | adviceDelete | delete] - show respectively delete identical sequentially datasets. Therefore Device,Reading and Value of the sequentially datasets are compared. Not deleted are the first und the last dataset of a aggregation period (e.g. hour,day,week and so on) as well as the datasets before or after a value change (database field VALUE).
The attributes to define the scope of aggregation,time period, device and reading are considered. If attribute aggregation is not set or set to "no", it will change to the default aggregation period "day". For datasets containing numerical values it is possible to determine a variance with attribute "seqDoubletsVariance". Up to this value consecutive numerical datasets are handled as identical and should be deleted.

adviceRemain	: simulates the remaining datasets in database after delete-operation (nothing will be deleted !)
adviceDelete	: simulates the datasets to delete in database (nothing will be deleted !)
delete	: deletes the consecutive doublets (see example)

Due to security reasons the attribute attribute "allowDeletion" needs to be set for execute the "delete" option.
The amount of datasets to show by commands "delSeqDoublets adviceDelete", "delSeqDoublets adviceRemain" is initially limited (default: 1000) and can be adjusted by attribute "limit". The adjustment of "limit" has no impact to the "delSeqDoublets delete" function, but affects ONLY the display of the data.
Before and after this "delSeqDoublets" it is possible to execute a FHEM command or Perl-script (please see attributes "executeBeforeProc" and "executeAfterProc").

Example

bold

2017-11-25_00-00-05__eg.az.fridge_Pwr__power 0

2017-11-25_01-08-21__eg.az.fridge_Pwr__power 0

2017-11-25_01-08-59__eg.az.fridge_Pwr__power 60.32

2017-11-25_01-11-21__eg.az.fridge_Pwr__power 56.26

2017-11-25_01-27-54__eg.az.fridge_Pwr__power 6.19

2017-11-25_01-28-51__eg.az.fridge_Pwr__power 0

2017-11-25_02-39-29__eg.az.fridge_Pwr__power 0

2017-11-25_02-41-18__eg.az.fridge_Pwr__power 105.28

2017-11-25_02-41-26__eg.az.fridge_Pwr__power 61.52

2017-11-25_03-00-06__eg.az.fridge_Pwr__power 47.46

2017-11-25_03-00-33__eg.az.fridge_Pwr__power 0

2017-11-25_23-40-10__eg.az.fridge_Pwr__power 0

2017-11-25_23-42-24__eg.az.fridge_Pwr__power 1

2017-11-25_23-45-27__eg.az.fridge_Pwr__power 1

2017-11-25_23-47-07__eg.az.fridge_Pwr__power 0

2017-11-25_23-48-15__eg.az.fridge_Pwr__power 0

2017-11-25_23-50-21__eg.az.fridge_Pwr__power 59.1

2017-11-25_23-55-14__eg.az.fridge_Pwr__power 52.31

2017-11-25_23-58-09__eg.az.fridge_Pwr__power 51.73

Summarized the relevant attributes to control this function are:

allowDeletion	: needs to be set to execute the delete option
aggregation	: choose the aggregation period
limit	: limits ONLY the count of datasets to display
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
executeBeforeProc	: execute a FHEM command (or perl-routine) before start of the function
executeAfterProc	: execute a FHEM command (or perl-routine) after the function is finished
seqDoubletsVariance	: Up to this value consecutive numerical datasets are handled as identical and should be deleted
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

deviceRename <old_name>,<new_name> - renames the device name of a device inside the connected database (Internal DATABASE). The devicename will allways be changed in the entire database. Possibly set time limits or restrictions by attributes device and/or reading will not be considered.

diffValue [display | writeToDB] - calculates the difference of database column "VALUE" between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". This function is mostly reasonable if readingvalues are increasing permanently and don't write value-differences to the database. The difference will be generated from the first available dataset (VALUE-Field) to the last available dataset between the specified time linits/aggregation, in which a balanced difference value of the previous aggregation period will be transfered to the following aggregation period in case this period contains a value.
A possible counter overrun (restart with value "0") will be considered (compare attribute "diffAccept").

If only one dataset will be found within the evalution period, the difference can be calculated only in combination with the balanced difference of the previous aggregation period. In this case a logical inaccuracy according the assignment of the difference to the particular aggregation period can be possible. Hence in warning in "state" will be placed and the reading "less_data_in_period" with a list of periods with only one dataset found in it will be created.

Note:

Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculation results are stored in the database with a new reading name.
The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute "readingNameMap". The prefix is made up of the creation function and the aggregation.
The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".

Example of building a new reading name from the original reading "totalpac":

Summarized the relevant attributes to control this function are:

aggregation	: choose the aggregation period
diffAccept	: the maximum accepted difference between sequential records
device	: include or exclude <device> from selection
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
reading	: include or exclude <reading> from selection
readingNameMap	: rename the resulted reading name
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

dumpMySQL [clientSide | serverSide] - creates a dump of the connected MySQL database.
Depending from selected option the dump will be created on Client- or on Server-Side.
The variants differs each other concerning the executing system, the creating location, the usage of attributes, the function result and the needed hardware ressources.
The option "clientSide" e.g. needs more powerful FHEM-Server hardware, but saves all available tables inclusive possibly created views.
With attribute "dumpCompress" a compression of dump file after creation can be switched on.

Option clientSide

Note:
To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization want to be used !

dumpComment	: User comment in head of dump file
dumpCompress	: compress of dump files after creation
dumpDirLocal	: the local destination directory for dump file creation
dumpMemlimit	: limits memory usage
dumpSpeed	: limits CPU utilization
dumpFilesKeep	: number of dump files to keep
executeBeforeProc	: execution of FHEM command (or perl-routine) before dump
executeAfterProc	: execution of FHEM command (or perl-routine) after dump
optimizeTablesBeforeDump	: table optimization before dump

naming convention of dump files

Option serverSide

CSV-formatted

Note:
To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization want to be used !

dumpDirRemote	: destination directory of dump file on remote server
dumpCompress	: compress of dump files after creation
dumpDirLocal	: the local mounted directory dumpDirRemote
dumpFilesKeep	: number of dump files to keep
executeBeforeProc	: execution of FHEM command (or perl-routine) before dump
executeAfterProc	: execution of FHEM command (or perl-routine) after dump
optimizeTablesBeforeDump	: table optimization before dump

Note:

Example:

naming convention of dump files

FTP-Transfer after Dump

ftpUse	: FTP Transfer after dump will be switched on (without SSL encoding)
ftpUser	: User for FTP-server login, default: anonymous
ftpUseSSL	: FTP Transfer with SSL encoding after dump
ftpDebug	: debugging of FTP communication for diagnostics
ftpDir	: directory on FTP-server in which the file will be send into (default: "/")
ftpDumpFilesKeep	: leave the number of dump files in FTP-destination <ftpDir> (default: 3)
ftpPassive	: set if passive FTP is to be used
ftpPort	: FTP-Port, default: 21
ftpPwd	: password of FTP-User, not set by default
ftpServer	: name or IP-address of FTP-server. absolutely essential !
ftpTimeout	: timeout of FTP-connection in seconds (default: 30).

dumpSQLite - creates a dump of the connected SQLite database.
This function uses the SQLite Online Backup API and allow to create a consistent backup of the database during the normal operation. The dump will be saved in FHEM log-directory by default. The target directory can be defined by attribute "dumpDirLocal" and has to be writable by the FHEM process.
Before executing the dump a table optimization can be processed optionally (see attribute "optimizeTablesBeforeDump").

Note:
To avoid FHEM from blocking, you have to operate DbLog in asynchronous mode if the table optimization want to be used !

Before and after the dump a FHEM-command can be executed (see attribute "executeBeforeProc", "executeAfterProc").

The attributes relevant for function "dumpMySQL serverSide" are:

dumpCompress	: compress of dump files after creation
dumpDirLocal	: the local mounted directory dumpDirRemote
dumpFilesKeep	: number of dump files to keep
executeBeforeProc	: execution of FHEM command (or perl-routine) before dump
executeAfterProc	: execution of FHEM command (or perl-routine) after dump
optimizeTablesBeforeDump	: table optimization before dump

After a successfull finished dump the old dumpfiles are deleted and only the number of attribute "dumpFilesKeep" (default: 3) remain in the target directory "dumpDirLocal". If "dumpFilesKeep = 0" is set, all dumpfiles (also the current created file), are deleted. This setting can be helpful, if FTP transmission is used and the created dumps are only keep remain in the FTP destination directory.

The naming convention of dump files is: <dbname>_<date>_<time>.sqlitebkp[.gzip]

The database can be restored by command "set <name> restoreSQLite <filename>"
The created dump file can be transfered to a FTP-server. Please see explanations about FTP- transfer in topic "dumpMySQL".

eraseReadings - deletes all created readings in the device, except reading "state" and readings, which are contained in exception list defined by attribute "readingPreventFromDel".

exportToFile [</path/file>] [MAXLINES=<lines>] - exports DB-entries to a file in CSV-format of time period specified by time attributes.

The filename can be defined by attribute "expimpfile".
Optionally a file can be specified as a command option (/path/file) and overloads a possibly defined attribute "expimpfile". The maximum number of datasets which are exported into one file can be specified with the optional parameter "MAXLINES". In this case several files with extensions "_part1", "_part2", "_part3" and so on are created (pls. remember it when you import the files !).
Limitation of selections can be done by attributes device and/or reading. The filename may contain wildcards as described in attribute section of "expimpfile".
By setting attribute "aggregation" the export of datasets will be splitted into time slices corresponding to the specified aggregation. If, for example, "aggregation = month" is set, the data are selected in monthly packets and written into the exportfile. Thereby the usage of main memory is optimized if very large amount of data is exported and avoid the "died prematurely" error.

The attributes relevant for this function are:

aggregation	: determination of selection time slices
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
time.*	: a number of attributes to limit selection by time
executeBeforeProc	: execution of FHEM command (or perl-routine) before export
executeAfterProc	: execution of FHEM command (or perl-routine) after export
expimpfile	: the name of exportfile
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

fetchrows [history|current] - provides all table entries (default: history) of time period set by time attributes respectively selection conditions by attributes "device" and "reading". An aggregation set will not be considered.
The direction of data selection can be determined by attribute "fetchRoute".

Every reading of result is composed of the dataset timestring , an index, the device name and the reading name. The function has the capability to reconize multiple occuring datasets (doublets). Such doublets are marked by an index > 1.
Doublets can be highlighted in terms of color by setting attribut e"fetchMarkDuplicates".

Note:
Highlighted readings are not displayed again after restart or rereadcfg because of they are not saved in statefile.

This attribute is preallocated with some colors, but can be changed by colorpicker-widget:


                                 attr <DbRep-Device> widgetOverride fetchMarkDuplicates:colorpicker

The readings of result are composed like the following sceme:

Example:

For a better overview the relevant attributes are listed here in a table:

fetchRoute	: direction of selection read in database
limit	: limits the number of datasets to select and display
fetchMarkDuplicates	: Highlighting of found doublets
device	: include or exclude <device> from selection
reading	: include or exclude <reading> from selection
time.*	: A number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

Note:
Although the module is designed non-blocking, a huge number of selection result (huge number of rows) can overwhelm the browser session respectively FHEMWEB. Due to the sample space can be limited by attribute "limit". Of course ths attribute can be increased if your system capabilities allow a higher workload.

insert - use it to insert data ito table "history" manually. Input values for Date, Time and Value are mandatory. The database fields for Type and Event will be filled in with "manual" automatically and the values of Device, Reading will be get from set attributes.

importFromFile [<file>] - imports data in CSV format from file into database.
The filename can be defined by attribute "expimpfile".
Optionally a file can be specified as a command option (/path/file) and overloads a possibly defined attribute "expimpfile". The filename may contain wildcards as described in attribute section of "expimpfile".

dataset format:

Example for a source dataset:

executeBeforeProc	: execution of FHEM command (or perl-routine) before import
executeAfterProc	: execution of FHEM command (or perl-routine) after import
expimpfile	: the name of exportfile

maxValue [display | writeToDB] - calculates the maximum value of database column "VALUE" between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". The evaluation contains the timestamp of the last appearing of the identified maximum value within the given period.
Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculated results are stored in the database with a new reading name.
The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute "readingNameMap". The prefix is made up of the creation function and the aggregation.
The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".

Example of building a new reading name from the original reading "totalpac":

Summarized the relevant attributes to control this function are:

aggregation	: choose the aggregation period
device	: include or exclude <device> from selection
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
reading	: include or exclude <reading> from selection
readingNameMap	: rename the resulted readings
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

minValue [display | writeToDB] - calculates the minimum value of database column "VALUE" between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". The evaluation contains the timestamp of the first appearing of the identified minimum value within the given period.
Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculated results are stored in the database with a new reading name.
The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute "readingNameMap". The prefix is made up of the creation function and the aggregation.
The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".

Example of building a new reading name from the original reading "totalpac":

Summarized the relevant attributes to control this function are:

aggregation	: choose the aggregation period
device	: include or exclude <device> from selection
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
reading	: include or exclude <reading> from selection
readingNameMap	: rename the resulted readings
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

optimizeTables - optimize tables in the connected database (MySQL).
Before and after an optimization it is possible to execute a FHEM command. (please see attributes "executeBeforeProc", "executeAfterProc")
readingRename <[device:]oldreadingname>,<newreadingname>
Renames the reading name of a device inside the connected database (see Internal DATABASE). The readingname will allways be changed in the entire database. Possibly set time limits or restrictions by attributes device and/or reading will not be considered.
As an option a device can be specified. In this case only the old readings of this device will be renamed.
The amount of renamed reading names (datasets) will be displayed in reading "reading_renamed".
If the reading name to be renamed was not found in the database, a WARNING will appear in reading "reading_not_renamed".
Appropriate entries will be written to Logfile if verbose >= 3 is set.

Note:
Even though the function itself is designed non-blocking, make sure the assigned DbLog-device is operating in asynchronous mode to avoid FHEMWEB from blocking.

reduceLog [average[=day]]
Reduces historical records within the limits given by the "time.*"-attributes to one record (the 1st) each hour per device & reading. At least one of the "time.*"-attributes must be set (pls. see table below). Each of missing time limit will be calculated by the module itself in this case.

With the optional argument 'average' not only the records will be reduced, but all numerical values of an hour will be reduced to a single average. With option 'average=day' all numerical values of a day are reduced to a single average (implies 'average').

By setting attributes "device" and/or "reading" the records to be considered could be included respectively excluded. Both containments delimit the selected data from database and may reduce the system RAM load. The reading "reduceLogState" contains the result of the last executed reducelog run.

The relevant attributes for this function are:

executeBeforeProc	: execution of FHEM command (or perl-routine) before reducelog
executeAfterProc	: execution of FHEM command (or perl-routine) after reducelog
device	: include or exclude <device> for selection
reading	: include or exclude <reading> for selection
timeOlderThan	: records older than this attribute will be reduced
timestamp_end	: records older than this attribute will be reduced
timeDiffToNow	: records newer than this attribute will be reduced
timestamp_begin	: records newer than this attribute will be reduced
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

For compatibility reasons the reducelog command can optionally be completed with supplements "EXCLUDE" respectively "INCLUDE" to exclude and/or include device/reading combinations from reducelog:

This declaration is evaluated as Regex and overwrites the attributes "device" and "reading", which won't be considered in this case.

Examples:

Note:
Even though the function itself is non-blocking, you have to set the attached DbLog device into the asynchronous mode (attr asyncMode = 1) to avoid a blocking situation of FHEM !.
It is strongly recommended to check if the default INDEX 'Search_Idx' exists on the table 'history'!

repairSQLite - repairs a corrupted SQLite database.
A corruption is usally existent when the error message "database disk image is malformed" appears in reading "state" of the connected DbLog-device. If the command was started, the connected DbLog-device will firstly disconnected from the database for 10 hours (36000 seconds) automatically (breakup time). After the repair is finished, the DbLog-device will be connected to the (repaired) database immediately.
As an argument the command can be completed by a differing breakup time (in seconds).
The corrupted database is saved as <database>.corrupt in same directory.
restoreMySQL <File> - restore a database from serverSide- or clientSide-Dump.
The function provides a drop-down-list of files which can be used for restore.

Usage of serverSide-Dumps
The content of history-table will be restored from a serverSide-Dump. Therefore the remote directory "dumpDirRemote" of the MySQL-Server has to be mounted on the Client and make it usable to the DbRep-device by setting attribute "dumpDirLocal" to the appropriate value.
All files with extension "csv[.gzip]" and if the filename is beginning with the name of the connected database (see Internal DATABASE) are listed.

Usage of clientSide-Dumps
All tables and views (if present) are restored. The directory which contains the dump files has to be set by attribute "dumpDirLocal" to make it usable by the DbRep device.
All files with extension "sql[.gzip]" and if the filename is beginning with the name of the connected database (see Internal DATABASE) are listed.
The restore speed depends of the server variable "max_allowed_packet". You can change this variable in file my.cnf to adapt the speed. Please consider the need of sufficient ressources (especially RAM).

The database user needs rights for database management, e.g.:
CREATE, ALTER, INDEX, DROP, SHOW VIEW, CREATE VIEW

restoreSQLite <File>.sqlitebkp[.gzip] - restores a backup of SQLite database.
The function provides a drop-down-list of files which can be used for restore. The data stored in the current database are deleted respectively overwritten. All files with extension "sqlitebkp[.gzip]" and if the filename is beginning with the name of the connected database will are listed.

sqlCmd - Execute an arbitrary user specific command.
If the command contains a operation to delete data, the attribute "allowDeletion" has to be set for security reason.
The statement doesn't consider limitations by attributes "device", "reading", "time.*" respectively "aggregation".
This command also accept the setting of MySQL session variables like "SET @open:=NULL, @closed:=NULL;" or the usage of SQLite PRAGMA before execution the SQL-Statement. If the session variable or PRAGMA has to be set every time before executing a SQL statement, the attribute "sqlCmdVars" can be set.
If the attribute "timestamp_begin" respectively "timestamp_end" is assumed in the statement, it is possible to use placeholder "§timestamp_begin§" respectively "§timestamp_end§" on suitable place.

If you want update a dataset, you have to add "TIMESTAMP=TIMESTAMP" to the update-statement to avoid changing the original timestamp.

Examples of SQL-statements:

set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-01-06 00:00:00" group by DEVICE having count(*) > 800
set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-05-06 00:00:00" group by DEVICE
set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= §timestamp_begin§ group by DEVICE
set <name> sqlCmd select * from history where DEVICE like "Te%t" order by `TIMESTAMP` desc
set <name> sqlCmd select * from history where `TIMESTAMP` > "2017-05-09 18:03:00" order by `TIMESTAMP` desc
set <name> sqlCmd select * from current order by `TIMESTAMP` desc
set <name> sqlCmd select sum(VALUE) as 'Einspeisung am 04.05.2017', count(*) as 'Anzahl' FROM history where `READING` = "Einspeisung_WirkP_Zaehler_Diff" and TIMESTAMP between '2017-05-04' AND '2017-05-05'
set <name> sqlCmd delete from current
set <name> sqlCmd delete from history where TIMESTAMP < "2016-05-06 00:00:00"
set <name> sqlCmd update history set TIMESTAMP=TIMESTAMP,VALUE='Val' WHERE VALUE='TestValue'
set <name> sqlCmd select * from history where DEVICE = "Test"
set <name> sqlCmd insert into history (TIMESTAMP, DEVICE, TYPE, EVENT, READING, VALUE, UNIT) VALUES ('2017-05-09 17:00:14','Test','manuell','manuell','Tes§e','TestValue','°C')

set <name> sqlCmd SET @open:=NULL, @closed:=NULL; SELECT TIMESTAMP, VALUE,DEVICE, @open AS open, @open := IF(VALUE = 'open', TIMESTAMP, NULL) AS curr_open, @closed := IF(VALUE = 'closed', TIMESTAMP, NULL) AS closed FROM history WHERE DATE(TIMESTAMP) = CURDATE() AND DEVICE = "HT_Fensterkontakt" AND READING = "state" AND (VALUE = "open" OR VALUE = "closed") ORDER BY TIMESTAMP;
set <name> sqlCmd PRAGMA temp_store=MEMORY; PRAGMA synchronous=FULL; PRAGMA journal_mode=WAL; PRAGMA cache_size=4000; select count(*) from history;
set <name> sqlCmd PRAGMA temp_store=FILE; PRAGMA temp_store_directory = '/opt/fhem/'; VACUUM;

Reading

allowDeletion	: activates capabilty to delete datasets
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
sqlResultFormat	: determines presentation style of command result
sqlResultFieldSep	: choice of a useful field separator for result
sqlCmdHistoryLength	: activates command history and length
sqlCmdVars	: set SQL session variable or PRAGMA before execute the SQL statement

Note:

sqlCmdHistory - If history is activated by attribute "sqlCmdHistoryLength", an already successfully executed sqlCmd-command can be repeated from a drop-down list.
By execution of the last list entry, "__purge_historylist__", the list itself can be deleted.
If the statement contains "," this character is displayed as "<c>" in the history list due to technical restrictions.

For a better overview the relevant attributes for this command are listed in a table:

allowDeletion	: activates capabilty to delete datasets
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
sqlResultFormat	: determines presentation style of command result
sqlResultFieldSep	: choice of a useful field separator for result

sqlSpecial - This function provides a drop-down list with a selection of prepared reportings.
The statements result is depicted in reading "SqlResult". The result can be formatted by attribute "sqlResultFormat", a well as the used field separator by attribute "sqlResultFieldSep".

The relevant attributes for this function are:

executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
sqlResultFormat	: determines the formatting of the result
sqlResultFieldSep	: determines the used field separator in statement result

The following predefined reportings are selectable:

50mostFreqLogsLast2days	: reports the 50 most occuring log entries of the last 2 days
allDevCount	: all devices occuring in database and their quantity
allDevReadCount	: all device/reading combinations occuring in database and their quantity

sumValue [display | writeToDB] - calculates the summary of database column "VALUE" between period given by attributes "timestamp_begin", "timestamp_end" or "timeDiffToNow / timeOlderThan". The reading to evaluate must be defined using attribute "reading". Using this function is mostly reasonable if value-differences of readings are written to the database.
Is no or the option "display" specified, the results are only displayed. Using option "writeToDB" the calculation results are stored in the database with a new reading name.
The new readingname is built of a prefix and the original reading name, in which the original reading name can be replaced by the value of attribute "readingNameMap". The prefix is made up of the creation function and the aggregation.
The timestamp of the new stored readings is deviated from aggregation period, unless no unique point of time of the result can be determined. The field "EVENT" will be filled with "calculated".

Example of building a new reading name from the original reading "totalpac":

Summarized the relevant attributes to control this function are:

aggregation	: choose the aggregation period
device	: include or exclude <device> from selection
executeBeforeProc	: execution of FHEM command (or perl-routine) before operation
executeAfterProc	: execution of FHEM command (or perl-routine) after operation
reading	: include or exclude <reading> from selection
readingNameMap	: rename the resulted readings
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

syncStandby <DbLog-Device Standby> - datasets of the connected database (source) are transmitted into another database (Standby-database).
Here the "<DbLog-Device Standby>" is the DbLog-Device what is connected to the Standby-database.

All the datasets which are determined by timestamp-attributes or respectively the attributes "device", "reading" are transmitted.
The datasets are transmitted in time slices accordingly to the adjusted aggregation. If the attribute "aggregation" has value "no" or "month", the datasets are transmitted automatically in daily time slices into standby-database. Source- and Standby-database can be of different types.

The relevant attributes to control the syncStandby function are:

aggregation	: adjustment of time slices for data transmission (hour,day,week)
device	: include or exclude <device> for transmission
reading	: include or exclude <reading> for transmission
time.*	: a number of attributes to limit selection by time
valueFilter	: an additional REGEXP to control the record selection. The REGEXP is applied to the database field 'VALUE'.

tableCurrentFillup - the current-table will be filled u with an extract of the history-table. The attributes for limiting time and device, reading are considered. Thereby the content of the extract can be affected. In the associated DbLog-device the attribute "DbLogType" should be set to "SampleFill/History".

tableCurrentPurge - deletes the content of current-table. There are no limits, e.g. by attributes "timestamp_begin", "timestamp_end", device, reading and so on, considered.

vacuum - optimize tables in the connected database (SQLite, PostgreSQL).
Before and after an optimization it is possible to execute a FHEM command. (please see attributes "executeBeforeProc", "executeAfterProc")

For all evaluation variants (except sqlCmd,deviceRename,readingRename) applies:

Note:

Get

Note:

blockinginfo - list the current system wide running background processes (BlockingCalls) together with their informations. If character string is too long (e.g. arguments) it is reported shortened.

dbstatus - lists global informations about MySQL server status (e.g. informations related to cache, threads, bufferpools, etc. ). Initially all available informations are reported. Using the attribute "showStatus" the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained there.
dbValue <SQL-statement> - Executes the specified SQL-statement in blocking manner. Because of its mode of operation this function is particular convenient for user own perl scripts.
The input accepts multi line commands and delivers multi line results as well. This command also accept the setting of SQL session variables like "SET @open:=NULL, @closed:=NULL;".
If several fields are selected and passed back, the fieds are separated by the separator defined by attribute "sqlResultFieldSep" (default "|"). Several result lines are separated by newline ("\n").
This function only set/update status readings, the userExitFn function isn't called.
If you create a little routine in 99_myUtils, for example:
```
sub dbval($$) {
  my ($name,$cmd) = @_;
  my $ret = CommandGet(undef,"$name dbValue $cmd"); 
return $ret;
}                            
                            
```
it can be accessed with e.g. those calls:

dbvars - lists global informations about MySQL system variables. Included are e.g. readings related to InnoDB-Home, datafile path, memory- or cache-parameter and so on. The Output reports initially all available informations. Using the attribute "showVariables" the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained there.
minTimestamp - Identifies the oldest timestamp in the database (will be executed implicitely at FHEM start). The timestamp is used as begin of data selection if no time attribut is set to determine the start date.

procinfo - reports the existing database processes in a summary table (only MySQL).
Typically only the own processes of the connection user (set in DbLog configuration file) will be reported. If all precesses have to be reported, the global "PROCESS" right has to be granted to the user.
As of MariaDB 5.3 for particular SQL-Statements a progress reporting will be provided (table row "PROGRESS"). So you can track, for instance, the degree of processing during an index creation.
Further informations can be found there.

svrinfo - common database server informations, e.g. DBMS-version, server address and port and so on. The quantity of elements to get depends on the database type. Using the attribute "showSvrInfo" the quantity of results can be limited to show only the desired values. Further detailed informations of items meaning are explained there.
tableinfo - access detailed informations about tables in MySQL database which is connected by the DbRep-device. All available tables in the connected database will be selected by default. Using theattribute "showTableInfo" the results can be limited to tables you want to show. Further detailed informations of items meaning are explained there.
versionNotes [hints | rel | <key>] - Shows realease informations and/or hints about the module. It contains only main release informations for module users.
If no options are specified, both release informations and hints will be shown. "rel" shows only release informations and "hints" shows only hints. By the <key>-specification only the hint with the specified number is shown.

Attributes

Note for SQL-Wildcard Usage:

except

aggregation - Aggregation of Device/Reading-selections. Possible values are hour, day, week, month, year and "no". Delivers e.g. the count of database entries for a day (countEntries), Summation of difference values of a reading (sumValue) and so on. Using aggregation "no" (default) an aggregation don't happens but the output contains all values of Device/Reading in the selected time period.

allowDeletion - unlocks the delete-function

averageCalcForm - specifies the calculation variant of average peak by "averageValue".

At the moment the following methods are implemented:

avgArithmeticMean :	the arithmetic average is calculated (default)
avgDailyMeanGWS :	calculates the daily medium temperature according the specifications of german weather service (pls. see "get <name> versionNotes 2"). This variant uses aggregation "day" automatically.
avgTimeWeightMean :	calculates a time weighted average mean value is calculated

countEntriesDetail - If set, the function countEntries creates a detailed report of counted datasets of every reading. By default only the summary of counted datasets is reported.

device - Selection of particular or several devices.
You can specify a list of devices separated by "," or use device specifications (devspec).
Inside of lists or device specifications a SQL wildcard (%) will be evaluated as a normal ASCII-character. The device names are derived from device specification and the active devices in FHEM before SQL selection will be carried out.
If the the device, list or device specification is prepended by "EXCLUDE=", the devices are excluded from database selection.
If you need more information about device specifications, execute "get <name> versionNotes 3".

diffAccept - valid for function diffValue. diffAccept determines the threshold, up to that a calaculated difference between two straight sequently datasets should be commenly accepted (default = 20).
Hence faulty DB entries with a disproportional high difference value will be eliminated and don't tamper the result. If a threshold overrun happens, the reading "diff_overrun_limit_<diffLimit>" will be generated (<diffLimit> will be substituted with the present prest attribute value).
The reading contains a list of relevant pair of values. Using verbose=3 this list will also be reported in the FHEM logfile.

disable - deactivates the module

dumpComment - User-comment. It will be included in the header of the created dumpfile by command "dumpMySQL clientSide".

dumpCompress - if set, the dump files are compressed after operation of "dumpMySQL" bzw. "dumpSQLite"

dumpDirLocal - Target directory of database dumps by command "dumpMySQL clientSide" (default: "{global}{modpath}/log/" on the FHEM-Server).
In this directory also the internal version administration searches for old backup-files and deletes them if the number exceeds attribute "dumpFilesKeep". The attribute is also relevant to publish a local mounted directory "dumpDirRemote" to DbRep.

dumpDirRemote - Target directory of database dumps by command "dumpMySQL serverSide" (default: the Home-directory of MySQL-Server on the MySQL-Host).

dumpMemlimit - tolerable memory consumption for the SQL-script during generation period (default: 100000 characters). Please adjust this parameter if you may notice memory bottlenecks and performance problems based on it on your specific hardware.

dumpSpeed - Number of Lines which will be selected in source database with one select by dump-command "dumpMySQL ClientSide" (default: 10000). This parameter impacts the run-time and consumption of resources directly.

dumpFilesKeep - The specified number of dumpfiles remain in the dump directory (default: 3). If there more (older) files has been found, these files will be deleted after a new database dump was created successfully. The global attrubute "archivesort" will be considered.

executeAfterProc - you can specify a FHEM command or perl function which should be executed after command execution.
Perl functions have to be enclosed in {} .

executeBeforeProc - you can specify a FHEM command or perl function which should be executed before command execution.
Perl functions have to be enclosed in {} .

expimpfile </path/file> [MAXLINES=<lines>] - Path/filename for data export/import.

The maximum number of datasets which are exported into one file can be specified with the optional parameter "MAXLINES". In this case several files with extensions "_part1", "_part2", "_part3" and so on are created.
The filename may contain wildcards which are replaced by corresponding values (see subsequent table). Furthermore filename can contain %-wildcards of the POSIX strftime function of the underlying OS (see your strftime manual).

%L	: is replaced by the value of global logdir attribute
%TSB	: is replaced by the (calculated) value of the timestamp_begin attribute

	Common used POSIX-wildcards are:
%d	: day of month (01..31)
%m	: month (01..12)
%Y	: year (1970...)
%w	: day of week (0..6); 0 represents Sunday
%j	: day of year (001..366)
%U	: week number of year with Sunday as first day of week (00..53)
%W	: week number of year with Monday as first day of week (00..53)

Examples:

attr <name> expimpfile /sds1/backup/exptest_%TSB.csv

attr <name> expimpfile /sds1/backup/exptest_%Y-%m-%d.csv

About POSIX wildcard usage please see also explanations in Filelog.

fastStart - Usually every DbRep device is making a short connect to its database when FHEM is started to retrieve some important informations and the reading "state" switches to "connected" on success. If this attrbute is set, the initial database connection is executed not till then the DbRep device is processing its first command.
While the reading "state" is remaining in state "initialized" after FHEM-start. This approach my be helpful if a lot of DbRep devices are defined.

fetchMarkDuplicates - Highlighting of multiple occuring datasets in result of "fetchrows" command

fetchRoute [descent | ascent] - specify the direction of data selection of the fetchrows-command.

ftpUse - FTP Transfer after dump will be switched on (without SSL encoding). The created database backup file will be transfered non-blocking to the FTP-Server (Attribut "ftpServer").

ftpUseSSL - FTP Transfer with SSL encoding after dump. The created database backup file will be transfered non-blocking to the FTP-Server (Attribut "ftpServer").

ftpUser - User for FTP-server login, default: "anonymous".

ftpDebug - debugging of FTP communication for diagnostics.

ftpDir - directory on FTP-server in which the file will be send into (default: "/").

ftpDumpFilesKeep - leave the number of dump files in FTP-destination <ftpDir> (default: 3). Are there more (older) dump files present, these files are deleted after a new dump was transfered successfully.

ftpPassive - set if passive FTP is to be used

ftpPort - FTP-Port, default: 21

ftpPwd - password of FTP-User, is not set by default

ftpServer - name or IP-address of FTP-server. absolutely essential !

ftpTimeout - timeout of FTP-connection in seconds (default: 30).

limit - limits the number of selected datasets by the "fetchrows", or the shown datasets of "delSeqDoublets adviceDelete", "delSeqDoublets adviceRemain" commands (default: 1000). This limitation should prevent the browser session from overload and avoids FHEMWEB from blocking. Please change the attribut according your requirements or change the selection criteria (decrease evaluation period).

optimizeTablesBeforeDump - if set to "1", the database tables will be optimized before executing the dump (default: 0). Thereby the backup run-time time will be extended.

reading - Selection of particular or several readings. More than one reading can be specified by a comma separated list.
If SQL wildcard (%) is set in a list, it will be evaluated as a normal ASCII-character.
If the reading or the reading-list is prepended by "EXCLUDE=", those readings are excluded from database selection.

readingNameMap - the name of the analyzed reading can be overwritten for output

role - the role of the DbRep-device. Standard role is "Client".
The role "Agent" is described in section DbRep-Agent.

readingPreventFromDel - comma separated list of readings which are should prevent from deletion when a new operation starts

seqDoubletsVariance - accepted variance (+/-) for the command "set <name> delSeqDoublets".
The value of this attribute describes the variance up to it consecutive numeric values (VALUE) of datasets are handled as identical and should be deleted. "seqDoubletsVariance" is an absolut numerical value, which is used as a positive as well as a negative variance.

showproctime - if set, the reading "sql_processing_time" shows the required execution time (in seconds) for the sql-requests. This is not calculated for a single sql-statement, but the summary of all sql-statements necessara for within an executed DbRep-function in background.

showStatus - limits the sample space of command "get <name> dbstatus". SQL-Wildcard (%) can be used.

showVariables - limits the sample space of command "get <name> dbvars". SQL-Wildcard (%) can be used.

showSvrInfo - limits the sample space of command "get <name> svrinfo". SQL-Wildcard (%) can be used.

showTableInfo - Determine the tablenames which are selected by command "get <name> tableinfo". SQL-Wildcard (%) can be used.

sqlCmdHistoryLength - Activates the command history of "sqlCmd" and determines the length of it.

sqlCmdVars - Set a SQL session variable or a PRAGMA every time before executing a SQL statement with "set <name> sqlCmd".

sqlResultFieldSep - determines the used field separator (default: "|") in the result of some sql-commands.

sqlResultFormat - determines the formatting of the "set <name> sqlCmd" command result. Possible options are:

timeYearPeriod - By this attribute an annual time period will be determined for database data selection. The time limits are calculated dynamically during execution time. Every time an annual period is determined. Periods of less than a year are not possible to set.
This attribute is particularly intended to make reports synchronous to an account period, e.g. of an energy- or gas provider.

timestamp_begin - begin of data selection
The format of timestamp is as used with DbLog "YYYY-MM-DD HH:MM:SS". For the attributes "timestamp_begin", "timestamp_end" you can also use one of the following entries. The timestamp-attribute will be dynamically set to:

timestamp_end - end of data selection. If not set the current date/time combination will be used.
The format of timestamp is as used with DbLog "YYYY-MM-DD HH:MM:SS". For the attributes "timestamp_begin", "timestamp_end" you can also use one of the following entries. The timestamp-attribute will be dynamically set to:
Make sure that "timestamp_begin" < "timestamp_end" is fulfilled.
Note
If the attribute "timeDiffToNow" will be set, the attributes "timestamp_begin" respectively "timestamp_end" will be deleted if they were set before. The setting of "timestamp_begin" respectively "timestamp_end" causes the deletion of attribute "timeDiffToNow" if it was set before as well.

timeDiffToNow - the begin time of data selection will be set to the timestamp "<current time> - <timeDiffToNow>" dynamically (e.g. if set to 86400, the last 24 hours are considered by data selection). The time period will be calculated dynamically at execution time.
If both attributes "timeDiffToNow" and "timeOlderThan" are set, the selection period will be calculated between of these timestamps dynamically.

timeOlderThan - the end time of data selection will be set to the timestamp "<aktuelle Zeit> - <timeOlderThan>" dynamically. Always the datasets up to timestamp "<current time> - <timeOlderThan>" will be considered (e.g. if set to 86400, all datasets older than one day are considered). The time period will be calculated dynamically at execution time.
If both attributes "timeDiffToNow" and "timeOlderThan" are set, the selection period will be calculated between of these timestamps dynamically.

timeout - set the timeout-value for Blocking-Call Routines in background in seconds (default 86400)

userExitFn - provides an interface to execute user specific program code.
To activate the interfaace at first you should implement the subroutine which will be called by the interface in your 99_myUtls.pm as shown in by the example:
```
        sub UserFunction {
          my ($name,$reading,$value) = @_;
          my $hash = $defs{$name};
          ...
          # e.g. output transfered data
          Log3 $name, 1, "UserExitFn $name called - transfer parameter are Reading: $reading, Value: $value " ;
          ...
        return;
        }
  	    
```
The interface activation takes place by setting the subroutine name into the attribute. Optional you may set a Reading:Value combination (Regex) as argument. If no Regex is specified, all value combinations will be evaluated as "true" (related to .*:.*).
The interface works generally without and independent from Events. If the attribute is set, after every reading generation the Regex will be evaluated. If the evaluation was "true", set subroutine will be called. For further processing following parameters will be forwarded to the function:
- $name - the name of the DbRep-Device
- $reading - the name of the created reading
- $value - the value of the reading

valueFilter - Regular expression (REGEXP) to filter datasets within particular functions. The REGEXP is applied to a particular field or to the whole selected dataset (inclusive Device, Reading and so on). Please consider the explanations within the set-commands. Further information is available with command "get <name> versionNotes 4".

Readings

state - contains the current state of evaluation. If warnings are occured (state = Warning) compare Readings "diff_overrun_limit_<diffLimit>" and "less_data_in_period"

errortext - description about the reason of an error state

background_processing_time - the processing time spent for operations in background/forked operation

sql_processing_time - the processing time wasted for all sql-statements used for an operation

diff_overrun_limit_<diffLimit> - contains a list of pairs of datasets which have overrun the threshold (<diffLimit>) of calculated difference each other determined by attribute "diffAccept" (default=20).

less_data_in_period - contains a list of time periods within only one dataset was found. The difference calculation considers the last value of the aggregation period before the current one. Valid for function "diffValue".

SqlResult - result of the last executed sqlCmd-command. The formatting can be specified by attribute "sqlResultFormat"

sqlCmd - contains the last executed sqlCmd-command

DbRep Agent - automatic change of device names in databases and DbRep-definitions after FHEM "rename" command

in the database connected to the DbRep-Agent (Internal Database) dataset containing the old device name will be searched and renamed to the to the new device name in all affected datasets.

in the DbLog-Device assigned to the DbRep-Agent the definition will be changed to substitute the old device name by the new one. Thereby the logging of the renamed device will be going on in the database.

in other existing DbRep-definitions with Type "Client" a possibly set attribute "device = old device name" will be changed to "device = new device name". Because of that, reporting definitions will be kept consistent automatically if devices are renamed in FHEM.

within a FHEM installation only one DbRep-Agent can be configured for every defined DbLog-database. That means, if more than one DbLog-database is present, you could define same numbers of DbRep-Agents as well as DbLog-devices are defined.

after changing to DbRep-Agent role only the set-command "renameDevice" will be available and as well as a reduced set of module specific attributes will be permitted. If a DbRep-device of privious type "Client" has changed an Agent, furthermore not permitted attributes will be deleted if set.

Example


        define Rep.Agent DbRep LogDB  

        attr Rep.Agent devStateIcon connected:10px-kreis-gelb .*disconnect:10px-kreis-rot .*done:10px-kreis-gruen 

        attr Rep.Agent icon security      

        attr Rep.Agent role Agent         

        attr Rep.Agent room DbLog         

        attr Rep.Agent showproctime 1     

        attr Rep.Agent stateFormat { ReadingsVal("$name","state", undef) eq "running" ? "renaming" : ReadingsVal("$name","state", undef). " »; ProcTime: ".ReadingsVal("$name","sql_processing_time", undef)." sec"}  

        attr Rep.Agent timeout 86400

Note:

=end html =begin html_DE

DbRep

Selektion aller Datensätze innerhalb einstellbarer Zeitgrenzen
Darstellung der Datensätze einer Device/Reading-Kombination innerhalb einstellbarer Zeitgrenzen.
Selektion der Datensätze unter Verwendung von dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt.
Dubletten-Hervorhebung bei Datensatzanzeige (fetchrows)
Berechnung der Anzahl von Datensätzen einer Device/Reading-Kombination unter Berücksichtigung von Zeitgrenzen und verschiedenen Aggregationen.
Die Berechnung von Summen-, Differenz-, Maximum-, Minimum- und Durchschnittswerten numerischer Readings in Zeitgrenzen und verschiedenen Aggregationen.
Speichern von Summen-, Differenz- , Maximum- , Minimum- und Durchschnittswertberechnungen in der Datenbank
Löschung von Datensätzen. Die Eingrenzung der Löschung kann durch Device und/oder Reading sowie fixer oder dynamisch berechneter Zeitgrenzen zum Ausführungszeitpunkt erfolgen.
Export von Datensätzen in ein File im CSV-Format
Import von Datensätzen aus File im CSV-Format
Umbenennen von Device/Readings in Datenbanksätzen
Ändern von Reading-Werten (VALUES) in der Datenbank (changeValue)
automatisches Umbenennen von Device-Namen in Datenbanksätzen und DbRep-Definitionen nach FHEM "rename" Befehl (siehe DbRep-Agent)
Ausführen von beliebigen Benutzer spezifischen SQL-Kommandos (non-blocking)
Ausführen von beliebigen Benutzer spezifischen SQL-Kommandos (blocking) zur Verwendung in eigenem Code (dbValue)
Backups der FHEM-Datenbank im laufenden Betrieb erstellen (MySQL, SQLite)
senden des Dumpfiles zu einem FTP-Server nach dem Backup incl. Versionsverwaltung
Restore von SQLite- und MySQL-Dumps
Optimierung der angeschlossenen Datenbank (optimizeTables, vacuum)
Ausgabe der existierenden Datenbankprozesse (MySQL)
leeren der current-Tabelle
Auffüllen der current-Tabelle mit einem (einstellbaren) Extrakt der history-Tabelle
Bereinigung sequentiell aufeinander folgender Datensätze mit unterschiedlichen Zeitstempel aber gleichen Werten (sequentielle Dublettenbereinigung)
Reparatur einer korrupten SQLite Datenbank ("database disk image is malformed")
Übertragung von Datensätzen aus der Quelldatenbank in eine andere (Standby) Datenbank (syncStandby)
Reduktion der Anzahl von Datensätzen in der Datenbank (reduceLog)
Löschen von doppelten Datensätzen (delDoublets)

Autorename

DbRep-Agent

UserExit

Modul 93_DbRep - Reporting und Management von Datenbankinhalten (DbLog)

DbReadingsVal

DbReadingsVal("<name>","<device:reading>","<timestamp>","<default>")

Beispiele:

<name>	: Name des abzufragenden DbRep-Device
<device:reading>	: Device:Reading dessen Wert geliefert werden soll
<timestamp>	: Zeitpunkt des zu liefernden Readingwertes (*) in der Form "YYYY-MM-DD hh:mm:ss"
<default>	: Defaultwert falls kein Readingwert ermittelt werden konnte

DbRep - Reporting und Management von DbLog-Datenbankinhalten

Voraussetzungen


  CREATE INDEX Report_Idx ON `history` (TIMESTAMP, READING) USING BTREE;

Definition


    define <name> DbRep <Name der DbLog-Instanz>

nicht

Set

averageValue [display | writeToDB] - berechnet einen Durchschnittswert des Datenbankfelds "VALUE" in den gegebenen Zeitgrenzen ( siehe Attribute). Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein.
Mit dem Attribut "averageCalcForm" wird die Berechnungsvariante zur Mittelwertermittlung definiert. Ist keine oder die Option "display" angegeben, werden die Ergebnisse nur angezeigt. Mit der Option "writeToDB" werden die Berechnungsergebnisse mit einem neuen Readingnamen in der Datenbank gespeichert.
Der neue Readingname wird aus einem Präfix und dem originalen Readingnamen gebildet, wobei der originale Readingname durch das Attribut "readingNameMap" ersetzt werden kann. Der Präfix setzt sich aus der Bildungsfunktion und der Aggregation zusammen.
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. Das Feld "EVENT" wird mit "calculated" gefüllt.

Beispiel neuer Readingname gebildet aus dem Originalreading "totalpac":

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

aggregation	: Auswahl einer Aggregationsperiode
averageCalcForm	: Auswahl der Berechnungsvariante für den Durchschnitt
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start Operation
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende Operation
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

cancelDump - bricht einen laufenden Datenbankdump ab.

changeValue - ändert den gespeicherten Wert eines Readings. Ist die Selektion auf bestimmte Device/Reading-Kombinationen durch die Attribute "device" bzw. "reading" beschränkt, werden sie genauso berücksichtigt wie gesetzte Zeitgrenzen (Attribute time.*).
Fehlen diese Beschränkungen, wird die gesamte Datenbank durchsucht und der angegebene Wert geändert.

Syntax:

<old string> :	ein einfacher String mit/ohne Leerzeichen, z.B. "OL 12" ein String mit Verwendung von SQL-Wildcard, z.B. "%OL%"
<new string> :	ein einfacher String mit/ohne Leerzeichen, z.B. "12 kWh" Perl Code eingeschlossen in "{}" inkl. Quotes, z.B. "{($VALUE,$UNIT) = split(" ",$VALUE)}". Dem Perl-Ausdruck werden die Variablen $VALUE und $UNIT übergeben. Sie können innerhalb des Perl-Code geändert werden. Der zurückgebene Wert von $VALUE und $UNIT wird in dem Feld VALUE bzw. UNIT des Datensatzes gespeichert.

Beispiele:

device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
aggregation	: Auswahl einer Aggregationsperiode
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start changeValue
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende changeValue
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

Hinweis:

countEntries [history | current] - liefert die Anzahl der Tabelleneinträge (default: history) in den gegebenen Zeitgrenzen (siehe Attribute). Sind die Timestamps nicht gesetzt, werden alle Einträge der Tabelle gezählt. Beschränkungen durch die Attribute Device bzw. Reading gehen in die Selektion mit ein.
Standardmäßig wird die Summe aller Datensätze, gekennzeichnet mit "ALLREADINGS", erstellt. Ist das Attribut "countEntriesDetail" gesetzt, wird die Anzahl jedes einzelnen Readings zusätzlich ausgegeben.

Die für diese Funktion relevanten Attribute sind:

aggregation	: Zusammenfassung/Gruppierung von Zeitintervallen
countEntriesDetail	: detaillierte Ausgabe der Datensatzanzahl
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

delDoublets [adviceDelete | delete] - zeigt bzw. löscht doppelte / mehrfach vorkommende Datensätze. Dazu wird Timestamp, Device,Reading und Value ausgewertet.
Die Attribute zur Aggregation,Zeit-,Device- und Reading-Abgrenzung werden dabei berücksichtigt. Ist das Attribut "aggregation" nicht oder auf "no" gesetzt, wird im Standard die Aggregation "day" verwendet.

adviceDelete	: ermittelt die zu löschenden Datensätze (es wird nichts gelöscht !)
delete	: löscht die Dubletten

Aus Sicherheitsgründen muss das Attribut "allowDeletion" für die "delete" Option gesetzt sein.
Die Anzahl der anzuzeigenden Datensätze des Kommandos "delDoublets adviceDelete" ist zunächst begrenzt (default 1000) und kann durch das Attribut "limit" angepasst werden. Die Einstellung von "limit" hat keinen Einfluss auf die "delDoublets delete" Funktion, sondern beeinflusst NUR die Anzeige der Daten.
Vor und nach der Ausführung von "delDoublets" kann ein FHEM-Kommando bzw. Perl-Routine ausgeführt werden. (siehe Attribute "executeBeforeProc", "executeAfterProc")

Beispiel:

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

allowDeletion	: needs to be set to execute the delete option
aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
limit	: begrenzt NUR die Anzahl der anzuzeigenden Datensätze
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start des Befehls
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende des Befehls
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

delEntries - löscht alle oder die durch die Attribute device und/oder reading definierten Datenbankeinträge. Die Eingrenzung über Timestamps erfolgt folgendermaßen:

bis

zwischen

älter

Aus Sicherheitsgründen muss das Attribut "allowDeletion" gesetzt sein um die Löschfunktion freizuschalten.

Die zur Steuerung von delEntries relevanten Attribute:

allowDeletion	: Freischaltung der Löschfunktion
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start delEntries
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende delEntries
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

delSeqDoublets [adviceRemain | adviceDelete | delete] - zeigt bzw. löscht aufeinander folgende identische Datensätze. Dazu wird Device,Reading und Value ausgewertet. Nicht gelöscht werden der erste und der letzte Datensatz einer Aggregationsperiode (z.B. hour, day, week usw.) sowie die Datensätze vor oder nach einem Wertewechsel (Datenbankfeld VALUE).
Die Attribute zur Aggregation,Zeit-,Device- und Reading-Abgrenzung werden dabei berücksichtigt. Ist das Attribut "aggregation" nicht oder auf "no" gesetzt, wird als Standard die Aggregation "day" verwendet. Für Datensätze mit numerischen Werten kann mit dem Attribut "seqDoubletsVariance" eine Abweichung eingestellt werden, bis zu der aufeinander folgende numerische Werte als identisch angesehen und gelöscht werden sollen.

adviceRemain	: simuliert die nach der Operation in der DB verbleibenden Datensätze (es wird nichts gelöscht !)
adviceDelete	: simuliert die zu löschenden Datensätze (es wird nichts gelöscht !)
delete	: löscht die sequentiellen Dubletten (siehe Beispiel)

Aus Sicherheitsgründen muss das Attribut "allowDeletion" für die "delete" Option gesetzt sein.
Die Anzahl der anzuzeigenden Datensätze der Kommandos "delSeqDoublets adviceDelete", "delSeqDoublets adviceRemain" ist zunächst begrenzt (default 1000) und kann durch das Attribut "limit" angepasst werden. Die Einstellung von "limit" hat keinen Einfluss auf die "delSeqDoublets delete" Funktion, sondern beeinflusst NUR die Anzeige der Daten.
Vor und nach der Ausführung von "delSeqDoublets" kann ein FHEM-Kommando bzw. Perl-Routine ausgeführt werden. (siehe Attribute "executeBeforeProc", "executeAfterProc")

Beispiel

fett

2017-11-25_00-00-05__eg.az.fridge_Pwr__power 0

2017-11-25_01-08-21__eg.az.fridge_Pwr__power 0

2017-11-25_01-08-59__eg.az.fridge_Pwr__power 60.32

2017-11-25_01-11-21__eg.az.fridge_Pwr__power 56.26

2017-11-25_01-27-54__eg.az.fridge_Pwr__power 6.19

2017-11-25_01-28-51__eg.az.fridge_Pwr__power 0

2017-11-25_02-39-29__eg.az.fridge_Pwr__power 0

2017-11-25_02-41-18__eg.az.fridge_Pwr__power 105.28

2017-11-25_02-41-26__eg.az.fridge_Pwr__power 61.52

2017-11-25_03-00-06__eg.az.fridge_Pwr__power 47.46

2017-11-25_03-00-33__eg.az.fridge_Pwr__power 0

2017-11-25_23-40-10__eg.az.fridge_Pwr__power 0

2017-11-25_23-42-24__eg.az.fridge_Pwr__power 1

2017-11-25_23-45-27__eg.az.fridge_Pwr__power 1

2017-11-25_23-47-07__eg.az.fridge_Pwr__power 0

2017-11-25_23-48-15__eg.az.fridge_Pwr__power 0

2017-11-25_23-50-21__eg.az.fridge_Pwr__power 59.1

2017-11-25_23-55-14__eg.az.fridge_Pwr__power 52.31

2017-11-25_23-58-09__eg.az.fridge_Pwr__power 51.73

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

allowDeletion	: needs to be set to execute the delete option
aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
limit	: begrenzt NUR die Anzahl der anzuzeigenden Datensätze
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
seqDoubletsVariance	: bis zu diesem Wert werden aufeinander folgende numerische Datensätze als identisch angesehen und werden gelöscht
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start des Befehls
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende des Befehls
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

deviceRename <old_name>,<new_name> - benennt den Namen eines Device innerhalb der angeschlossenen Datenbank (Internal DATABASE) um. Der Gerätename wird immer in der gesamten Datenbank umgesetzt. Eventuell gesetzte Zeitgrenzen oder Beschränkungen durch die Attribute Device bzw. Reading werden nicht berücksichtigt.

diffValue [display | writeToDB] - berechnet den Differenzwert des Datenbankfelds "VALUE" in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading im Attribut "reading" angegeben sein. Diese Funktion ist z.B. zur Auswertung von Eventloggings sinnvoll, deren Werte sich fortlaufend erhöhen und keine Wertdifferenzen wegschreiben.
Es wird immer die Differenz aus dem Value-Wert des ersten verfügbaren Datensatzes und dem Value-Wert des letzten verfügbaren Datensatzes innerhalb der angegebenen Zeitgrenzen/Aggregation gebildet, wobei ein Übertragswert der Vorperiode (Aggregation) zur darauf folgenden Aggregationsperiode berücksichtigt wird sofern diese einen Value-Wert enhtält.
Dabei wird ein Zählerüberlauf (Neubeginn bei 0) mit berücksichtigt (vergleiche Attribut "diffAccept").
Wird in einer auszuwertenden Zeit- bzw. Aggregationsperiode nur ein Datensatz gefunden, kann die Differenz in Verbindung mit dem Differenzübertrag der Vorperiode berechnet werden. in diesem Fall kann es zu einer logischen Ungenauigkeit in der Zuordnung der Differenz zu der Aggregationsperiode kommen. Deswegen wird eine Warnung im "state" und das Reading "less_data_in_period" mit einer Liste der betroffenen Perioden wird erzeugt.

Hinweis:

Ist keine oder die Option "display" angegeben, werden die Ergebnisse nur angezeigt. Mit der Option "writeToDB" werden die Berechnungsergebnisse mit einem neuen Readingnamen in der Datenbank gespeichert.
Der neue Readingname wird aus einem Präfix und dem originalen Readingnamen gebildet, wobei der originale Readingname durch das Attribut "readingNameMap" ersetzt werden kann. Der Präfix setzt sich aus der Bildungsfunktion und der Aggregation zusammen.
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. Das Feld "EVENT" wird mit "calculated" gefüllt.

Beispiel neuer Readingname gebildet aus dem Originalreading "totalpac":

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start Operation
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende Operation
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

dumpMySQL [clientSide | serverSide] - erstellt einen Dump der angeschlossenen MySQL-Datenbank.
Abhängig von der ausgewählten Option wird der Dump auf der Client- bzw. Serverseite erstellt.
Die Varianten unterscheiden sich hinsichtlich des ausführenden Systems, des Erstellungsortes, der Attributverwendung, des erzielten Ergebnisses und der benötigten Hardwareressourcen.
Die Option "clientSide" benötigt z.B. eine leistungsfähigere Hardware des FHEM-Servers, sichert aber alle Tabellen inklusive eventuell angelegter Views.
Mit dem Attribut "dumpCompress" kann eine Komprimierung der erstellten Dumpfiles eingeschaltet werden.

Option clientSide

Achtung !
Um ein Blockieren von FHEM zu vermeiden, muß DbLog im asynchronen Modus betrieben werden wenn die Tabellenoptimierung verwendet wird !

dumpComment	: User-Kommentar im Dumpfile
dumpCompress	: Komprimierung des Dumpfiles nach der Erstellung
dumpDirLocal	: das lokale Zielverzeichnis für die Erstellung des Dump
dumpMemlimit	: Begrenzung der Speicherverwendung
dumpSpeed	: Begrenzung die CPU-Belastung
dumpFilesKeep	: Anzahl der aufzubwahrenden Dumpfiles
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor dem Dump
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach dem Dump
optimizeTablesBeforeDump	: Tabelloptimierung vor dem Dump ausführen

Namenskonvention der Dumpfiles

Option serverSide

im CSV-Format

Achtung !
Um ein Blockieren von FHEM zu vermeiden, muß DbLog im asynchronen Modus betrieben werden wenn die Tabellenoptimierung verwendet wird !

dumpDirRemote	: das Erstellungsverzeichnis des Dumpfile auf dem entfernten Server
dumpCompress	: Komprimierung des Dumpfiles nach der Erstellung
dumpDirLocal	: Directory des lokal gemounteten dumpDirRemote-Verzeichnisses
dumpFilesKeep	: Anzahl der aufzubwahrenden Dumpfiles
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor dem Dump
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach dem Dump
optimizeTablesBeforeDump	: Tabelloptimierung vor dem Dump ausführen

Hinweis:

Beispiel:

Namenskonvention der Dumpfiles

FTP Transfer nach Dump

ftpUse	: FTP Transfer nach dem Dump wird eingeschaltet (ohne SSL Verschlüsselung)
ftpUser	: User zur Anmeldung am FTP-Server, default: anonymous
ftpUseSSL	: FTP Transfer mit SSL Verschlüsselung nach dem Dump wird eingeschaltet
ftpDebug	: Debugging des FTP Verkehrs zur Fehlersuche
ftpDir	: Verzeichnis auf dem FTP-Server in welches das File übertragen werden soll (default: "/")
ftpDumpFilesKeep	: Es wird die angegebene Anzahl Dumpfiles im <ftpDir> belassen (default: 3)
ftpPassive	: setzen wenn passives FTP verwendet werden soll
ftpPort	: FTP-Port, default: 21
ftpPwd	: Passwort des FTP-Users, default nicht gesetzt
ftpServer	: Name oder IP-Adresse des FTP-Servers. notwendig !
ftpTimeout	: Timeout für die FTP-Verbindung in Sekunden (default: 30).

dumpSQLite - erstellt einen Dump der angeschlossenen SQLite-Datenbank.
Diese Funktion nutzt die SQLite Online Backup API und ermöglicht es konsistente Backups der SQLite-DB in laufenden Betrieb zu erstellen. Der Dump wird per default im log-Verzeichnis des FHEM-Rechners gespeichert. Das Zielverzeichnis kann mit dem Attribut "dumpDirLocal" verändert werden und muß durch FHEM beschreibbar sein. Vor dem Dump kann optional eine Tabellenoptimierung (Attribut "optimizeTablesBeforeDump") zugeschaltet werden.

Achtung !
Um ein Blockieren von FHEM zu vermeiden, muß DbLog im asynchronen Modus betrieben werden wenn die Tabellenoptimierung verwendet wird !

Vor und nach dem Dump kann ein FHEM-Kommando (siehe Attribute "executeBeforeProc", "executeAfterProc") ausgeführt werden.

Die für diese Funktion relevanten Attribute sind:

dumpCompress	: Komprimierung des Dumpfiles nach der Erstellung
dumpDirLocal	: Directory des lokal gemounteten dumpDirRemote-Verzeichnisses
dumpFilesKeep	: Anzahl der aufzubwahrenden Dumpfiles
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor dem Dump
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach dem Dump
optimizeTablesBeforeDump	: Tabelloptimierung vor dem Dump ausführen

Nach einem erfolgreichen Dump werden alte Dumpfiles gelöscht und nur die Anzahl Files, definiert durch das Attribut "dumpFilesKeep" (default: 3), verbleibt im Zielverzeichnis "dumpDirLocal". Falls "dumpFilesKeep = 0" gesetzt, werden alle Dumpfiles (auch das aktuell erstellte File), gelöscht. Diese Einstellung kann sinnvoll sein, wenn FTP aktiviert ist und die erzeugten Dumps nur im FTP-Zielverzeichnis erhalten bleiben sollen.

Die Namenskonvention der Dumpfiles ist: <dbname>_<date>_<time>.sqlitebkp[.gzip]

Die Datenbank kann mit "set <name> restoreSQLite <Filename>" wiederhergestellt werden.
Das erstellte Dumpfile kann auf einen FTP-Server übertragen werden. Siehe dazu die Erläuterungen unter "dumpMySQL".

eraseReadings - Löscht alle angelegten Readings im Device, außer dem Reading "state" und Readings, die in der Ausnahmeliste definiert mit Attribut "readingPreventFromDel" enthalten sind.

exportToFile [</Pfad/File>] [MAXLINES=<lines>] - exportiert DB-Einträge im CSV-Format in den gegebenen Zeitgrenzen.

Der Dateiname wird durch das Attribut "expimpfile" bestimmt. Alternativ kann "/Pfad/File" als Kommando-Option angegeben werden und übersteuert ein eventuell gesetztes Attribut "expimpfile". Optional kann über den Parameter "MAXLINES" die maximale Anzahl von Datensätzen angegeben werden, die in ein File exportiert werden. In diesem Fall werden mehrere Files mit den Extensions "_part1", "_part2", "_part3" usw. erstellt (beim Import berücksichtigen !).

Einschränkungen durch die Attribute "device" bzw. "reading" gehen in die Selektion mit ein. Der Dateiname kann Wildcards enthalten (siehe Attribut "expimpfile").
Durch das Attribut "aggregation" wird der Export der Datensätze in Zeitscheiben der angegebenen Aggregation vorgenommen. Ist z.B. "aggregation = month" gesetzt, werden die Daten in monatlichen Paketen selektiert und in das Exportfile geschrieben. Dadurch wird die Hauptspeicherverwendung optimiert wenn sehr große Datenmengen exportiert werden sollen und vermeidet den "died prematurely" Abbruchfehler.

Die für diese Funktion relevanten Attribute sind:

aggregation	: Festlegung der Selektionspaketierung
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor dem Export ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach dem Export ausführen
expimpfile	: der Name des Exportfiles
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

fetchrows [history|current] - liefert alle Tabelleneinträge (default: history) in den gegebenen Zeitgrenzen bzw. Selektionsbedingungen durch die Attribute "device" und "reading". Eine evtl. gesetzte Aggregation wird dabei nicht berücksichtigt.
Die Leserichtung in der Datenbank kann durch das Attribut "fetchRoute" bestimmt werden.

Jedes Ergebnisreading setzt sich aus dem Timestring des Datensatzes, einem Index, dem Device und dem Reading zusammen. Die Funktion fetchrows ist in der Lage, mehrfach vorkommende Datensätze (Dubletten) zu erkennen. Solche Dubletten sind mit einem Index > 1 gekennzeichnet.
Dubletten können mit dem Attribut "fetchMarkDuplicates" farblich hervorgehoben werden.

Hinweis:
Hervorgehobene Readings werden nach einem Restart bzw. nach rereadcfg nicht mehr angezeigt da sie nicht im statefile gesichert werden (Verletzung erlaubter Readingnamen durch Formatierung).

Dieses Attribut ist mit einigen Farben vorbelegt, kann aber mit dem colorpicker-Widget überschrieben werden:


                                 attr <name> widgetOverride fetchMarkDuplicates:colorpicker

Die Ergebnisreadings von fetchrows sind nach folgendem Schema aufgebaut:

Beispiel:

Zur besseren Übersicht sind die zur Steuerung von fetchrows relevanten Attribute hier noch einmal dargestellt:

fetchRoute	: Leserichtung der Selektion innerhalb der Datenbank
limit	: begrenzt die Anzahl zu selektierenden bzw. anzuzeigenden Datensätze
fetchMarkDuplicates	: Hervorhebung von gefundenen Dubletten
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: filtert die anzuzeigenden Datensätze mit einem regulären Ausdruck. Der Regex wird auf Werte des DAtenbankfelder 'VALUE' angewendet.

Hinweis:
Auch wenn das Modul bezüglich der Datenbankabfrage nichtblockierend arbeitet, kann eine zu große Ergebnismenge (Anzahl Zeilen bzw. Readings) die Browsersesssion bzw. FHEMWEB blockieren. Aus diesem Grund wird die Ergebnismenge mit dem Attribut "limit" begrenzt. Bei Bedarf kann dieses Attribut geändert werden, falls eine Anpassung der Selektionsbedingungen nicht möglich oder gewünscht ist.

insert - Manuelles Einfügen eines Datensatzes in die Tabelle "history". Obligatorisch sind Eingabewerte für Datum, Zeit und Value. Die Werte für die DB-Felder Type bzw. Event werden mit "manual" gefüllt, sowie die Werte für Device, Reading aus den gesetzten Attributen genommen.

importFromFile [<File>] - importiert Datensätze im CSV-Format aus einer Datei in die Datenbank.
Der Dateiname wird durch das Attribut "expimpfile" bestimmt.
Alternativ kann die Datei (/Pfad/Datei) als Kommando-Option angegeben werden und übersteuert ein eventuell gesetztes Attribut "expimpfile". Der Dateiname kann Wildcards enthalten (siehe Attribut "expimpfile").

Datensatzformat:

Beispiel:

executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor dem Import ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach dem Import ausführen
expimpfile	: der Name des Importfiles

maxValue [display | writeToDB] - berechnet den Maximalwert des Datenbankfelds "VALUE" in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein. Die Auswertung enthält den Zeitstempel des ermittelten Maximumwertes innerhalb der Aggregation bzw. Zeitgrenzen. Im Reading wird der Zeitstempel des letzten Auftretens vom Maximalwert ausgegeben falls dieser Wert im Intervall mehrfach erreicht wird.
Ist keine oder die Option "display" angegeben, werden die Ergebnisse nur angezeigt. Mit der Option "writeToDB" werden die Berechnungsergebnisse mit einem neuen Readingnamen in der Datenbank gespeichert.
Der neue Readingname wird aus einem Präfix und dem originalen Readingnamen gebildet, wobei der originale Readingname durch das Attribut "readingNameMap" ersetzt werden kann. Der Präfix setzt sich aus der Bildungsfunktion und der Aggregation zusammen.
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. Das Feld "EVENT" wird mit "calculated" gefüllt.

Beispiel neuer Readingname gebildet aus dem Originalreading "totalpac":

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start Operation
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende Operation
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

minValue [display | writeToDB] - berechnet den Minimalwert des Datenbankfelds "VALUE" in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading über das Attribut "reading" angegeben sein. Die Auswertung enthält den Zeitstempel des ermittelten Minimumwertes innerhalb der Aggregation bzw. Zeitgrenzen. Im Reading wird der Zeitstempel des ersten Auftretens vom Minimalwert ausgegeben falls dieser Wert im Intervall mehrfach erreicht wird.
Ist keine oder die Option "display" angegeben, werden die Ergebnisse nur angezeigt. Mit der Option "writeToDB" werden die Berechnungsergebnisse mit einem neuen Readingnamen in der Datenbank gespeichert.
Der neue Readingname wird aus einem Präfix und dem originalen Readingnamen gebildet, wobei der originale Readingname durch das Attribut "readingNameMap" ersetzt werden kann. Der Präfix setzt sich aus der Bildungsfunktion und der Aggregation zusammen.
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. Das Feld "EVENT" wird mit "calculated" gefüllt.

Beispiel neuer Readingname gebildet aus dem Originalreading "totalpac":

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start Operation
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende Operation
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

optimizeTables - optimiert die Tabellen in der angeschlossenen Datenbank (MySQL).
Vor und nach der Optimierung kann ein FHEM-Kommando ausgeführt werden. (siehe Attribute "executeBeforeProc", "executeAfterProc")
readingRename <[Device:]alterReadingname>,<neuerReadingname>
Benennt den Namen eines Readings innerhalb der angeschlossenen Datenbank (siehe Internal DATABASE) um. Der Readingname wird immer in der gesamten Datenbank umgesetzt. Eventuell gesetzte Zeitgrenzen oder Beschränkungen durch die Attribute Device bzw. Reading werden nicht berücksichtigt.
Optional kann eine Device angegeben werden. In diesem Fall werden nur die alten Readings dieses Devices in den neuen Readingnamen umgesetzt.
Die Anzahl der umbenannten Device-Datensätze wird im Reading "reading_renamed" ausgegeben.
Wird der umzubenennende Readingname in der Datenbank nicht gefunden, wird eine WARNUNG im Reading "reading_not_renamed" ausgegeben.
Entsprechende Einträge erfolgen auch im Logfile mit verbose=3.

Hinweis:
Obwohl die Funktion selbst non-blocking ausgelegt ist, sollte das zugeordnete DbLog-Device im asynchronen Modus betrieben werden um ein Blockieren von FHEMWEB zu vermeiden (Tabellen-Lock).

reduceLog [average[=day]]
Reduziert historische Datensätze innerhalb der durch die "time.*"-Attribute bestimmten Zeitgrenzen auf einen Eintrag (den ersten) pro Stunde je Device & Reading. Es muss mindestens eines der "time.*"-Attribute gesetzt sein (siehe Tabelle unten). Die jeweils fehlende Zeitabgrenzung wird in diesem Fall durch das Modul errechnet.

Durch die optionale Angabe von 'average' wird nicht nur die Datenbank bereinigt, sondern alle numerischen Werte einer Stunde werden auf einen einzigen Mittelwert reduziert. Mit der Option 'average=day' werden alle numerischen Werte eines Tages auf einen einzigen Mittelwert reduziert (impliziert 'average').

Mit den Attributen "device" und "reading" können die zu berücksichtigenden Datensätze eingeschlossen bzw. ausgeschlossen werden. Beide Eingrenzungen reduzieren die selektierten Daten und verringern den Ressourcenbedarf. Das Reading "reduceLogState" enthält das Ausführungsergebnis des letzten reduceLog-Befehls.

Die für diese Funktion relevanten Attribute sind:

executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor dem Export ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach dem Export ausführen
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
timeOlderThan	: es werden Datenbankeinträge älter als dieses Attribut reduziert
timestamp_end	: es werden Datenbankeinträge älter als dieses Attribut reduziert
timeDiffToNow	: es werden Datenbankeinträge neuer als dieses Attribut reduziert
timestamp_begin	: es werden Datenbankeinträge neuer als dieses Attribut reduziert
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

Aus Kompatibilitätsgründen kann der Befehl optional durch die Zusätze "EXCLUDE" bzw. "INCLUDE" ergänzt werden um device/reading Kombinationen von reduceLog auszuschließen bzw. einzuschließen:

Diese Angabe wird als Regex ausgewertet und überschreibt die Attribute "device" und "reading", die in diesem Fall nicht beachtet werden.

Beispiele:

Hinweis:
Obwohl die Funktion selbst non-blocking ausgelegt ist, sollte das zugeordnete DbLog-Device im asynchronen Modus betrieben werden um ein Blockieren von FHEMWEB zu vermeiden (Tabellen-Lock).
Weiterhin wird dringend empfohlen den standard INDEX 'Search_Idx' in der Tabelle 'history' anzulegen !
Die Abarbeitung dieses Befehls dauert unter Umständen (ohne INDEX) extrem lange.

repairSQLite - repariert eine korrupte SQLite-Datenbank.
Eine Korruption liegt im Allgemeinen vor wenn die Fehlermitteilung "database disk image is malformed" im state des DbLog-Devices erscheint. Wird dieses Kommando gestartet, wird das angeschlossene DbLog-Device zunächst automatisch für 10 Stunden (36000 Sekunden) von der Datenbank getrennt (Trennungszeit). Nach Abschluss der Reparatur erfolgt wieder eine sofortige Neuverbindung zur reparierten Datenbank.
Dem Befehl kann eine abweichende Trennungszeit (in Sekunden) als Argument angegeben werden.
Die korrupte Datenbank wird als <database>.corrupt im gleichen Verzeichnis gespeichert.
restoreMySQL <File> - stellt die Datenbank aus einem serverSide- oder clientSide-Dump wieder her.
Die Funktion stellt über eine Drop-Down Liste eine Dateiauswahl für den Restore zur Verfügung.

Verwendung eines serverSide-Dumps
Es wird der Inhalt der history-Tabelle aus einem serverSide-Dump wiederhergestellt. Dazu ist das Verzeichnis "dumpDirRemote" des MySQL-Servers auf dem Client zu mounten und im Attribut "dumpDirLocal" dem DbRep-Device bekannt zu machen.
Es werden alle Files mit der Endung "csv[.gzip]" und deren Name mit der verbundenen Datenbank beginnt (siehe Internal DATABASE), aufgelistet.

Verwendung eines clientSide-Dumps
Es werden alle Tabellen und eventuell vorhandenen Views wiederhergestellt. Das Verzeichnis, in dem sich die Dump-Files befinden, ist im Attribut "dumpDirLocal" dem DbRep-Device bekannt zu machen.
Es werden alle Files mit der Endung "sql[.gzip]" und deren Name mit der verbundenen Datenbank beginnt (siehe Internal DATABASE), aufgelistet.
Die Geschwindigkeit des Restores ist abhängig von der Servervariable "max_allowed_packet". Durch Veränderung dieser Variable im File my.cnf kann die Geschwindigkeit angepasst werden. Auf genügend verfügbare Ressourcen (insbesondere RAM) ist dabei zu achten.

Der Datenbankuser benötigt Rechte zum Tabellenmanagement, z.B.:
CREATE, ALTER, INDEX, DROP, SHOW VIEW, CREATE VIEW

restoreSQLite <File>.sqlitebkp[.gzip] - stellt das Backup einer SQLite-Datenbank wieder her.
Die Funktion stellt über eine Drop-Down Liste die für den Restore zur Verfügung stehenden Dateien zur Verfügung. Die aktuell in der Zieldatenbank enthaltenen Daten werden gelöscht bzw. überschrieben. Es werden alle Files mit der Endung "sqlitebkp[.gzip]" und deren Name mit dem Namen der verbundenen Datenbank beginnt, aufgelistet .

sqlCmd - führt ein beliebiges benutzerspezifisches Kommando aus.
Enthält dieses Kommando eine Delete-Operation, muss zur Sicherheit das Attribut "allowDeletion" gesetzt sein.
Bei der Ausführung dieses Kommandos werden keine Einschränkungen durch gesetzte Attribute "device", "reading", "time.*" bzw. "aggregation" berücksichtigt.
Dieses Kommando akzeptiert ebenfalls das Setzen von SQL Session Variablen wie z.B. "SET @open:=NULL, @closed:=NULL;" oder die Verwendung von SQLite PRAGMA vor der Ausführung des SQL-Statements. Soll die Session Variable oder das PRAGMA vor jeder Ausführung eines SQL Statements gesetzt werden, kann dafür das Attribut "sqlCmdVars" verwendet werden.
Sollen die im Modul gesetzten Attribute "timestamp_begin" bzw. "timestamp_end" im Statement berücksichtigt werden, können die Platzhalter "§timestamp_begin§" bzw. "§timestamp_end§" dafür verwendet werden.

Soll ein Datensatz upgedated werden, ist dem Statement "TIMESTAMP=TIMESTAMP" hinzuzufügen um eine Änderung des originalen Timestamps zu verhindern.

Beispiele für Statements:

set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-01-06 00:00:00" group by DEVICE having count(*) > 800
set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= "2017-05-06 00:00:00" group by DEVICE
set <name> sqlCmd select DEVICE, count(*) from history where TIMESTAMP >= §timestamp_begin§ group by DEVICE
set <name> sqlCmd select * from history where DEVICE like "Te%t" order by `TIMESTAMP` desc
set <name> sqlCmd select * from history where `TIMESTAMP` > "2017-05-09 18:03:00" order by `TIMESTAMP` desc
set <name> sqlCmd select * from current order by `TIMESTAMP` desc
set <name> sqlCmd select sum(VALUE) as 'Einspeisung am 04.05.2017', count(*) as 'Anzahl' FROM history where `READING` = "Einspeisung_WirkP_Zaehler_Diff" and TIMESTAMP between '2017-05-04' AND '2017-05-05'
set <name> sqlCmd delete from current
set <name> sqlCmd delete from history where TIMESTAMP < "2016-05-06 00:00:00"
set <name> sqlCmd update history set TIMESTAMP=TIMESTAMP,VALUE='Val' WHERE VALUE='TestValue'
set <name> sqlCmd select * from history where DEVICE = "Test"
set <name> sqlCmd insert into history (TIMESTAMP, DEVICE, TYPE, EVENT, READING, VALUE, UNIT) VALUES ('2017-05-09 17:00:14','Test','manuell','manuell','Tes§e','TestValue','°C')

set <name> sqlCmd SET @open:=NULL, @closed:=NULL; SELECT TIMESTAMP, VALUE,DEVICE, @open AS open, @open := IF(VALUE = 'open', TIMESTAMP, NULL) AS curr_open, @closed := IF(VALUE = 'closed', TIMESTAMP, NULL) AS closed FROM history WHERE DATE(TIMESTAMP) = CURDATE() AND DEVICE = "HT_Fensterkontakt" AND READING = "state" AND (VALUE = "open" OR VALUE = "closed") ORDER BY TIMESTAMP;
set <name> sqlCmd PRAGMA temp_store=MEMORY; PRAGMA synchronous=FULL; PRAGMA journal_mode=WAL; PRAGMA cache_size=4000; select count(*) from history;
set <name> sqlCmd PRAGMA temp_store=FILE; PRAGMA temp_store_directory = '/opt/fhem/'; VACUUM;

Reading

executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor der Operation ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach der Operation ausführen
allowDeletion	: aktiviert Löschmöglichkeit
sqlResultFormat	: legt die Darstellung des Kommandoergebnis fest
sqlResultFieldSep	: Auswahl Feldtrenner im Ergebnis
sqlCmdHistoryLength	: Aktivierung Kommando-Historie und deren Umfang
sqlCmdVars	: setzt SQL Session Variablen oder PRAGMA vor jeder Ausführung des SQL-Statements

Hinweis:

sqlCmdHistory - Wenn mit dem Attribut "sqlCmdHistoryLength" aktiviert, kann aus einer Liste ein bereits erfolgreich ausgeführtes sqlCmd-Kommando wiederholt werden.
Mit Ausführung des letzten Eintrags der Liste, "__purge_historylist__", kann die Liste gelöscht werden.
Falls das Statement "," enthält, wird dieses Zeichen aus technischen Gründen in der History-Liste als "<c>" dargestellt.

Zur besseren Übersicht sind die zur Steuerung dieser Funktion von relevanten Attribute hier noch einmal zusammenstellt:

executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor der Operation ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach der Operation ausführen
allowDeletion	: aktiviert Löschmöglichkeit
sqlResultFormat	: legt die Darstellung des Kommandoergebnis fest
sqlResultFieldSep	: Auswahl Feldtrenner im Ergebnis

sqlSpecial - Die Funktion bietet eine Drop-Downliste mit einer Auswahl vorbereiter Auswertungen an.
Das Ergebnis des Statements wird im Reading "SqlResult" dargestellt. Die Ergebnis-Formatierung kann durch das Attribut "sqlResultFormat" ausgewählt, sowie der verwendete Feldtrenner durch das Attribut "sqlResultFieldSep" festgelegt werden.

Die für diese Funktion relevanten Attribute sind:

executeBeforeProc	: FHEM Kommando (oder perl-Routine) vor der Operation ausführen
executeAfterProc	: FHEM Kommando (oder perl-Routine) nach der Operation ausführen
sqlResultFormat	: Optionen der Ergebnisformatierung
sqlResultFieldSep	: Auswahl des Trennzeichens zwischen Ergebnisfeldern

Es sind die folgenden vordefinierte Auswertungen auswählbar:

50mostFreqLogsLast2days	: ermittelt die 50 am häufigsten vorkommenden Loggingeinträge der letzten 2 Tage
allDevCount	: alle in der Datenbank vorkommenden Devices und deren Anzahl
allDevReadCount	: alle in der Datenbank vorkommenden Device/Reading-Kombinationen und deren Anzahl

sumValue [display | writeToDB] - Berechnet die Summenwerte des Datenbankfelds "VALUE" in den Zeitgrenzen (Attribute) "timestamp_begin", "timestamp_end" bzw. "timeDiffToNow / timeOlderThan". Es muss das auszuwertende Reading im Attribut "reading" angegeben sein. Diese Funktion ist sinnvoll wenn fortlaufend Wertedifferenzen eines Readings in die Datenbank geschrieben werden.
Ist keine oder die Option "display" angegeben, werden die Ergebnisse nur angezeigt. Mit der Option "writeToDB" werden die Berechnungsergebnisse mit einem neuen Readingnamen in der Datenbank gespeichert.
Der neue Readingname wird aus einem Präfix und dem originalen Readingnamen gebildet, wobei der originale Readingname durch das Attribut "readingNameMap" ersetzt werden kann. Der Präfix setzt sich aus der Bildungsfunktion und der Aggregation zusammen.
Der Timestamp der neuen Readings in der Datenbank wird von der eingestellten Aggregationsperiode abgeleitet, sofern kein eindeutiger Zeitpunkt des Ergebnisses bestimmt werden kann. Das Feld "EVENT" wird mit "calculated" gefüllt.

Beispiel neuer Readingname gebildet aus dem Originalreading "totalpac":

Zusammengefasst sind die zur Steuerung dieser Funktion relevanten Attribute:

aggregation	: Auswahl einer Aggregationsperiode
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
executeBeforeProc	: ausführen FHEM Kommando (oder perl-Routine) vor Start Operation
executeAfterProc	: ausführen FHEM Kommando (oder perl-Routine) nach Ende Operation
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
readingNameMap	: die entstehenden Ergebnisreadings werden partiell umbenannt
time.*	: eine Reihe von Attributen zur Zeitabgrenzung
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

syncStandby <DbLog-Device Standby> - Es werden die Datensätze aus der angeschlossenen Datenbank (Quelle) direkt in eine weitere Datenbank (Standby-Datenbank) übertragen. Dabei ist "<DbLog-Device Standby>" das DbLog-Device, welches mit der Standby-Datenbank verbunden ist.

Es werden alle Datensätze übertragen, die durch Timestamp-Attribute bzw. die Attribute "device", "reading" bestimmt sind.
Die Datensätze werden dabei in Zeitscheiben entsprechend der eingestellten Aggregation übertragen. Hat das Attribut "aggregation" den Wert "no" oder "month", werden die Datensätze automatisch in Tageszeitscheiben zur Standby-Datenbank übertragen. Quell- und Standby-Datenbank können unterschiedlichen Typs sein.

Die zur Steuerung der syncStandby Funktion relevanten Attribute sind:

aggregation	: Einstellung der Zeitscheiben zur Übertragung (hour,day,week)
device	: einschließen oder ausschließen von Datensätzen die <device> enthalten
reading	: einschließen oder ausschließen von Datensätzen die <reading> enthalten
time.*	: Attribute zur Zeitabgrenzung der zu übertragenden Datensätze.
valueFilter	: ein zusätzliches REGEXP um die Datenselektion zu steuern. Der REGEXP wird auf das Datenbankfeld 'VALUE' angewendet.

tableCurrentFillup - Die current-Tabelle wird mit einem Extrakt der history-Tabelle aufgefüllt. Die Attribute zur Zeiteinschränkung bzw. device, reading werden ausgewertet. Dadurch kann der Inhalt des Extrakts beeinflusst werden. Im zugehörigen DbLog-Device sollte sollte das Attribut "DbLogType=SampleFill/History" gesetzt sein.

tableCurrentPurge - löscht den Inhalt der current-Tabelle. Es werden keine Limitierungen, z.B. durch die Attribute "timestamp_begin", "timestamp_end", device, reading, usw. , ausgewertet.

vacuum - optimiert die Tabellen in der angeschlossenen Datenbank (SQLite, PostgreSQL).
Vor und nach der Optimierung kann ein FHEM-Kommando ausgeführt werden. (siehe Attribute "executeBeforeProc", "executeAfterProc")

Für alle Auswertungsvarianten (Ausnahme sqlCmd,deviceRename,readingRename) gilt:

Hinweis:

Get