From 2c65d5b9d61bb99fe961553ad6533844cb48abfa Mon Sep 17 00:00:00 2001 From: Mark Herwege Date: Tue, 27 Aug 2024 15:19:14 +0200 Subject: [PATCH] median documentation Signed-off-by: Mark Herwege --- configuration/items.md | 14 ++--- configuration/persistence.md | 115 ++++++++++++++++++----------------- 2 files changed, 66 insertions(+), 63 deletions(-) diff --git a/configuration/items.md b/configuration/items.md index 9cafcc120b..ebe6e341ce 100644 --- a/configuration/items.md +++ b/configuration/items.md @@ -501,13 +501,13 @@ Group[:itemtype[:function]] groupname ["labeltext"] [] [(group1, group Group state aggregation functions can be any of the following: -| | Function | Parameters | Base Item | Description | | -| --- | -------------------------- | ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -| | `EQUALITY` | - | \ | Default if no function is specified. Sets the state of the members if all have equal state. Otherwise `UNDEF` is set. In the Item DSL `EQUALITY` is the default and may be omitted. | | -| | `AND`, `OR`, `NAND`, `NOR` | , | \ (must match active & passive state) | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) operation. Sets the \, if the members state \ evaluates to `true` under the boolean term. Otherwise the \ is set. | | -| | `SUM`, `AVG`, `MIN`, `MAX` | - | Number | [Arithmetic](https://en.wikipedia.org/wiki/Arithmetic) operation. Sets the state according to the arithmetic function over all members states. | | -| | `COUNT` | | Number | Sets the state to the number of members matching the given regular expression with their states. | | -| | `LATEST`, `EARLIEST` | - | DateTime | Sets the state to the latest/earliest date from all members states | | +| | Function | Parameters | Base Item | Description | | +| --- | ------------------------------------ | ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| | `EQUALITY` | - | \ | Default if no function is specified. Sets the state of the members if all have equal state. Otherwise `UNDEF` is set. In the Item DSL `EQUALITY` is the default and may be omitted. | | +| | `AND`, `OR`, `NAND`, `NOR` | , | \ (must match active & passive state) | [Boolean](https://en.wikipedia.org/wiki/Boolean_algebra) operation. Sets the \, if the members state \ evaluates to `true` under the boolean term. Otherwise the \ is set. | | +| | `SUM`, `AVG`, `MEDIAN`, `MIN`, `MAX` | - | Number | [Arithmetic](https://en.wikipedia.org/wiki/Arithmetic) operation. Sets the state according to the arithmetic function over all members states. | | +| | `COUNT` | | Number | Sets the state to the number of members matching the given regular expression with their states. | | +| | `LATEST`, `EARLIEST` | - | DateTime | Sets the state to the latest/earliest date from all members states | | Boolean group state functions additionally return a number representing the count of member Items of value 'value1' (see example below). diff --git a/configuration/persistence.md b/configuration/persistence.md index 45255b38d1..b26a8f4669 100644 --- a/configuration/persistence.md +++ b/configuration/persistence.md @@ -239,62 +239,65 @@ You can easily imagine that you can implement very powerful rules using this fea Here is the full list of available persistence extensions: -| Persistence Extension | Description | -|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `.persist()` | Persists the current State of the Item | -| `.persist(ZonedDateTime, State)` | Persists a past or future state for the Item | -| `.persist(TimeSeries)` | Persists a TimeSeries with one or multiple values to the Item | -| `.persistedState(ZonedDateTime)` | Retrieves the State of an Item at a certain point in time (returns HistoricItem) | -| `.lastUpdate()` | Returns the timestamp of the last Item update, null if current Item state different from last persisted state | -| `.nextUpdate()` | Returns the timestamp of the next Item update if future states have been persisted | -| `.lastChange()` | Returns the timestamp of the last Item change, null if current Item state different from last persisted state | -| `.nextChange()` | Returns the timestamp of the next Item change if future states have been persisted | -| `.previousState()` | Gets the previous State of a persisted Item (returns HistoricItem) | -| `.previousState(true)` | Gets the previous State of a persisted Item, skips Items with equal State values and searches the first Item with State not equal the current State (returns HistoricItem) | -| `.nextState()` | Gets the next State of a persisted Item if future states have been persisted (returns HistoricItem) | -| `.nextState(true)` | Gets the next State of a persisted Item, skips Items with equal State values and searches the first Item with State not equal the current State (returns HistoricItem) | -| `.changedSince(ZonedDateTime)` | Checks if the State of the Item has (ever) changed since a certain point in time | -| `.changedUntil(ZonedDateTime)` | Checks if the State of the Item will change by a certain future point in time | -| `.changedBetween(ZonedDateTime, ZonedDateTime)` | Checks if the State of the Item has (ever) changed between certain points in time | -| `.updatedSince(ZonedDateTime)` | Checks if the state of the Item has been updated since a certain point in time | -| `.updatedUntil(ZonedDateTime)` | Checks if the state of the Item will be updated by a certain future point in time | -| `.updatedBetween(ZonedDateTime, ZonedDateTime)` | Checks if the state of the Item has been updated between certain points in time | -| `.maximumSince(ZonedDateTime)` | Gets the maximum value of the State of a persisted Item since a certain point in time (returns HistoricItem) | -| `.maximumUntil(ZonedDateTime)` | Gets the maximum value of the State of a persisted Item until a certain future point in time (returns HistoricItem) | -| `.maximumBetween(ZonedDateTime, ZonedDateTime)` | Gets the maximum value of the State of a persisted Item between certain points in time (returns HistoricItem) | -| `.minimumSince(ZonedDateTime)` | Gets the minimum value of the State of a persisted Item since a certain point in time (returns HistoricItem) | -| `.minimumUntil(ZonedDateTime)` | Gets the minimum value of the State of a persisted Item until a certain future point in time (returns HistoricItem) | -| `.minimumBetween(ZonedDateTime, ZonedDateTime)` | Gets the minimum value of the State of a persisted Item between certain points in time (returns HistoricItem) | -| `.averageSince(ZonedDateTime)` | Gets the average value of the State of a persisted Item since a certain point in time. This method uses a time-weighted average calculation (see example below) (returns State) | -| `.averageUntil(ZonedDateTime)` | Gets the average value of the State of a persisted Item until a certain point in time. This method uses a time-weighted average calculation (see example below) (returns State) | -| `.averageBetween(ZonedDateTime, ZonedDateTime)` | Gets the average value of the State of a persisted Item betwen certain points in time. This method uses a time-weighted average calculation (see example below) (returns State) | -| `.deltaSince(ZonedDateTime)` | Gets the difference in value of the State of a given Item since a certain point in time (returns State) | -| `.deltaUntil(ZonedDateTime)` | Gets the difference in value of the future State of a given Item with the current State (returns State) | -| `.deltaBetween(ZonedDateTime, ZonedDateTime)` | Gets the difference in value of the State of a given Item between certain points in time (returns State) | -| `.evolutionRateSince(ZonedDateTime)` | Gets the evolution rate of the state of a given Item since a certain point in time (returns DecimalType) | -| `.evolutionRateUntil(ZonedDateTime)` | Gets the evolution rate of the state of a given Item until a certain point in time (returns DecimalType) | -| `.evolutionRateBetween(ZonedDateTime, ZonedDateTime)` | Gets the evolution rate of the state of a given Item between certain points in time (returns DecimalType) | -| `.deviationSince(ZonedDateTime)` | Gets the standard deviation of the state of the given Item since a certain point in time (returns State) | -| `.deviationUntil(ZonedDateTime)` | Gets the standard deviation of the state of the given Item until a certain point in time (returns State) | -| `.deviationBetween(ZonedDateTime, ZonedDateTime)` | Gets the standard deviation of the state of the given Item between certain points in time (returns State) | -| `.varianceSince(ZonedDateTime)` | Gets the variance of the state of the given Item since a certain point in time (returns State) | -| `.varianceUntil(ZonedDateTime)` | Gets the variance of the state of the given Item until a certain future point in time (returns State) | -| `.varianceBetween(ZonedDateTime, ZonedDateTime)` | Gets the variance of the state of the given Item between certain points in time (returns State) | -| `.sumSince(ZonedDateTime)` | Gets the sum of the previous States of a persisted Item since a certain point in time (returns State) | -| `.sumUntil(ZonedDateTime)` | Gets the sum of the future States of a persisted Item until a certain point in time (returns State) | -| `.sumBetween(ZonedDateTime, ZonedDateTime)` | Gets the sum of the previous States of a persisted Item between certain points in time (returns State) | -| `.countSince(ZonedDateTime)` | Gets the number of persisted States of an Item since a certain point in time | -| `.countUntil(ZonedDateTime)` | Gets the number of persisted States of an Item until a certain point in time | -| `.countBetween(ZonedDateTime, ZonedDateTime)` | Gets the number of persisted States of an Item between certain points in time | -| `.countStateChangesSince(ZonedDateTime)` | Gets the number of changes in persisted States of an Item since a certain point in time | -| `.countStateChangesUntil(ZonedDateTime)` | Gets the number changes in of persisted States of an Item until a certain point in time | -| `.countStateChangesBetween(ZonedDateTime, ZonedDateTime)` | Gets the number of changes in persisted States of an Item between certain points in time | -| `.getAllStatesSince(ZonedDateTime)` | Gets all persisted State changes for an Item since a certain point in time (returns Iterable) | -| `.getAllStatesUntil(ZonedDateTime)` | Gets all persisted State changes for an Item until a certain point in time (returns Iterable) | -| `.getAllStatesBetween(ZonedDateTime, ZonedDateTime)` | Gets all persisted State changes for an Item between certain points in time (returns Iterable) | -| `.removeAllStatesSince(ZonedDateTime)` | Removes all persisted States since a certain point in time | -| `.removeAllStatesUntil(ZonedDateTime)` | Removes all future persisted States for an Item until a certain point in time | -| `.removeAllStatesBetween(ZonedDateTime, ZonedDateTime)` | Removes all persisted States for an Item between certain points in time | +| Persistence Extension | Description | +|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `.persist()` | Persists the current State of the Item | +| `.persist(ZonedDateTime, State)` | Persists a past or future state for the Item | +| `.persist(TimeSeries)` | Persists a TimeSeries with one or multiple values to the Item | +| `.persistedState(ZonedDateTime)` | Retrieves the State of an Item at a certain point in time (returns HistoricItem) | +| `.lastUpdate()` | Returns the timestamp of the last Item update, null if current Item state different from last persisted state | +| `.nextUpdate()` | Returns the timestamp of the next Item update if future states have been persisted | +| `.lastChange()` | Returns the timestamp of the last Item change, null if current Item state different from last persisted state | +| `.nextChange()` | Returns the timestamp of the next Item change if future states have been persisted | +| `.previousState()` | Gets the previous State of a persisted Item (returns HistoricItem) | +| `.previousState(true)` | Gets the previous State of a persisted Item, skips Items with equal State values and searches the first Item with State not equal the current State (returns HistoricItem) | +| `.nextState()` | Gets the next State of a persisted Item if future states have been persisted (returns HistoricItem) | +| `.nextState(true)` | Gets the next State of a persisted Item, skips Items with equal State values and searches the first Item with State not equal the current State (returns HistoricItem) | +| `.changedSince(ZonedDateTime)` | Checks if the State of the Item has (ever) changed since a certain point in time | +| `.changedUntil(ZonedDateTime)` | Checks if the State of the Item will change by a certain future point in time | +| `.changedBetween(ZonedDateTime, ZonedDateTime)` | Checks if the State of the Item has (ever) changed between certain points in time | +| `.updatedSince(ZonedDateTime)` | Checks if the state of the Item has been updated since a certain point in time | +| `.updatedUntil(ZonedDateTime)` | Checks if the state of the Item will be updated by a certain future point in time | +| `.updatedBetween(ZonedDateTime, ZonedDateTime)` | Checks if the state of the Item has been updated between certain points in time | +| `.maximumSince(ZonedDateTime)` | Gets the maximum value of the State of a persisted Item since a certain point in time (returns HistoricItem) | +| `.maximumUntil(ZonedDateTime)` | Gets the maximum value of the State of a persisted Item until a certain future point in time (returns HistoricItem) | +| `.maximumBetween(ZonedDateTime, ZonedDateTime)` | Gets the maximum value of the State of a persisted Item between certain points in time (returns HistoricItem) | +| `.minimumSince(ZonedDateTime)` | Gets the minimum value of the State of a persisted Item since a certain point in time (returns HistoricItem) | +| `.minimumUntil(ZonedDateTime)` | Gets the minimum value of the State of a persisted Item until a certain future point in time (returns HistoricItem) | +| `.minimumBetween(ZonedDateTime, ZonedDateTime)` | Gets the minimum value of the State of a persisted Item between certain points in time (returns HistoricItem) | +| `.averageSince(ZonedDateTime)` | Gets the average value of the State of a persisted Item since a certain point in time. This method uses a time-weighted average calculation (see example below) (returns State) | +| `.averageUntil(ZonedDateTime)` | Gets the average value of the State of a persisted Item until a certain point in time. This method uses a time-weighted average calculation (see example below) (returns State) | +| `.averageBetween(ZonedDateTime, ZonedDateTime)` | Gets the average value of the State of a persisted Item between certain points in time. This method uses a time-weighted average calculation (see example below) (returns State) | +| `.medianSince(ZonedDateTime)` | Gets the median value of the State of a persisted Item since a certain point in time (returns State) | +| `.medianUntil(ZonedDateTime)` | Gets the median value of the State of a persisted Item until a certain point in time (returns State) | +| `.medianBetween(ZonedDateTime, ZonedDateTime)` | Gets the median value of the State of a persisted Item between certain points in time (returns State) | +| `.deltaSince(ZonedDateTime)` | Gets the difference in value of the State of a given Item since a certain point in time (returns State) | +| `.deltaUntil(ZonedDateTime)` | Gets the difference in value of the future State of a given Item with the current State (returns State) | +| `.deltaBetween(ZonedDateTime, ZonedDateTime)` | Gets the difference in value of the State of a given Item between certain points in time (returns State) | +| `.evolutionRateSince(ZonedDateTime)` | Gets the evolution rate of the state of a given Item since a certain point in time (returns DecimalType) | +| `.evolutionRateUntil(ZonedDateTime)` | Gets the evolution rate of the state of a given Item until a certain point in time (returns DecimalType) | +| `.evolutionRateBetween(ZonedDateTime, ZonedDateTime)` | Gets the evolution rate of the state of a given Item between certain points in time (returns DecimalType) | +| `.deviationSince(ZonedDateTime)` | Gets the standard deviation of the state of the given Item since a certain point in time (returns State) | +| `.deviationUntil(ZonedDateTime)` | Gets the standard deviation of the state of the given Item until a certain point in time (returns State) | +| `.deviationBetween(ZonedDateTime, ZonedDateTime)` | Gets the standard deviation of the state of the given Item between certain points in time (returns State) | +| `.varianceSince(ZonedDateTime)` | Gets the variance of the state of the given Item since a certain point in time (returns State) | +| `.varianceUntil(ZonedDateTime)` | Gets the variance of the state of the given Item until a certain future point in time (returns State) | +| `.varianceBetween(ZonedDateTime, ZonedDateTime)` | Gets the variance of the state of the given Item between certain points in time (returns State) | +| `.sumSince(ZonedDateTime)` | Gets the sum of the previous States of a persisted Item since a certain point in time (returns State) | +| `.sumUntil(ZonedDateTime)` | Gets the sum of the future States of a persisted Item until a certain point in time (returns State) | +| `.sumBetween(ZonedDateTime, ZonedDateTime)` | Gets the sum of the previous States of a persisted Item between certain points in time (returns State) | +| `.countSince(ZonedDateTime)` | Gets the number of persisted States of an Item since a certain point in time | +| `.countUntil(ZonedDateTime)` | Gets the number of persisted States of an Item until a certain point in time | +| `.countBetween(ZonedDateTime, ZonedDateTime)` | Gets the number of persisted States of an Item between certain points in time | +| `.countStateChangesSince(ZonedDateTime)` | Gets the number of changes in persisted States of an Item since a certain point in time | +| `.countStateChangesUntil(ZonedDateTime)` | Gets the number changes in of persisted States of an Item until a certain point in time | +| `.countStateChangesBetween(ZonedDateTime, ZonedDateTime)` | Gets the number of changes in persisted States of an Item between certain points in time | +| `.getAllStatesSince(ZonedDateTime)` | Gets all persisted State changes for an Item since a certain point in time (returns Iterable) | +| `.getAllStatesUntil(ZonedDateTime)` | Gets all persisted State changes for an Item until a certain point in time (returns Iterable) | +| `.getAllStatesBetween(ZonedDateTime, ZonedDateTime)` | Gets all persisted State changes for an Item between certain points in time (returns Iterable) | +| `.removeAllStatesSince(ZonedDateTime)` | Removes all persisted States since a certain point in time | +| `.removeAllStatesUntil(ZonedDateTime)` | Removes all future persisted States for an Item until a certain point in time | +| `.removeAllStatesBetween(ZonedDateTime, ZonedDateTime)` | Removes all persisted States for an Item between certain points in time | These extensions use the [default persistence service](#default-persistence-service). You may specify a different persistence service by appending a String as an optional additional parameter at the end of the extension.