[timescaledb] Add metadata tag support and JSONB config storage (fixes openhab#20460) (openhab#20464)

* feat: Enhance TimescaleDB schema with value and metadata columns

Signed-off-by: René Ulbricht <rene_ulbricht@outlook.com>

Author: ulbi

bundles/org.openhab.persistence.timescaledb/AGENTS.md

@@ -49,6 +49,8 @@ CREATE TABLE item_meta (
     id         SERIAL PRIMARY KEY,
     name       TEXT NOT NULL UNIQUE,
     label      TEXT,
+    value      TEXT,
+    metadata   JSONB,
     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
@@ -65,6 +67,36 @@ SELECT create_hypertable('items', 'time');
 CREATE INDEX ON items (item_id, time DESC);
 ```
 
+### `item_meta.value` and `item_meta.metadata`
+
+`value TEXT` stores `metadata.getValue()` — a free user-defined string (measurement label, filter tag, etc.).
+`metadata JSONB` stores the **complete** `metadata.getConfiguration()` map serialized as JSON — unfiltered,
+including reserved keys (`aggregation`, `downsampleInterval`, `retainRawDays`, `retentionDays`) and any
+user-defined tags (`location`, `kind`, etc.).
+
+```
+Number:Temperature MySensor {
+    timescaledb="sensor.temperature" [ aggregation="AVG", downsampleInterval="1h",
+        location="living_room", kind="sensor" ]
+}
+-- item_meta.value    = 'sensor.temperature'
+-- item_meta.metadata = '{"aggregation":"AVG","downsampleInterval":"1h","location":"living_room","kind":"sensor"}'
+```
+
+Grafana can filter via JSONB operators: `WHERE metadata->>'location' = 'living_room'`
+
+When no value/config is set, both columns are `NULL`.
+
+**Migration:** On startup `TimescaleDBSchema.initialize()` runs a single DO-block that adds both columns atomically:
+
+```sql
+ALTER TABLE item_meta
+    ADD COLUMN IF NOT EXISTS value    TEXT,
+    ADD COLUMN IF NOT EXISTS metadata JSONB;
+```
+
+`IF NOT EXISTS` makes the statement idempotent. A `lock_timeout` of 5 s prevents blocking `@Activate` indefinitely; on timeout a WARNING is logged and the migration is retried on the next startup.
+
 ### Why `unit` is per row, not in `item_meta`
 
 A `QuantityType` unit can change over time (sensor reconfiguration, firmware update, etc.). Storing it in `item_meta` would corrupt historical reads. The unit is stored with each measurement and read back from the row when reconstructing `QuantityType` states.
@@ -134,17 +166,22 @@ private Optional<Metadata> getItemMetadata(String itemName) {
 ```
 
 `Metadata` has:
-- `getValue()` → main value string, e.g. `"AVG"`, `"MAX"`, `"MIN"`, `"SUM"`, or `""` (no aggregation)
-- `getConfiguration()` → `Map<String, Object>` with keys like `"downsampleInterval"`, `"retainRawDays"`, `"retentionDays"`
+- `getValue()` → user-defined string (e.g. `"sensor.temperature"`), stored in `item_meta.value`
+- `getConfiguration()` → `Map<String, Object>` with keys like `"aggregation"`, `"downsampleInterval"`, `"retainRawDays"`, `"retentionDays"`, plus user-defined tags
 
 ### Metadata format (configured by users in .items files)
 
 ```java
 Number:Temperature MySensor {
-    timescaledb="AVG" [ downsampleInterval="1h", retainRawDays="5", retentionDays="365" ]
+    timescaledb="sensor.temperature" [ aggregation="AVG", downsampleInterval="1h",
+        retainRawDays="5", retentionDays="365", location="living_room" ]
 }
 ```
 
+- `getValue()` = user-defined string stored in `item_meta.value` (e.g. measurement label for Grafana)
+- `aggregation` in config = downsampling function (replaces the old `getValue()` = `"AVG"` pattern)
+- All config keys are stored unfiltered as JSONB in `item_meta.metadata`
+
 ### Parsing the metadata
 
 ```java
@@ -249,7 +286,7 @@ Location: `src/test/java/org/openhab/persistence/timescaledb/internal/`
 - `TimescaleDBMetadataServiceTest` — parsing of metadata values and config keys
 - `TimescaleDBDownsampleJobTest` — SQL generation for aggregation/delete, interval allowlist validation
 
-Run with `mvn test` — last result: **183 tests, 0 failures** (2026-03-13).
+Run with `mvn test` — last result: **228 tests, 0 failures** (2026-03-28).
 
 ### Integration Tests (requires Docker + TimescaleDB)
 

bundles/org.openhab.persistence.timescaledb/README.md

@@ -27,7 +27,7 @@ CREATE EXTENSION IF NOT EXISTS timescaledb;
 ## Database Schema
 
 The service **creates all tables automatically on startup** — no manual DDL required.
-Item states are stored in a single hypertable `items` (columns: `time`, `item_id`, `value`, `string`, `unit`, `downsampled`) and a name-lookup table `item_meta`.
+Item states are stored in a single hypertable `items` (columns: `time`, `item_id`, `value`, `string`, `unit`, `downsampled`) and a name-lookup table `item_meta` (columns: `id`, `name`, `label`, `value`, `metadata`).
 
 ## State Type Mapping
 
@@ -77,36 +77,44 @@ Items {
 }
 ```
 
-## Per-Item Downsampling
+## Per-Item Downsampling and Metadata Tags
 
-Downsampling is configured **per item** via item metadata in the `timescaledb` namespace.
+Per-item behaviour is configured via item metadata in the `timescaledb` namespace.
 
 ### Metadata format
 
 ```text
-timescaledb="<operation>" [downsampleInterval="<interval>", retainRawDays="<n>", retentionDays="<n>"]
+timescaledb="<label>" [ aggregation="<fn>", downsampleInterval="<interval>",
+    retainRawDays="<n>", retentionDays="<n>", <custom-tag>="<value>", ... ]
 ```
 
-| Metadata key         | Values                               | Description                                                                                                                                       |
-|----------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
-| value (main)         | `AVG`, `MAX`, `MIN`, `SUM`, or `" "` | Aggregation function. Use a single space `" "` for retention-only (no downsampling). openHAB rejects a truly empty value, so a space is required. |
-| `downsampleInterval` | e.g. `1h`, `15m`, `1d`               | Time bucket size for aggregation. Required when value is an aggregation function.                                                                 |
-| `retainRawDays`      | integer, default `5`                 | Keep raw data for N days before replacing with aggregated rows.                                                                                   |
-| `retentionDays`      | integer, default `0`                 | Drop all data (raw + downsampled) older than N days. `0` = off.                                                                                   |
+| Metadata key         | Values / default             | Description                                                                                                   |
+|----------------------|------------------------------|---------------------------------------------------------------------------------------------------------------|
+| value (main)         | any string                   | User-defined label stored in `item_meta.value`. Leave blank (single space `" "`) if only retention is needed. |
+| `aggregation`        | `AVG`, `MAX`, `MIN`, `SUM`   | Downsampling aggregation function. Omit if no downsampling is needed.                                         |
+| `downsampleInterval` | e.g. `1h`, `15m`, `1d`       | Time bucket size for aggregation. Required when `aggregation` is set.                                         |
+| `retainRawDays`      | integer, default `5`         | Keep raw data for N days before replacing with aggregated rows.                                               |
+| `retentionDays`      | integer, default `0`         | Drop all data older than N days. `0` = disabled.                                                              |
+| custom tags          | any key=value pairs          | Stored unfiltered as JSONB in `item_meta.metadata`. Queryable via Grafana/SQL JSONB operators.                |
+
+The **entire config map** (all keys including `aggregation`, `downsampleInterval`, etc.) is stored as JSONB in `item_meta.metadata`, enabling flexible SQL/Grafana filtering.
 
 ### Configuration in `.items` files
 
 ```java
+// Downsampling + custom tags for Grafana filtering
 Number:Temperature Sensor_Temperature_Living "Living Room [%.1f °C]" {
-    timescaledb="AVG" [ downsampleInterval="1h", retainRawDays="5" ]
+    timescaledb="sensor.temperature" [ aggregation="AVG", downsampleInterval="1h",
+        retainRawDays="5", location="living_room", kind="temperature" ]
 }
 
 Number:Power Meter_Power_House "House Power [%.1f W]" {
-    timescaledb="AVG" [ downsampleInterval="15m", retainRawDays="3", retentionDays="365" ]
+    timescaledb="meter.power" [ aggregation="AVG", downsampleInterval="15m",
+        retainRawDays="3", retentionDays="365" ]
 }
 
 Number:Energy Meter_Energy_House "House Energy [%.3f kWh]" {
-    timescaledb="SUM" [ downsampleInterval="1h", retainRawDays="7" ]
+    timescaledb="meter.energy" [ aggregation="SUM", downsampleInterval="1h", retainRawDays="7" ]
 }
 
 // Retention-only: no downsampling, just drop data older than 30 days.
@@ -118,12 +126,12 @@ Number:Temperature Sensor_Temp_Outdoor {
 
 ### Configuration in mainUI
 
-**Downsampling + Retention:**
+**Downsampling + Retention + Tags:**
 
 `Item → Metadata → Add Metadata → Enter namespace "timescaledb"`:
 
-- Value: `AVG`
-- Additional config: `downsampleInterval=1h`, `retainRawDays=5`, `retentionDays=365`
+- Value: `sensor.temperature` (or any descriptive label)
+- Additional config: `aggregation=AVG`, `downsampleInterval=1h`, `retainRawDays=5`, `retentionDays=365`, `location=living_room`
 
 **Retention-only (no downsampling):**
 
@@ -204,7 +212,9 @@ This works independently of downsampling: an item can have `retentionDays` set w
 
 ## Grafana Integration
 
-TimescaleDB works natively with the Grafana PostgreSQL data source:
+TimescaleDB works natively with the Grafana PostgreSQL data source.
+
+### Query by item name
 
 ```sql
 -- Raw + downsampled data for a sensor (last 24 h)
@@ -220,6 +230,39 @@ GROUP BY 1
 ORDER BY 1;
 ```
 
+### Filter by label (`item_meta.value`)
+
+```sql
+-- All items labelled "sensor.temperature" (last 24 h)
+SELECT
+  time_bucket('5 minutes', time) AS time,
+  item_meta.name                 AS sensor,
+  AVG(value)                     AS temperature
+FROM items
+JOIN item_meta ON items.item_id = item_meta.id
+WHERE item_meta.value = 'sensor.temperature'
+  AND time > NOW() - INTERVAL '24 hours'
+GROUP BY 1, 2
+ORDER BY 1;
+```
+
+### Filter by custom tag (`item_meta.metadata` JSONB)
+
+```sql
+-- All temperature sensors in the living room
+SELECT
+  time_bucket('5 minutes', time) AS time,
+  item_meta.name                 AS sensor,
+  AVG(value)                     AS temperature
+FROM items
+JOIN item_meta ON items.item_id = item_meta.id
+WHERE item_meta.metadata->>'location' = 'living_room'
+  AND item_meta.metadata->>'kind'     = 'temperature'
+  AND time > NOW() - INTERVAL '24 hours'
+GROUP BY 1, 2
+ORDER BY 1;
+```
+
 ## Differences from JDBC Persistence
 
 | Feature                        | JDBC Persistence     | TimescaleDB Persistence |

bundles/org.openhab.persistence.timescaledb/pom.xml

@@ -15,7 +15,7 @@
   <name>openHAB Add-ons :: Bundles :: Persistence Service :: TimescaleDB</name>
 
   <properties>
-    <bnd.importpackage>!com.codahale.metrics.*,!io.prometheus.*,!org.checkerframework.*,!org.jetbrains.annotations.*,!org.hibernate.*,!waffle.windows.auth.*,!org.osgi.service.jdbc.*,!com.sun.jna.*,!javassist.*</bnd.importpackage>
+    <bnd.importpackage>!com.codahale.metrics.*,!io.prometheus.*,!org.checkerframework.*,!org.jetbrains.annotations.*,!org.hibernate.*,!waffle.windows.auth.*,!org.osgi.service.jdbc.*,!com.sun.jna.*,!javassist.*,!com.google.errorprone.annotations.*,!sun.misc.*</bnd.importpackage>
     <postgresql.version>42.7.9</postgresql.version>
     <hikari.version>5.1.0</hikari.version>
   </properties>
@@ -34,6 +34,13 @@
       <scope>compile</scope>
     </dependency>
 
+    <dependency>
+      <groupId>com.google.code.gson</groupId>
+      <artifactId>gson</artifactId>
+      <version>${gson.version}</version>
+      <scope>compile</scope>
+    </dependency>
+
     <!-- Test dependencies -->
     <dependency>
       <groupId>org.testcontainers</groupId>

bundles/org.openhab.persistence.timescaledb/src/main/java/org/openhab/persistence/timescaledb/internal/TimescaleDBMetadataService.java

@@ -14,6 +14,7 @@
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Map;
 import java.util.Optional;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
@@ -27,26 +28,36 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import com.google.gson.Gson;
+
 /**
- * Reads and parses per-item downsampling configuration from the {@link MetadataRegistry}
- * using the {@code timescaledb} namespace.
+ * Reads per-item configuration from the {@link MetadataRegistry} using the {@code timescaledb} namespace.
  *
  * <p>
  * Example item metadata:
- * 
+ *
  * <pre>
  * Number:Temperature MySensor {
- *     timescaledb="AVG" [ downsampleInterval="1h", retainRawDays="5", retentionDays="365" ]
+ *     timescaledb="sensor.temperature" [ aggregation="AVG", downsampleInterval="1h", retainRawDays="5",
+ *         retentionDays="365", kind="sensor", location="living_room" ]
  * }
  * </pre>
  *
+ * <ul>
+ * <li>{@code getValue()} — user-defined string (measurement label / filter tag), stored in
+ * {@code item_meta.value}</li>
+ * <li>{@code getConfiguration()} — full config map stored as JSONB in {@code item_meta.metadata}; reserved keys:
+ * {@code aggregation}, {@code downsampleInterval}, {@code retainRawDays}, {@code retentionDays}</li>
+ * </ul>
+ *
  * @author René Ulbricht - Initial contribution
  */
 @NonNullByDefault
 @Component(service = TimescaleDBMetadataService.class)
 public class TimescaleDBMetadataService {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(TimescaleDBMetadataService.class);
+    private static final Gson GSON = new Gson();
 
     /** The metadata namespace used by this persistence service. */
     public static final String METADATA_NAMESPACE = "timescaledb";
@@ -95,13 +106,61 @@ public List<String> getConfiguredItemNames() {
         return result;
     }
 
+    /**
+     * Returns the user-defined value string from {@code metadata.getValue()}, stored verbatim in
+     * {@code item_meta.value}. Returns {@code null} if no metadata is configured or the value is blank.
+     *
+     * <p>
+     * Example: {@code timescaledb="sensor.temperature" [...]} → returns {@code "sensor.temperature"}.
+     *
+     * @param itemName The item name.
+     * @return The value string, or {@code null}.
+     */
+    public @Nullable String getMetadataValueString(String itemName) {
+        MetadataKey key = new MetadataKey(METADATA_NAMESPACE, itemName);
+        @Nullable
+        Metadata metadata = metadataRegistry.get(key);
+        if (metadata == null) {
+            return null;
+        }
+        String v = metadata.getValue();
+        return v.isBlank() ? null : v;
+    }
+
+    /**
+     * Returns the full {@code getConfiguration()} map serialized as a JSON string, suitable for storage
+     * in {@code item_meta.metadata} (JSONB column). Returns {@code null} if no metadata is configured
+     * or the config map is empty.
+     *
+     * <p>
+     * All config keys are stored unfiltered, including reserved keys ({@code aggregation},
+     * {@code downsampleInterval}, {@code retainRawDays}, {@code retentionDays}) and any user-defined tags.
+     *
+     * @param itemName The item name.
+     * @return JSON string of the config map, or {@code null}.
+     */
+    public @Nullable String getMetadataConfigJson(String itemName) {
+        MetadataKey key = new MetadataKey(METADATA_NAMESPACE, itemName);
+        @Nullable
+        Metadata metadata = metadataRegistry.get(key);
+        if (metadata == null) {
+            return null;
+        }
+        Map<String, Object> config = metadata.getConfiguration();
+        if (config.isEmpty()) {
+            return null;
+        }
+        return GSON.toJson(config);
+    }
+
     private Optional<DownsampleConfig> parseConfig(String itemName, Metadata metadata) {
-        String functionStr = metadata.getValue();
+        var config = metadata.getConfiguration();
+        Object aggObj = config.get("aggregation");
+        String functionStr = aggObj != null ? aggObj.toString().trim() : "";
+
         if (functionStr.isBlank()) {
-            // No aggregation function — check for retention-only config.
-            // Note: openHAB requires a non-empty metadata value, so use a single space (" ")
-            // in item files and the UI when you only want retention without downsampling.
-            int retentionDays = getInt(metadata.getConfiguration(), "retentionDays", DEFAULT_RETENTION_DAYS);
+            // No aggregation function — retention-only config (retentionDays without downsampling).
+            int retentionDays = getInt(config, "retentionDays", DEFAULT_RETENTION_DAYS);
             if (retentionDays < 0) {
                 LOGGER.warn("Item '{}': retentionDays must be >= 0, ignoring negative value {}", itemName,
                         retentionDays);
@@ -123,11 +182,9 @@ private Optional<DownsampleConfig> parseConfig(String itemName, Metadata metadat
             return Optional.empty();
         }
 
-        var config = metadata.getConfiguration();
-
         String intervalStr = getString(config, "downsampleInterval", null);
         if (intervalStr == null || intervalStr.isBlank()) {
-            LOGGER.warn("Item '{}': timescaledb metadata has function '{}' but no downsampleInterval — skipping",
+            LOGGER.warn("Item '{}': timescaledb metadata has aggregation '{}' but no downsampleInterval — skipping",
                     itemName, functionStr);
             return Optional.empty();
         }
@@ -156,13 +213,12 @@ private Optional<DownsampleConfig> parseConfig(String itemName, Metadata metadat
         return Optional.of(result);
     }
 
-    private static @Nullable String getString(java.util.Map<String, Object> config, String key,
-            @Nullable String defaultValue) {
+    private static @Nullable String getString(Map<String, Object> config, String key, @Nullable String defaultValue) {
         Object val = config.get(key);
         return val != null ? val.toString() : defaultValue;
     }
 
-    private static int getInt(java.util.Map<String, Object> config, String key, int defaultValue) {
+    private static int getInt(Map<String, Object> config, String key, int defaultValue) {
         Object val = config.get(key);
         if (val == null) {
             return defaultValue;