From 798ff902ae26164780a646e208110c1f9d182f15 Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 30 Jun 2026 16:16:24 -0400 Subject: [PATCH 1/2] docs(analytics): note get_analytics reads without a consistent snapshot get_analytics queries now read against the latest committed data without holding a read snapshot open for the duration of the scan, so long-running analytics queries stay easier on the rest of the system (no pinned snapshot blocking compaction). Documents the behavior and its consistency trade-off. Implements the docs follow-up for HarperFast/harper#35. Co-Authored-By: Claude Opus 4.8 --- reference/analytics/operations.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/reference/analytics/operations.md b/reference/analytics/operations.md index e82d3086..c5e5cace 100644 --- a/reference/analytics/operations.md +++ b/reference/analytics/operations.md @@ -130,6 +130,14 @@ Queries analytics data for a specific metric over a time range. ] ``` +### Read behavior + +`get_analytics` queries read against the latest committed data without holding a consistent read +snapshot open for the duration of the query. This keeps long-running analytics scans easier on the +rest of the system — a query never pins a snapshot that would otherwise block storage compaction +for its duration. The trade-off is that results are not guaranteed to reflect a single point in +time: rows written while the query is iterating may be included. + ## Related - [Analytics Overview](./overview) From f0c5a5b3456d66585ea3a8dc10a4372c5c911baa Mon Sep 17 00:00:00 2001 From: Dawson Toth Date: Tue, 30 Jun 2026 16:19:53 -0400 Subject: [PATCH 2/2] docs(analytics): tighten get_analytics read-behavior wording Address review feedback: use more precise phrasing ("minimizes the impact of...") instead of "keeps ... easier on the rest of the system". Co-Authored-By: Claude Opus 4.8 --- reference/analytics/operations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/analytics/operations.md b/reference/analytics/operations.md index c5e5cace..5525b6ab 100644 --- a/reference/analytics/operations.md +++ b/reference/analytics/operations.md @@ -133,9 +133,9 @@ Queries analytics data for a specific metric over a time range. ### Read behavior `get_analytics` queries read against the latest committed data without holding a consistent read -snapshot open for the duration of the query. This keeps long-running analytics scans easier on the -rest of the system — a query never pins a snapshot that would otherwise block storage compaction -for its duration. The trade-off is that results are not guaranteed to reflect a single point in +snapshot open for the duration of the query. This minimizes the impact of long-running analytics +scans on the rest of the system — a query never pins a snapshot that would otherwise block storage +compaction for its duration. The trade-off is that results are not guaranteed to reflect a single point in time: rows written while the query is iterating may be included. ## Related