When HelixQL samples instead of scanning everything, how far off can the answer be? We publish the error bound, not just a disclaimer.

For very large scans — billions of rows over long time ranges — HelixQL can answer `summarize` queries approximately, using reservoir sampling instead of a full scan, when a query opts into `approx summarize`. The obvious question is how wrong the answer can be, and we think a vague "approximate" label isn't good enough for engineers making decisions during an incident.

The sampling method

Approximate queries use reservoir sampling at a configurable rate (default targets a 100,000-row sample regardless of source size) uniformly across the scanned chunks, weighted so each chunk contributes proportionally to its row count. This avoids the common failure mode of naive sampling, where a scan that touches unevenly-sized chunks over-represents small, dense time windows.

from traces
| where service == 'checkout-api' and range == 30d
| approx summarize p95(duration), count() by route
| where confidence_interval_width < 0.05  # reject groups whose CI is too wide to trust

The error bound, concretely

For a `count()` aggregation, standard sampling theory gives a relative standard error of roughly 1/sqrt(sample_size) for a uniform random sample, which at our default 100,000-row sample works out to about 0.32% relative error at one standard deviation, or roughly ±0.6% at a 95% confidence level for a well-mixed population. For `p95`/`p99` quantile estimates, the error is wider and depends on the local density of the distribution near that quantile — we compute this per query using the t-digest sketch's own error estimate rather than a fixed constant, since a p99 estimate over a distribution with a sharp cliff is inherently less certain than one over a smooth tail.

Why we surface the confidence interval, not just the estimate

Every `approx summarize` result carries a `confidence_interval_width` field per group, and low-population groups (a route hit only 40 times in the sampled window, for instance) get a visibly wider interval rather than a falsely precise-looking number. We validated this against ground truth on 20 large historical queries re-run as full scans: 94% of our reported 95% confidence intervals actually contained the true value, close enough to the nominal 95% that we trust the estimator in production.

What this means for on-call

During an incident, a 30-day approximate query returns in roughly 400ms instead of the 25-40s a full scan over that range would take, with an honestly-labeled error bound instead of a silent one — good enough to say "yes, p95 really did double," even if the exact decimal isn't the one you'd cite in a postmortem.

  • Reservoir sampling targets a 100,000-row sample by default, weighted proportionally across chunks.
  • Count aggregations carry roughly ±0.6% relative error at 95% confidence at the default sample size.
  • Validated against 20 full-scan ground-truth queries: reported 95% confidence intervals were correct 94% of the time.