npm - signalk-questdb - Versions diffs - 2.5.0 → 2.5.2 - Mend

signalk-questdb 2.5.0 → 2.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/.release-please-manifest.json +1 -1
package/README.md +157 -1186
package/dist/api-contract.d.ts +1 -1
package/dist/config/schema.js +1 -1
package/dist/config/schema.js.map +1 -1
package/dist/index.js +8 -45
package/dist/index.js.map +1 -1
package/dist/migration-checkpoint.d.ts +4 -4
package/dist/migration-checkpoint.js +4 -4
package/dist/restore.d.ts +10 -6
package/dist/restore.js +22 -8
package/dist/restore.js.map +1 -1
package/doc/configuration.md +98 -0
package/doc/deployment.md +249 -0
package/doc/history-api.md +178 -0
package/doc/import-export.md +179 -0
package/doc/recording.md +187 -0
package/doc/troubleshooting.md +243 -0
package/doc/web-console.md +17 -0
package/package.json +1 -1
package/public/assets/{PluginConfigurationPanel-CAj6IDmY.js → PluginConfigurationPanel-DVQ7lQ2N.js} +2 -2
package/public/remoteEntry.js +1 -1

package/dist/restore.js CHANGED Viewed

@@ -201,6 +201,15 @@ function snapshotSQL(sinceIso, identitySinceIso, withKind) {
 function isMissingKindColumn(err) {
     return /Invalid column:\s*value_kind/i.test(err instanceof Error ? err.message : String(err));
 }
+// A leaf the server has written holds `value`, but a node can exist without
+// one: meta published for a path creates it. A vessel name is a plain string
+// at the context's root, with no leaf around it.
+function inModel(node) {
+    if (typeof node === "object" && node !== null) {
+        return node.value !== undefined;
+    }
+    return node !== undefined;
+}
 function decodeValue(row) {
     const text = row.valuetext;
     if (text === null || text === undefined)
@@ -298,10 +307,11 @@ export async function restoreFromHistory(deps, options) {
         // target that never expires.
         if (!entry.byPath.has("navigation.position"))
             continue;
-        // A vessel that transmitted while the query ran is already current; its
-        // stored fix is stale by comparison and replaying it would move the
-        // target backwards.
-        if (deps.hasLiveData?.(storedContext)) {
+        // Stored "self" is a placeholder for whatever this server's self context
+        // is; every other context is already a real Signal K context string.
+        const context = storedContext === "self" ? selfContext : storedContext;
+        // Already drawn, from a fix at least as new as the stored one.
+        if (inModel(deps.getPath(`${context}.navigation.position`))) {
             skippedLive++;
             continue;
         }
@@ -324,6 +334,13 @@ export async function restoreFromHistory(deps, options) {
                 entry.byPath.set(path, { ...newest, value, isName: false });
             }
         }
+        // Looked up after the leaves are joined, under the bare path the model
+        // keeps an object identity at.
+        for (const path of entry.byPath.keys()) {
+            if (inModel(deps.getPath(`${context}.${path}`))) {
+                entry.byPath.delete(path);
+            }
+        }
         // One update per distinct recorded time. These paths were sampled at
         // different moments — an AIS name repeats every ~6 minutes while position
         // arrives every few seconds — so putting them all under the newest
@@ -336,9 +353,6 @@ export async function restoreFromHistory(deps, options) {
                 : { path, value: row.value });
             byTimestamp.set(row.ts, group);
         }
-        // Stored "self" is a placeholder for whatever this server's self context
-        // is; every other context is already a real Signal K context string.
-        const context = storedContext === "self" ? selfContext : storedContext;
         handleMessage({
             context,
             updates: [...byTimestamp].map(([timestamp, values]) => ({
@@ -354,7 +368,7 @@ export async function restoreFromHistory(deps, options) {
     }
     debug(`restored ${contexts} context(s), ${values} value(s) from history` +
         (skippedStale ? `, skipped ${skippedStale} stale row(s)` : "") +
-        (skippedLive ? `, skipped ${skippedLive} already live` : ""));
+        (skippedLive ? `, skipped ${skippedLive} already in the model` : ""));
     return { contexts, values, skippedStale, skippedLive };
 }
 //# sourceMappingURL=restore.js.map

package/dist/restore.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"restore.js","sourceRoot":"","sources":["../src/restore.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,yBAAyB,CAAC;~~AAmCxD~~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~~wEAAwE~~;~~QACxE~~,~~oEAAoE~~;~~QACpE~~,~~oBAAoB;QACpB~~,~~IAAI~~,~~IAAI~~,CAAC,WAAW,~~EAAE~~,CAAC,aAAa,CAAC,EAAE,CAAC;~~YACtC~~,WAAW,EAAE,CAAC;YACd,SAAS;QACX,CAAC;QAED,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,qBAAqB,EAAE,CAAC;YACrD,MAAM,KAAK,GAA4B,EAAE,CAAC;YAC1C,IAAI,MAAgD,CAAC;YACrD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;gBAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,GAAG;oBAAE,SAAS;gBACnB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;gBAC/C,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;oBAAE,MAAM,GAAG,GAAG,CAAC;gBACpD,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YACD,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,qEAAqE;QACrE,0EAA0E;QAC1E,mEAAmE;QACnE,sEAAsE;QACtE,MAAM,WAAW,GAAG,IAAI,GAAG,EAA8C,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,MAAM;gBACR,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,KAAe,EAAE,EAAE;gBACpD,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAC/B,CAAC;YACF,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,~~yEAAyE;QACzE,qEAAqE;QACrE,MAAM,OAAO,GAAG,~~aAAa,~~KAAK,MAAM,~~CAAC~~,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC~~;~~QAEvE,aAAa,CAAC;~~YACZ,OAAO;YACP,OAAO,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;gBACtD,mEAAmE;gBACnE,iEAAiE;gBACjE,OAAO,EAAE,cAAc;gBACvB,SAAS;gBACT,MAAM;aACP,CAAC,CAAC;SACJ,CAAC,CAAC;QAEH,QAAQ,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED,KAAK,CACH,YAAY,QAAQ,gBAAgB,MAAM,wBAAwB;QAChE,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,YAAY,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,WAAW,~~eAAe~~,CAAC,CAAC,CAAC,EAAE,CAAC,~~CAC/D~~,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;AACzD,CAAC"}
1	+ {"version":3,"file":"restore.js","sourceRoot":"","sources":["../src/restore.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,yBAAyB,CAAC;AAuCxD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,YAAY,GAAG;IACnB,qBAAqB;IACrB,iCAAiC;IACjC,4BAA4B;IAC5B,wBAAwB;IACxB,4BAA4B;IAC5B,kBAAkB;CACV,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,cAAc,GAAG;IACrB,yEAAyE;IACzE,wEAAwE;IACxE,yDAAyD;IACzD,2EAA2E;IAC3E,qEAAqE;IACrE,qEAAqE;IACrE,mEAAmE;IACnE,wEAAwE;IACxE,wEAAwE;IACxE,UAAU;IACV,oBAAoB;IACpB,uBAAuB;IACvB,yBAAyB;IACzB,uEAAuE;IACvE,2EAA2E;IAC3E,2EAA2E;IAC3E,2EAA2E;IAC3E,mEAAmE;IACnE,eAAe;IACf,uBAAuB;IACvB,oBAAoB;IACpB,aAAa;IACb,wDAAwD;IACxD,4EAA4E;IAC5E,uEAAuE;IACvE,0EAA0E;IAC1E,6EAA6E;IAC7E,2EAA2E;IAC3E,uEAAuE;IACvE,SAAS;IACT,MAAM;CACE,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,kBAAkB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEnD;;;;GAIG;AACH,MAAM,iBAAiB,GAAwB,IAAI,GAAG,CAAC,cAAc,CAAC,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,qBAAqB,GAGtB,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI;IACJ,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC;CAC/D,CAAC,CAAC,CAAC;AAEJ,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,OAAO,CAAC,MAAyB;IACxC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAClB,QAAgB,EAChB,gBAAwB,EACxB,QAAiB;IAEjB,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzC,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,oEAAoE;IACpE,8DAA8D;IAC9D,MAAM,IAAI,GAAG,QAAQ;QACnB,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,uEAAuE,CAAC;IAE5E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,wDAAwD;IACxD,EAAE;IACF,4EAA4E;IAC5E,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,MAAM,GACV,YAAY,QAAQ,kBAAkB,MAAM,QAAQ;QACpD,WAAW,gBAAgB,kBAAkB,QAAQ,KAAK,CAAC;IAE7D,MAAM,GAAG,GACP,6DAA6D;QAC7D,oCAAoC,MAAM,EAAE;QAC5C,0CAA0C,CAAC;IAE7C,MAAM,GAAG,GACP,kDAAkD,IAAI,QAAQ;QAC9D,0BAA0B,MAAM,EAAE;QAClC,0CAA0C,CAAC;IAE7C,2EAA2E;IAC3E,gCAAgC;IAChC,MAAM,GAAG,GACP,kDAAkD;QAClD,mEAAmE;QACnE,sDAAsD,QAAQ,GAAG;QACjE,oCAAoC,CAAC;IAEvC,OAAO,IAAI,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,GAAG,CAAC;AAC1D,CAAC;AAED,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,SAAS,mBAAmB,CAAC,GAAY;IACvC,OAAO,+BAA+B,CAAC,IAAI,CACzC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CACjD,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,6EAA6E;AAC7E,iDAAiD;AACjD,SAAS,OAAO,CAAC,IAAa;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAQ,IAA4B,CAAC,KAAK,KAAK,SAAS,CAAC;IAC3D,CAAC;IACD,OAAO,IAAI,KAAK,SAAS,CAAC;AAC5B,CAAC;AAED,SAAS,WAAW,CAAC,GAA4B;IAC/C,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC;IAC3B,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACrD,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACvB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACvC,CAAC;QACD,KAAK,SAAS;YACZ,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC;QACjC,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAC5D,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE;gBACzB,CAAC,CAAC,IAAI,CAAC;QACX,CAAC;QACD;YACE,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAiB,EACjB,OAAuB;IAEvB,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IAChE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAChE,uEAAuE;IACvE,MAAM,gBAAgB,GAAG,IAAI,IAAI,CAAC,GAAG,GAAG,kBAAkB,CAAC,CAAC,WAAW,EAAE,CAAC;IAE1E,MAAM,MAAM,GAAG,MAAM,WAAW;SAC7B,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,CAAC,CAAC;SACnD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QACtB,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC;YAAE,MAAM,GAAG,CAAC;QACzC,OAAO,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEL,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE3C,4EAA4E;IAC5E,8EAA8E;IAC9E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,eAAe;IACf,MAAM,SAAS,GAAG,IAAI,GAAG,EAQtB,CAAC;IAEJ,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,aAAa,GAAI,GAAG,CAAC,OAAkB,IAAI,MAAM,CAAC;QACxD,MAAM,MAAM,GAAG,aAAa,KAAK,MAAM,CAAC;QACxC,IAAI,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW;YAAE,SAAS;QAC7C,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa;YAAE,SAAS;QAEhD,MAAM,EAAE,GAAG,GAAG,CAAC,EAAY,CAAC;QAC5B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAc,CAAC;QAChC,yEAAyE;QACzE,gEAAgE;QAChE,EAAE;QACF,sEAAsE;QACtE,uEAAuE;QACvE,sEAAsE;QACtE,yCAAyC;QACzC,MAAM,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;YACxD,YAAY,EAAE,CAAC;YACf,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,IAAI;YAAE,SAAS;QAE7B,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI;YAC5C,MAAM,EAAE,IAAI,GAAG,EAGZ;SACJ,CAAC;QAEF,kEAAkE;QAClE,sEAAsE;QACtE,0EAA0E;QAC1E,qDAAqD;QACrD,MAAM,MAAM,GACV,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;QAE1E,sEAAsE;QACtE,0EAA0E;QAC1E,0EAA0E;QAC1E,2CAA2C;QAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,IAAI,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;YACzC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;QAC/D,CAAC;QAED,SAAS,CAAC,GAAG,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,MAAM,CAAC,aAAa,EAAE,KAAK,CAAC,IAAI,SAAS,EAAE,CAAC;QAC/C,0EAA0E;QAC1E,qEAAqE;QACrE,6BAA6B;QAC7B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC;YAAE,SAAS;QAEvD,yEAAyE;QACzE,qEAAqE;QACrE,MAAM,OAAO,GAAG,aAAa,KAAK,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,CAAC;QAEvE,+DAA+D;QAC/D,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,OAAO,sBAAsB,CAAC,CAAC,EAAE,CAAC;YAC5D,WAAW,EAAE,CAAC;YACd,SAAS;QACX,CAAC;QAED,uEAAuE;QACvE,qEAAqE;QACrE,uEAAuE;QACvE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,qBAAqB,EAAE,CAAC;YACrD,MAAM,KAAK,GAA4B,EAAE,CAAC;YAC1C,IAAI,MAAgD,CAAC;YACrD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;gBAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,GAAG;oBAAE,SAAS;gBACnB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;gBAC/C,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI;oBAAE,MAAM,GAAG,GAAG,CAAC;gBACpD,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;YACD,IAAI,MAAM,EAAE,CAAC;gBACX,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,uEAAuE;QACvE,+BAA+B;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAChD,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,qEAAqE;QACrE,0EAA0E;QAC1E,mEAAmE;QACnE,sEAAsE;QACtE,MAAM,WAAW,GAAG,IAAI,GAAG,EAA8C,CAAC;QAC1E,KAAK,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,MAAM;gBACR,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,KAAe,EAAE,EAAE;gBACpD,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAC/B,CAAC;YACF,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QAED,aAAa,CAAC;YACZ,OAAO;YACP,OAAO,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;gBACtD,mEAAmE;gBACnE,iEAAiE;gBACjE,OAAO,EAAE,cAAc;gBACvB,SAAS;gBACT,MAAM;aACP,CAAC,CAAC;SACJ,CAAC,CAAC;QAEH,QAAQ,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED,KAAK,CACH,YAAY,QAAQ,gBAAgB,MAAM,wBAAwB;QAChE,CAAC,YAAY,CAAC,CAAC,CAAC,aAAa,YAAY,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa,WAAW,uBAAuB,CAAC,CAAC,CAAC,EAAE,CAAC,CACvE,CAAC;IAEF,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;AACzD,CAAC"}

package/doc/configuration.md ADDED Viewed

@@ -0,0 +1,98 @@
+# Configuration
+The config panel groups the settings as: the **status card** (running state,
+rows, active paths, restore outcome, WAL state), the **update check** and
+**image version** picker (latest, pre-releases and the last three stable
+releases), **Connection**, **Recording**, **History**, and the collapsible
+**Path filtering**, **Compression (on-disk)**, **InfluxDB Migration**, **Data
+Export** and **Danger zone** sections. The Danger zone removes the container and
+all of its data — including what Signal K's plugin uninstall cannot reach on
+rootless Podman.
+| Setting                       | Default      | Description                                                                                                                                                                                      |
+| ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| QuestDB image version         | `latest`     | Image tag; the dropdown lists the latest release, pre-releases, and the last three stable releases                                                                                               |
+| Manage QuestDB container      | `true`       | Let signalk-container run QuestDB; off = connect to an external QuestDB                                                                                                                          |
+| QuestDB host                  | `127.0.0.1`  | External mode only; in managed mode the address is resolved automatically                                                                                                                        |
+| HTTP port                     | `9000`       | External mode, or the host binding when "Bind to 0.0.0.0" is on; otherwise signalk-container allocates it                                                                                        |
+| ILP port                      | `9009`       | External mode, or the host binding when "Bind to 0.0.0.0" is on; otherwise signalk-container allocates it                                                                                        |
+| PostgreSQL port               | `8812`       | Host binding for Grafana/psql when "Bind to 0.0.0.0" is on                                                                                                                                       |
+| QuestDB memory limit          | `768m`       | Hard cgroup cap on the container (empty = unlimited); the JVM heap gets half of it, so heap plus off-heap stays inside                                                                           |
+| QuestDB CPU limit (cores)     | `1.5`        | Fractional cores (0 = unlimited)                                                                                                                                                                 |
+| Default sampling rate (ms)    | `2000`       | Minimum ms between writes for any one path (0 = every update)                                                                                                                                    |
+| Per-path sampling rates (ms)  | _(empty)_    | Glob → ms overrides, one `pattern ms` per line in the panel (0 = wire speed, see [Sampling](recording.md#what-is-recorded))                                                                      |
+| Unchanged-value heartbeat (s) | `300`        | A value equal to the last one recorded is written again only this often; changes are written at the sampling rate (0 = every sample, see [Change-only recording](recording.md#what-is-recorded)) |
+| Write batch interval (ms)     | `5000`       | How often buffered samples are committed — one WAL transaction per table per commit (see [Performance](deployment.md#performance-pi-and-other-low-power-hosts))                                  |
+| Record own vessel             | `true`       | Record the `self` context                                                                                                                                                                        |
+| Record AIS targets            | `true`       | Record other vessels                                                                                                                                                                             |
+| Record all sources            | `false`      | Record every source of a path, not only the one the source priorities prefer (see [Source priorities](recording.md#what-is-recorded))                                                            |
+| Restore vessels on startup    | `false`      | Replay each vessel's last recorded position after a restart (see [Startup restore](recording.md#startup-restore))                                                                                |
+| Restore max age (minutes)     | `9`          | Only replay values recorded within this window                                                                                                                                                   |
+| Allow `sourcePolicy=all`      | `false`      | Let History API callers split a path into one column per recording source (see [sourcePolicy=all](history-api.md#sourcepolicyall))                                                               |
+| QuestDB console webapp        | `true`       | Serve QuestDB's console inside the Signal K admin UI, admin only (see [Web Console](web-console.md))                                                                                             |
+| Retention (days)              | `0`          | Drop daily partitions older than this (0 = keep forever)                                                                                                                                         |
+| Keep own track                | `true`       | Archive the own vessel's positions before retention drops them (see [Retention and the archive](recording.md#retention-and-the-archive))                                                         |
+| Archived own-vessel paths     | _(empty)_    | Glob patterns of own-vessel numeric paths to archive the same way, e.g. `environment.depth.*`                                                                                                    |
+| Archive resolution (s)        | `10`         | Archived rows are thinned to the first sample per interval (0 = every row)                                                                                                                       |
+| Filter mode                   | `exclude`    | `exclude` the matching paths, or `include` only the matching paths                                                                                                                               |
+| Path patterns                 | _(empty)_    | Glob patterns, one per line, e.g. `environment.wind.*`; empty records everything                                                                                                                 |
+| Compression codec             | `lz4`        | On-disk WAL segments and Parquet exports: `none`, `lz4` (fast) or `zstd` (smaller)                                                                                                               |
+| Compression level             | `3`          | ZSTD level 1–22, used only with `zstd`                                                                                                                                                           |
+| Container network             | `sk-network` | Shared Podman/Docker network QuestDB joins in managed mode, so the companion signalk-grafana reaches it by container DNS; host-port publication is separate ("Bind to 0.0.0.0")                  |
+| Bind to 0.0.0.0               | `false`      | Publish QuestDB's ports on all interfaces (see [Connectivity](deployment.md#connectivity))                                                                                                       |
+## Default history provider
+Which registered provider answers `/signalk/v2/api/history/` is the operator's
+choice: pick it once under **Data → Preferences → Default History Provider**
+(server 2.31 or newer); the server persists it as `historyApi.defaultProvider`
+in `settings.json`, and it survives restarts and plugin load order. If no
+default is configured, the server uses whichever provider registers first.
+Versions 2.0.0 and earlier asked the server to make QuestDB the default on every
+start; that is gone as of 2.0.1 — it could silently override a default you had
+chosen, and on servers with security enabled it never worked at all.
+## QuestDB updates
+The panel's **update check** compares the running QuestDB with its latest stable
+release. **Update** pulls that release, recreates the container on it and saves
+it as the image version.
+After the plugin itself was updated, and at its very first start, the plugin
+also checks once on its own, in the background. It does so only in managed mode,
+and only where the image version is a tag that moves, such as the default
+`latest`. If QuestDB runs an older release than the latest stable one, the
+plugin pulls the tag again and recreates the container on it. The image version
+stays `latest`. Without this check, QuestDB on `latest` would stay on whatever
+release the first install pulled, because signalk-container pulls an image only
+when it is missing. An image version that names one release, such as `9.4.3`,
+stays as it is, and so does one that **Update** saved while the check was
+waiting. QuestDB is down while it starts again, as with **Update**. Progress
+goes to the debug log, and failures go to the server log. A recreate that fails
+half way and leaves QuestDB stopped or without a container is followed by a
+start, as the plugin's own start would do. Only if that fails too does the
+status line say so.
+With [signalk-internet](https://github.com/meri-imperiumi/signalk-internet)
+enabled, the check waits for a free link. On a metered, captive or offline link
+it asks again from time to time, for as long as the plugin runs. Without
+signalk-internet, the link counts as free. Telling the two apart needs
+signalk-container 1.38.0 or later; with an older one, the check does not run. A
+failure to read the running or the latest version is also tried again later.
+The check is done once QuestDB runs the latest release, or once its container
+runs the image the pull brought, even if QuestDB still reports an older release
+afterwards. It then waits for the next plugin update. The next start checks
+again wherever the container keeps its old image, or where the new one cannot
+be told from the old:
+- the plugin stopped first;
+- the download failed, or something else failed before the recreate;
+- an InfluxDB import, a GPX import or an export was running;
+- the string table was being rebuilt;
+- the container was stopped, which the check leaves as it is;
+- the container was wedged;
+- the tag on Docker Hub did not name the latest release yet.
+A tag that never reaches the latest release, such as `9` while the latest is
+`10.1.0`, therefore costs a pull and a look at GitHub at every start.

package/doc/deployment.md ADDED Viewed

@@ -0,0 +1,249 @@
+# Deployment
+## Requirements
+- Node.js 24 or newer
+- QuestDB 8.1 or newer (resolution queries use `SAMPLE BY … FROM … TO`). This
+  applies to an external QuestDB and to a pinned **QuestDB image version** in
+  managed mode; `latest` always qualifies
+- Signal K server — 2.31 or newer to choose the default history provider in the
+  admin UI
+- For managed mode: the
+  [signalk-container](https://github.com/dirkwa/signalk-container) plugin, and
+  Podman 5.4 or newer (what Debian 13 "trixie" ships) or Docker.
+  signalk-container 1.29.0 or newer is recommended; the plugin runs with 1.14.0
+  or newer, but older versions lose parts of it — below 1.19.0 the Danger zone
+  cannot delete data kept on a named volume, below 1.26 the macOS open-files
+  problem shows as a generic error, below 1.29.0 a container the runtime refuses
+  to recreate is not reported (see [Troubleshooting](troubleshooting.md)). On rootless Podman below
+  5.5 the plugin's open-files request is inherited from the podman service
+  rather than granted per container
+  ([containers/podman#25881](https://github.com/containers/podman/issues/25881));
+  signalk-container accounts for this.
+## Connectivity
+In **managed mode** the plugin does not need `QuestDB host` to be correct for
+your deployment — signalk-container resolves the right address automatically,
+whether Signal K runs on bare metal or is itself containerized:
+- **Bind to 0.0.0.0 = off (default).** QuestDB stays private. signalk-container
+  binds its ports to the host loopback (bare-metal Signal K) or attaches QuestDB
+  to Signal K's own container network (containerized Signal K), and the plugin
+  connects to whatever address it reports back. Nothing is exposed to the
+  network. QuestDB is also attached to the shared `Container network` so the
+  companion [signalk-grafana](https://github.com/dirkwa/signalk-grafana) plugin
+  still reaches it by container DNS. This is the recommended setup and fixes
+  connectivity for Signal K in a container.
+- **Bind to 0.0.0.0 = on.** QuestDB stays attached to the shared
+  `Container network`; the setting publishes its HTTP/ILP/PostgreSQL ports on
+  all host interfaces, using the configured port numbers. Enable this only to
+  reach QuestDB from another machine or from a Grafana running in a separate
+  Docker instance. When Signal K itself is containerized, the plugin probes
+  which address reaches the published ports — its own loopback first, then the
+  runtime's `host.containers.internal` gateway — and uses the one QuestDB
+  answers on.
+In **external mode** (`Manage QuestDB container` off) the plugin connects to the
+QuestDB you point it at via `QuestDB host` and the HTTP/ILP ports.
+## Data storage
+QuestDB's data root is the plugin's own data directory,
+`<config>/plugin-config-data/signalk-questdb`, whatever the deployment. Data
+survives container restarts, image upgrades, and plugin disable/enable cycles.
+How it reaches the container differs:
+- **Bare-metal Signal K**: that directory, mounted at `/var/lib/questdb`.
+- **Signal K in a container with its config directory bind-mounted**: the exact
+  host path of that directory, mounted at `/var/lib/questdb`.
+- **Signal K in a container with its config directory on a named volume**: the
+  volume cannot be mounted from a subdirectory, so it is mounted whole at
+  `/signalk-vols/<volume>` and QuestDB is pointed at the plugin's directory
+  inside it (`QUESTDB_DATA_DIR`). A database found at the volume's root — where
+  a whole-volume mount put it — is moved into the plugin's directory on start;
+  both are the same volume, so nothing is copied. A purge deletes the directory
+  from the Signal K process, since the runtime cannot mount the volume by Signal
+  K's path; where QuestDB's user owns it and the Signal K user cannot delete it,
+  the purge says so and the directory is deleted by hand.
+QuestDB's entrypoint makes its data root its own on start, so the plugin keeps
+the one file it writes alongside — the import checkpoint,
+`signalk-questdb.influx-import-checkpoint.json` — next to the directory rather
+than in it. A purge removes it, whether or not the data could be deleted.
+## Durability on power loss
+The managed container runs QuestDB with `cairo.commit.mode=sync`.
+QuestDB's default is `nosync`: nothing on the ingest path is ever fsynced, and
+durability is left to the OS page cache. On a power cut an arbitrary subset of
+recent writes survives — including the case where a commit record reaches disk
+while the row data it describes does not. QuestDB then fails while _opening_
+that table's partition, which suspends the table permanently: neither a lossless
+`RESUME WAL` nor a bounded `RESUME WAL FROM TXN` skip can get past it, because
+the failure happens before any transaction is read. Repair means hand-patching
+the commit record.
+With `sync`, partition columns are fsynced before the commit record is written
+and WAL segments are fsynced on commit, so the stored state can never claim data
+that isn't durable. The cost is a few fsyncs per commit interval — writes are
+already batched (see **Write batch interval**), so at boat data rates it is
+negligible against losing a table.
+**Running an external QuestDB?** Set this yourself in `server.conf`:
+```ini
+cairo.commit.mode=sync
+```
+## WAL suspension
+QuestDB ingestion is two-stage: the sequencer durably commits every batch (the
+writer sees success), then a background job applies the transactions to the
+partitions. When that job hits an error it **suspends the table** — the
+sequencer keeps accepting rows, nothing is applied, queries serve stale data,
+and no client-visible error is raised anywhere. Left alone, recording stalls
+silently for as long as nobody looks.
+The plugin watches for this. A suspended table of its own (in external mode,
+only the three tables above and the two archive tables — never someone else's)
+is logged loudly, raised as
+the Signal K notification `notifications.signalk-questdb.walSuspended`, and
+shown on the status card as **WAL suspended**. Two causes need two remedies:
+- **Transient** — disk full since cleared, out of memory, file-descriptor
+  exhaustion: a plain `RESUME WAL` replays every pending transaction,
+  losslessly. The plugin does this by itself, once per stall point; the panel's
+  **Resume** button does the same on request, and the banner clears as the
+  backlog drains.
+- **Unreadable segment** — an unclean container stop mid-write corrupts the
+  in-flight segment's files, and every apply attempt fails on them within
+  milliseconds, so a plain resume re-suspends at once, forever. The only way
+  forward is `RESUME WAL FROM TXN` past the unreadable data, which loses what it
+  skips. The plugin prepares that but never applies it on its own:
+  **/wal-diagnosis** scrapes the engine log for the real reason (the
+  `wal_tables()` error fields often carry none, and a container recreate wipes
+  the engine's memory of it) and computes the minimal skip — the first
+  transaction of the segment after the stuck one — with the number of
+  transactions and the wall-clock window of ingestion it would drop. The panel
+  shows those numbers and offers **Skip**; if the stuck segment is the newest
+  one, skipping drops the entire pending backlog, and the panel says so.
+## Out of memory or not answering
+QuestDB caps the native memory it tracks below the container's memory limit
+and fails any allocation past the cap with `global RSS memory limit exceeded`.
+When something holds memory at the cap, queries fail, the WAL apply job then
+suspends the tables, and in the end QuestDB stops accepting HTTP connections. The JVM stays up throughout, so the
+container's restart policy never acts.
+In managed mode the plugin checks for this every minute while it runs, and
+restarts the QuestDB container when:
+- QuestDB recently reported its global memory limit, and over consecutive
+  checks its native memory is still held at that limit, it fails even the
+  health check with it, or it has stopped answering. A single large query
+  frees what it held when it ends, so it does not count, nor does a client that
+  keeps asking for one.
+- the container is running but QuestDB has answered nothing for several
+  minutes, over consecutive checks. A QuestDB busy with a long statement still
+  answers it in the end, and no check counts while a parquet export streams
+  from it.
+Before the restart the plugin writes QuestDB's message and its last error lines
+to the server log, shows the reason on the status card, and raises the Signal K
+notification `notifications.signalk-questdb.watchdog`. After the restart it
+logs the outcome. Once QuestDB answers again the notification returns to normal;
+when it answered right after the restart, the notification keeps the time and
+the reason. Restarts are rate limited, spaced apart and capped per few hours of
+the plugin running; past that the plugin logs that the restart is held back and
+keeps the alert up. A restart that fails, because stopping or starting the
+container failed, counts against none of these limits: the plugin tries again a
+few minutes later, since the container may be left stopped. It reports the
+first failure; while the retries keep failing, they go to the debug log only.
+The plugin leaves a container alone if someone else stopped it, and starts one
+that its own restart left stopped. One exception: a container stopped by hand
+while a stop of the plugin's is still pending, or right after a restart of the
+plugin's before the plugin has seen it running again, may be started again too.
+While a stop of the plugin's hangs, it sends no further stop. An external
+QuestDB is never restarted. A
+QuestDB that is already stuck when the plugin starts, as after a Signal K
+restart while it was stuck, is not covered: restarting the plugin stops the
+container and starts it afresh.
+The managed container runs with QuestDB's query caches off: history reads put
+their time range into the SQL, so the caches never got a hit, and on older
+QuestDB releases they held memory.
+## Performance (Pi and other low-power hosts)
+- **Default sampling rate** of 2000 ms limits each path to one write per two
+  seconds, keeping write volume modest on busy NMEA 2000 buses; per-path
+  overrides allow faster rates, or wire speed with 0, for critical paths while
+  slow-changing ones stay throttled.
+- **Change-only recording** skips a value that has not changed since it was last
+  written until the heartbeat is due. Paths that hold steady — which is
+  most of them — cost one row per heartbeat instead of one per sampling
+  interval, which cuts both disk use and WAL apply work (see [Recording](recording.md#what-is-recorded)).
+- **Resource caps** of 768 MB RAM and 1.5 CPU cores (cgroup limits via
+  signalk-container) keep QuestDB from squeezing co-resident containers like
+  Grafana, mayara, or signalk-backup. The JVM heap gets half of the memory
+  cap, so total footprint (heap plus off-heap) is bounded, and a JVM that runs
+  out of heap exits so the container restarts instead of hanging. Set the
+  memory limit to empty or the CPU limit to `0` to lift the cap on roomier
+  hosts.
+- **Worker tuning** cuts idle CPU. QuestDB sizes its worker pools from the host
+  core count and busy-polls before sleeping — sensible on a server, wasteful on
+  a mostly idle boat database. The plugin pins its worker pools down and quiets
+  QuestDB's per-commit logging, keeping the messages that matter. One caveat
+  when upgrading the QuestDB image: an unrecognised setting is ignored silently,
+  so a property renamed between releases looks exactly like one that worked.
+- **Batching.** Each commit is one WAL transaction per table, and with
+  deduplicated tables the apply cost of a transaction grows with partition size
+  — frequent tiny commits eventually outpace what a Pi can apply and recording
+  stalls. Bigger batches keep the WAL healthy; the cost is that at most one
+  interval of buffered samples is lost on a hard crash.
+The console's Monitoring view flags any table whose 90th-percentile WAL
+transaction stays under QuestDB's recommended batch size (100 rows) as **"Small
+transactions — consider batching"**. `signalk_position` triggers this
+structurally: it holds exactly one path, so its share of every commit is just
+the handful of GPS fixes since the last one, while the other tables spread
+hundreds of paths across each transaction. At vessel data rates the alert is
+cosmetic; the numbers that matter are on the same page — **Write Amplification**
+near 1x, **Pending Rows** 0 and **Transaction Lag** 0 mean the WAL apply is
+healthy. Clearing the alert for the position table would need roughly 100 fixes
+per commit, a batch window in the minutes; the trade-off is up to one interval
+of buffered data lost on a hard crash, and history that is that much less live.
+## Grafana
+Connect Grafana to QuestDB through the PostgreSQL data source (user `admin`,
+password `quest`, database `qdb`).
+- The companion [signalk-grafana](https://github.com/dirkwa/signalk-grafana)
+  plugin wires this up for you: it runs Grafana as a managed container and
+  reaches QuestDB by container DNS on the shared `sk-network`, so no port needs
+  publishing.
+- A Grafana **on the Signal K host** can reach the PostgreSQL port without
+  binding: with "Bind to 0.0.0.0" off, signalk-container binds it to loopback at
+  a host port of its choosing — `podman port <container>` shows which (the
+  container is `signalk-questdb` behind the `sk-` prefix). With "Bind to
+  0.0.0.0" on it is the configured port, 8812 by default.
+- A Grafana in a **separate Docker instance or on another machine** needs "Bind
+  to 0.0.0.0" and the host's LAN address (`192.168.0.122:8812`, say). That
+  publishes QuestDB's ports to your entire network; only enable it behind a
+  firewall you trust.
+Example query:
+```sql
+SELECT ts AS time, avg(value) AS sog
+FROM signalk
+WHERE path = 'navigation.speedOverGround'
+  AND context = 'self'
+  AND ts BETWEEN $__timeFrom() AND $__timeTo()
+SAMPLE BY $__interval
+```

package/doc/history-api.md ADDED Viewed

@@ -0,0 +1,178 @@
+# History API
+## v2 (REST — `/signalk/v2/api/history/`)
+Registered via `app.registerHistoryApiProvider()`. Supports all aggregate
+methods:
+| Method         | QuestDB mapping                                                                 |
+| -------------- | ------------------------------------------------------------------------------- |
+| `average`      | `avg(value)`                                                                    |
+| `min`          | `min(value)`                                                                    |
+| `max`          | `max(value)`                                                                    |
+| `first`        | `first(value)`                                                                  |
+| `last`         | `last(value)`                                                                   |
+| `mid`          | `(min + max) / 2`                                                               |
+| `middle_index` | the middle row of each bucket, by time — a recorded value, not a computed one   |
+| `sma`          | the `average` bucket, then a moving window over N buckets (`sma:N`, default 5)  |
+| `ema`          | the `average` bucket, then an exponential moving average (`ema:α`, default 0.2) |
+A sample for `sma` and `ema` is one row of the series the window runs over: a
+resolution bucket (its average) when the request names a resolution, a raw row
+otherwise. So `sma:5` at `resolution=180` is a 15-minute moving average, on the
+same grid as every other column in the response. An empty bucket keeps its place
+in the window: the average there is of what the window still holds, and a value
+leaves it N buckets after it arrived. `ema` carries its last value across an
+empty bucket instead.
+Buckets start at the request's `from` and cover the whole range, empty ones
+included. A bucket with no row is not always missing data. Change-only recording (see
+[Recording](recording.md#what-is-recorded)) writes an unchanged value only once per heartbeat, so an empty bucket
+takes the last sample before it — in every aggregate, since every aggregate of a
+steady value is that value — for up to twice the heartbeat after the sample was
+taken, and never into a bucket that has not started yet. At the start of a
+range the sample comes from just before it. Past that window, and with the
+heartbeat set to 0, an empty bucket is `null`. This happens before `sma` and
+`ema`, so a held value counts as a sample. `middle_index` and
+`navigation.position` return recorded rows only.
+A path recorded in radians — a heading, a course, a wind angle; `units: rad` in
+the server's metadata for the path — is averaged as a vector: `average`, `sma`
+and `ema` take the angle of the mean sine and cosine, so 359° and 1° average to
+0°, not 180°. The result keeps the path's convention, `[0, 2π)` for a heading or
+`(−π, π]` for an apparent wind angle; samples that cancel, 0° and 180° in equal
+measure, have no mean direction and give `null`. `min`, `max` and `mid` stay
+arithmetic.
+`navigation.position` answers `first`, `last` and `middle_index` — each a point
+the vessel was at. Any other method runs `first`, and the column's `method` says
+so. A text path (rows in `signalk_str`) answers `first`, `last` and
+`middle_index`. With a resolution, `average`, `min`, `max` and `mid` run `last`,
+the state in force at the bucket's end, and the column's `method` says so.
+`sma` and `ema` read the numeric table only, so a text path has no values for
+them.
+A method name outside the table above fails the request with an error naming
+the path and the method.
+Query example:
+```http
+GET /signalk/v2/api/history/values?paths=navigation.speedOverGround&duration=PT1H&resolution=60
+```
+A `navigation.position` value is a `[longitude, latitude]` pair — GeoJSON order,
+as the History API defines it and as signalk-to-influxdb2 and signalk-parquet
+return it — not the `{latitude, longitude}` object of the data model; a bucket
+without a fix is `null`. The v1 playback API is unaffected: it replays deltas,
+which carry the object.
+**Limits.** A request may produce at most 1 000 000 sample buckets across all of
+its columns (range ÷ resolution × columns); a finer one is rejected with an
+error that says so — use a coarser resolution or a shorter range. Without a
+resolution a column is its raw rows, capped at 10 000 (50 000 for
+`middle_index`).
+### Reading one source
+Append `|<sourceRef>` to a path to read one source's rows only (server 2.29+,
+[signalk-server#2737](https://github.com/SignalK/signalk-server/pull/2737)). The
+same path may appear once per source, giving one column per receiver:
+```http
+GET /signalk/v2/api/history/values?paths=navigation.position|gps.main,navigation.position|gps.backup&duration=PT1H
+```
+Without a sourceRef a path returns all sources mixed. A source-bearing column
+reports its source as `$source` in its `values` entry — the key
+[signalk-server#2817](https://github.com/SignalK/signalk-server/pull/2817)
+settled on, and what v1 playback has always emitted — while the request side
+keeps the name `sourceRef`.
+### sourcePolicy=all
+`sourcePolicy=all`
+([signalk-server#2817](https://github.com/SignalK/signalk-server/pull/2817))
+asks for every source separated without naming them up front. Each path that
+does not already specify a source is expanded into one column per source that
+actually recorded it in range, with the source in the `$source` field of the
+column's `values` entry:
+```http
+GET /signalk/v2/api/history/values?paths=navigation.speedOverGround&duration=PT1H&sourcePolicy=all
+```
+```jsonc
+"values": [
+  { "path": "navigation.speedOverGround", "method": "average", "$source": "gps.aux"  },
+  { "path": "navigation.speedOverGround", "method": "average", "$source": "gps.main" },
+  { "path": "navigation.speedOverGround", "method": "average" }  // unattributed rows
+]
+```
+Named sources come first, sorted, so column order is stable between requests.
+Rows whose source is unset — recorded before the `source` column existed, or
+from a delta that carried none — form their own trailing column with no
+`$source` claim.
+**Off by default**, behind the plugin setting that allows the policy. Expansion
+multiplies the work one request can ask for: a path recorded by four receivers
+becomes four queries and four columns, which on a Pi-class host turns a cheap
+request into an expensive one. The sample-bucket cap counts expanded columns, so
+a resolution that is fine unexpanded may be rejected once expanded.
+Two ceilings bound the fan-out, and a request past either is rejected rather
+than truncated — returning some of the asked-for series without saying so would
+be worse than refusing a request that is too broad. A single path may expand
+into at most 16 columns: recorded by more sources in range, it fails the
+request, and the error names the count, the ceiling and the way out (name the
+sources with `path|sourceRef`, or ask for a shorter range). A whole request is
+bounded at 64 columns, with its own error naming the limit.
+An explicit `path|sourceRef` stays a filter and takes precedence over the
+policy, matching the upstream contract. Requests that name their sources are
+unaffected by the setting either way.
+## v1 (WebSocket playback)
+Registered via `app.registerHistoryProvider()`. Supports playback at
+configurable speed multipliers using chunked reads from QuestDB. Replayed
+updates carry the recorded sourceRef as `$source`, one update per source, so
+consumers see the same attribution the live stream had.
+## REST endpoints
+All under `/plugins/signalk-questdb/api/`; the console is mounted beside them at
+`/plugins/signalk-questdb/console/`. Plugin routes are admin-only by Signal K's
+default.
+| Method | Path                                     | Description                                                                                                                       |
+| ------ | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| GET    | `/status`                                | QuestDB health, row counts, active paths, restore outcome, WAL state, unstorable paths                                            |
+| GET    | `/query?sql=...`                         | Read-only SQL proxy (DDL/DML blocked)                                                                                             |
+| GET    | `/paths`                                 | All recorded paths with row counts and time range                                                                                 |
+| GET    | `/versions`                              | QuestDB releases from GitHub (for the version picker)                                                                             |
+| GET    | `/update/check`                          | Compare the running version against the latest release                                                                            |
+| POST   | `/update/apply`                          | Pull the latest image, recreate the container, reconnect                                                                          |
+| GET    | `/wal-diagnosis`                         | Suspended tables with the engine's reason and a bounded skip plan (see [WAL suspension](deployment.md#wal-suspension))            |
+| POST   | `/resume-wal`                            | Lossless `RESUME WAL` of the suspended tables                                                                                     |
+| POST   | `/resume-wal/skip`                       | Guided skip of the unreadable segment — explicit, quantified, and only on request                                                 |
+| POST   | `/purge-data`                            | Remove the QuestDB container and delete all its data (rootless-Podman-safe)                                                       |
+| GET    | `/migration/detect`                      | Detect InfluxDB (supports `?url=` for a remote one)                                                                               |
+| POST   | `/migration/buckets`                     | List buckets (2.x) or databases (1.x); credentials in the body, never the query string                                            |
+| POST   | `/migration/measurements`                | List measurements and their field keys in a bucket/database                                                                       |
+| POST   | `/migration/contexts`                    | List the vessels a bucket/database holds, and which is this server's                                                              |
+| POST   | `/migration/start`                       | Start an import, or continue a stopped one with `{"resume": true}`; returns immediately                                           |
+| GET    | `/migration/status`                      | Progress and state of the current/last import, and any stopped import that can resume                                             |
+| POST   | `/migration/cancel`                      | Cancel the running import; any saved position is kept                                                                             |
+| POST   | `/migration/discard`                     | Forget a stopped import's saved position, so the next start begins again                                                          |
+| GET    | `/migration/legacy-rows`                 | Count rows an import made before 2.1.5 filed under suffixed paths                                                                 |
+| POST   | `/migration/legacy-rows/remove`          | Rebuild the string table without those rows; recording continues meanwhile                                                        |
+| GET    | `/export?from=...&to=...&format=parquet` | Parquet or CSV export of the `signalk` numeric table (date range required)                                                        |
+| GET    | `/full-export/tables`                    | List the tables the full-export route serves                                                                                      |
+| GET    | `/full-export/:table?from=...&to=...`    | Stream a table as Parquet; optional half-open `[from, to)` window for slicing into shards                                         |
+| GET    | `/gpx-import`                            | The current or last GPX import                                                                                                    |
+| POST   | `/gpx-import`                            | Announce an import: `{filename, size, tracks, fillGapsOnly}`, see [Importing a GPX track](import-export.md#importing-a-gpx-track) |
+| PUT    | `/gpx-import/:id?offset=N`               | One slice of the file, as `application/octet-stream`, at most 8 MiB                                                               |
+| POST   | `/gpx-import/:id/finish`                 | End the import once every byte is in; answers when QuestDB has applied it                                                         |
+| DELETE | `/gpx-import/:id`                        | Abort the import; what it wrote stays                                                                                             |