From 4cfa7bb7e7c16765dece817561e75c10aea3b0f6 Mon Sep 17 00:00:00 2001 From: OffgridwithJD Date: Sat, 29 Aug 2026 22:49:21 +0000 Subject: [PATCH] docs: cluster() is not numeric-only, and the error already said so (#827 follow-up) COMMENT ON FUNCTION pgcolumnar.vacuum_sorted describes the alternative as "the numeric-only Z-order cluster()". That is wrong in both directions, and it is in the shipped v1.0-alpha2, in the full script and in the upgrade script, so \df+ prints it to a user today. cluster_type_supported() takes boolean, smallint, integer, bigint, real, double precision, date, timestamp and timestamptz. Several of those are not numeric. And numeric itself is absent: NUMERICOID appears nowhere in the file, so the one type the sentence names is precisely the one cluster() refuses. Measured rather than read, with a positive control so the deny arms are not vacuous: on a 20,000 row table, vacuum_sorted accepts numeric and text; cluster() accepts int, and rejects numeric with "column n of type numeric cannot be used as a clustering key" and text likewise. The extension already contradicted the sentence. A rejected column raises an errhint reading "Z-order clustering supports integer, date/time, boolean, and floating-point columns". A user who trips the gate is told the truth; a user who reads the catalog first is not. The comment now uses the errhint's wording, so the two agree and there is one description of this rule rather than two. The same sentence sat in src/columnar_vacuum.c as a code comment above pgcolumnar_vacuum_sorted. That is where the catalog string came from, so it is corrected too; leaving it would leave the input to the defect in place. The 1.0-alpha2 -> 1.0-alpha3 upgrade re-issues the comment, as set_options, expire, parallel_copy and sort_status already do in that script. That half is not optional. native_upgrade_converge hashes obj_description(p.oid,'pg_proc') for every function in the schema, so correcting only the full script makes a fresh install and an upgraded one disagree. Verified in that order: 8 of 8 on unmodified main; with only the full script corrected it FAILS on both the 1.0-alpha and 1.0-alpha2 paths; 8 of 8 again once the upgrade script carries it. The changelog entry that this branch used to carry has moved to the changelog branch. Both edited the same `### Fixed` section from different bases, so whichever merged first left the other conflicting, while GitHub reported both mergeable because it compares each against main rather than against the other. Nothing executes differently. Historical scripts and the alpha/alpha2 fixtures are faithful snapshots of what shipped and are left alone. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01KL9BxvtjERL34H1XV8BND2 --- pgcolumnar--1.0-alpha2--1.0-alpha3.sql | 3 +++ pgcolumnar--1.0-alpha3.sql | 2 +- src/columnar_vacuum.c | 3 ++- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/pgcolumnar--1.0-alpha2--1.0-alpha3.sql b/pgcolumnar--1.0-alpha2--1.0-alpha3.sql index 4f80f4b..9b50bf8 100644 --- a/pgcolumnar--1.0-alpha2--1.0-alpha3.sql +++ b/pgcolumnar--1.0-alpha2--1.0-alpha3.sql @@ -293,3 +293,6 @@ $sort_status$; COMMENT ON FUNCTION pgcolumnar.sort_status(regclass) IS 'how much of an ordered columnar table is still in its ordered run, and by what kind of ordering (#301, #761)'; + +COMMENT ON FUNCTION pgcolumnar.vacuum_sorted(regclass, name[]) + IS 'compact a columnar table, storing rows sorted ascending (NULLS LAST) on the given columns. With no columns, applies the table''s declared sort_by key from set_options (#288), like a bare CLUSTER re-applying a remembered index; errors if none is declared. Supports any btree-orderable column including text and numeric, unlike Z-order cluster(), which takes integer, date/time, boolean and floating-point columns only. One-shot: not auto-maintained.'; diff --git a/pgcolumnar--1.0-alpha3.sql b/pgcolumnar--1.0-alpha3.sql index b7355bc..56596d8 100644 --- a/pgcolumnar--1.0-alpha3.sql +++ b/pgcolumnar--1.0-alpha3.sql @@ -895,7 +895,7 @@ CREATE FUNCTION pgcolumnar.vacuum_sorted( AS 'MODULE_PATHNAME', 'pgcolumnar_vacuum_sorted'; COMMENT ON FUNCTION pgcolumnar.vacuum_sorted(regclass, name[]) - IS 'compact a columnar table, storing rows sorted ascending (NULLS LAST) on the given columns. With no columns, applies the table''s declared sort_by key from set_options (#288), like a bare CLUSTER re-applying a remembered index; errors if none is declared. Supports any btree-orderable column including text (unlike the numeric-only Z-order cluster()). One-shot: not auto-maintained.'; + IS 'compact a columnar table, storing rows sorted ascending (NULLS LAST) on the given columns. With no columns, applies the table''s declared sort_by key from set_options (#288), like a bare CLUSTER re-applying a remembered index; errors if none is declared. Supports any btree-orderable column including text and numeric, unlike Z-order cluster(), which takes integer, date/time, boolean and floating-point columns only. One-shot: not auto-maintained.'; /* * One-argument form: apply the declared sort_by key (#288). A VARIADIC function diff --git a/src/columnar_vacuum.c b/src/columnar_vacuum.c index 35f5275..b041973 100644 --- a/src/columnar_vacuum.c +++ b/src/columnar_vacuum.c @@ -1740,7 +1740,8 @@ vacuum_sorted_gate_is_noop(Relation rel, int ncols, AttrNumber *atts) * declared sort_by key from pgcolumnar.options (#288), like a bare * "CLUSTER t" re-applying a remembered index; it errors if none is set. * Sorting supports any btree-orderable column, text included; the Z-order - * cluster() path is numeric-only. + * cluster() path takes integer, date/time, boolean and floating-point + * columns. */ Datum pgcolumnar_vacuum_sorted(PG_FUNCTION_ARGS)