Add SUBSAMPLE keyword documentation

documentation/changelog.mdx

@@ -21,6 +21,12 @@ This page tracks significant updates to the QuestDB documentation.
 - [ALTER GROUP](/docs/query/sql/acl/alter-group/) - New reference page covering `SET MEMORY LIMIT` and external alias mapping
 - [Migrate QuestDB onto the Kubernetes Operator](/docs/enterprise-kubernetes-operator/getting-started/migrate/) - Move an existing Enterprise deployment onto the Operator with a replica-first cutover: restore the source backup, consume replication WAL, then promote after a controlled source drain
 - [Copy a schema to another instance](/docs/cookbook/operations/copy-schema-between-instances/) - Recreate one instance's tables, views, and materialized views on another from `SHOW CREATE DATABASE`, either by replaying the statements over the REST API or by dumping them to a `.sql` file, with `INCLUDE (SCHEMA)` and `INCLUDE (ACL)` for separating structure from permissions on Enterprise, plus the Web Console schema explorer as a manual alternative and the ordering caveat that comes with it
+- [SUBSAMPLE](/docs/query/sql/subsample/) - New SQL keyword that reduces a query result to a subset of its existing rows, without interpolating values. Covers the six methods with a diagram each: `lttb` for line charts, with a gap-preserving mode, `minmax` and `m4` for per-time-bucket envelopes, `uniform` and `cadence` for position-based selection, and `sdt` (Swinging Door Trending) for error-bounded compression with a `2 * compdev` reconstruction bound and an animated walkthrough. Also covers where the clause goes in a query, output order, `NULL` handling, and which query shapes each method accepts
+- [SUBSAMPLE window functions](/docs/query/functions/window-functions/reference/#subsample-window-functions) - New category with `cadence()`, `lttb()`, `m4()`, `minmax()`, `sdt()`, and `uniform()`, which return a Boolean keep flag per row instead of the reduced row set. Covers the outer-query filter pattern, the ordering, framing, and `NULL` rules of each function, `PARTITION BY` and `IGNORE NULLS` support on `sdt()`, and [when to use each form](/docs/query/sql/subsample/#window-function-form)
+
+### Reference
+
+- Added [`cairo.sql.subsample.max.rows`](/docs/configuration/cairo-engine/#cairosqlsubsamplemaxrows), the input row limit for the `lttb`, `m4`, `minmax`, `uniform`, and `cadence` methods of `SUBSAMPLE`. It does not apply to `sdt`
 
 ### Updated
 

documentation/configuration/cairo-engine.md

@@ -870,6 +870,21 @@ CALENDAR, `false` corresponds to ALIGN TO FIRST OBSERVATION.
 SAMPLE BY index query page size (maximum values returned in a single scan).
 `0` means to use the symbol block capacity.
 
+### cairo.sql.subsample.max.rows
+
+- **Default**: `100000000`
+- **Reloadable**: no
+
+Maximum number of input rows accepted by the count-based and stride-based
+[SUBSAMPLE](/docs/query/sql/subsample/) methods: `lttb`, `m4`, `minmax`,
+`uniform`, and `cadence`. Exceeding this limit returns an error. Every input
+row counts, including rows that `lttb`, `m4`, or `minmax` skip because of a
+`NULL` value. The limit is independent of the `targetPoints` argument. Must
+be between 1 and 2,147,483,647.
+
+This limit does not apply to `sdt`, which remains subject to the query's
+normal memory limits.
+
 ## Window functions
 
 ### cairo.sql.analytic.initial.range.buffer.size

documentation/query/functions/window-functions/overview.md

@@ -44,6 +44,7 @@ Arithmetic operations on window functions (e.g., `sum(...) OVER (...) / sum(...)
 | Function | Description | Respects Frame |
 |----------|-------------|----------------|
 | [`avg()`](reference.md#avg) | Average value in window (also supports EMA and VWEMA) | Yes (standard) / No (EMA/VWEMA) |
+| [`cadence()`](reference.md#cadence) | SUBSAMPLE keep flag: every Nth row | No (frame clause rejected) |
 | [`corr()`](reference.md#corr) | Pearson correlation coefficient | Yes |
 | [`count()`](reference.md#count) | Count rows or non-null values | Yes |
 | [`covar_pop()` / `covar_samp()`](reference.md#covariance) | Covariance between two columns | Yes |
@@ -54,18 +55,23 @@ Arithmetic operations on window functions (e.g., `sum(...) OVER (...) / sum(...)
 | [`lag()`](reference.md#lag) | Value from previous row | No |
 | [`last_value()`](reference.md#last_value) | Last value in window | Yes |
 | [`lead()`](reference.md#lead) | Value from following row | No |
+| [`lttb()`](reference.md#lttb) | SUBSAMPLE keep flag: Largest Triangle Three Buckets | No (frame clause rejected) |
+| [`m4()`](reference.md#m4) | SUBSAMPLE keep flag: first, last, min, max per time bucket | No (frame clause rejected) |
 | [`max()`](reference.md#max) | Maximum value in window | Yes |
 | [`min()`](reference.md#min) | Minimum value in window | Yes |
+| [`minmax()`](reference.md#minmax) | SUBSAMPLE keep flag: min and max per time bucket | No (frame clause rejected) |
 | [`nth_value()`](reference.md#nth_value) | N-th value in window | Yes |
 | [`ntile()`](reference.md#ntile) | Bucket number from 1 to N | No |
 | [`percent_rank()`](reference.md#percent_rank) | Relative rank (0 to 1) | No |
 | [`rank()`](reference.md#rank) | Rank with gaps for ties | No |
 | [`row_number()`](reference.md#row_number) | Sequential row number | No |
+| [`sdt()`](reference.md#sdt) | SUBSAMPLE keep flag: Swinging Door Trending, error-bounded | No (frame clause rejected) |
 | [`stddev_pop()` / `stddev_samp()` / `stddev()`](reference.md#stddev) | Standard deviation (population or sample) | Yes |
 | [`sum()`](reference.md#sum) | Sum of values in window | Yes |
+| [`uniform()`](reference.md#uniform) | SUBSAMPLE keep flag: evenly spaced rows | No (frame clause rejected) |
 | [`var_pop()` / `var_samp()` / `variance()`](reference.md#variance) | Variance (population or sample) | Yes |
 
-**Respects Frame**: Functions marked "Yes" use the frame clause (`ROWS`/`RANGE BETWEEN`). Functions marked "No" operate on the entire partition regardless of frame specification.
+**Respects Frame**: Functions marked "Yes" use the frame clause (`ROWS`/`RANGE BETWEEN`). Functions marked "No" either operate on the entire partition or reject explicit frame specifications. See each function reference for its behavior.
 
 ## When to use window functions