From 6f6cfeaed97fb2f1c581c7492e205930a0ba2881 Mon Sep 17 00:00:00 2001 From: "Joshua D. Drake" Date: Fri, 7 Aug 2026 16:27:43 -0600 Subject: [PATCH] docs: say which document to believe when the spec and the code disagree Promised on #492 and owed. That review corrected a line I had taken from the spec (a vector is a fixed 1024 values) which the shipped code does not implement, and the root of it is that the ownership table hands the spec "what the format and the interface ARE" without saying what to do when the code disagrees. Two known instances, both verified rather than recalled: the spec says a vector is a fixed 1024 values; the code sizes it by pgcolumnar.chunk_group_row_limit, default 10000 the spec says the row-group limit is 122880, a multiple of the vector length (section 4, line 77); the code ships stripe_row_limit at 150000 Neither is a defect and neither announces itself. The first is the sharper trap: 1024 is not merely aspirational, it is written into the native storage catalog row as vector_length and then never read back. Checked across src/, sql/ and the extension script, the only occurrences are the column definition, the attribute number, and the INSERT that writes it. A constant that is recorded and never consulted looks exactly like one that is enforced, which is how a reader of either the spec or the catalog reaches a number the scan does not use. So: read the spec for intent and the code for behaviour, and size a fixture from the setting rather than from the spec. That last sentence is the operational part. Someone building a fixture for vector-level skipping in 1024-row units gets one vector per row group at the default, sees Vectors Skipped: 0, and concludes the mechanism is broken. Co-Authored-By: Claude Opus 5 (1M context) --- CONTEXT.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/CONTEXT.md b/CONTEXT.md index cf4d231..bada053 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -16,6 +16,24 @@ question: This file owns the words. +**Where the spec and the shipped defaults disagree, the defaults are what you +will observe.** The spec describes the native format as designed, and in two +known places the code has not moved to meet it. Neither is a defect, and neither +is going to announce itself: + +| the spec says | the code ships | +| --- | --- | +| a vector is a fixed 1024 values | a vector holds up to `pgcolumnar.chunk_group_row_limit` rows, default 10000 | +| the row-group limit is 122880 rows, a multiple of the vector length | `pgcolumnar.stripe_row_limit`, default 150000 | + +The first is the sharper trap, because 1024 is not merely aspirational: it is +written into the native storage catalog row as `vector_length` and then never +read back by anything. A constant that is recorded and never consulted looks +exactly like a constant that is enforced. + +Read the spec for intent and the code for behaviour. Where a fixture depends on +one of these numbers, take it from the setting, not from the spec. + There is also a `HANDOFF.md`, the running continuity record: what has happened, what is in flight, and what to pick up. **It is deliberately not in the repository.** It is excluded per clone through `.git/info/exclude`, so a fresh