Skip to content

Document five settings and correct two false claims (1.0-alpha docs pass) - #371

Merged
jdatcmd merged 1 commit into
commandprompt:mainfrom
ChronicallyJD:docs/alpha-config-gaps
Aug 4, 2026
Merged

Document five settings and correct two false claims (1.0-alpha docs pass)#371
jdatcmd merged 1 commit into
commandprompt:mainfrom
ChronicallyJD:docs/alpha-config-gaps

Conversation

@ChronicallyJD

Copy link
Copy Markdown
Collaborator

What

The docs accuracy pass from #367. Two separate problems: settings that exist and are
not documented, and documented claims that are not true.

Every registered GUC is now documented

Five were missing from docs/configuration.md. Four are user-facing and land in
Scan and execution:

  • pgcolumnar.enable_ungrouped_vector_agg
  • pgcolumnar.enable_parallel_vector_agg
  • pgcolumnar.enable_column_projection
  • pgcolumnar.enable_index_fetch_penalty

The fifth, pgcolumnar.bulk_parallel_writer, is internal — set by
pgcolumnar.parallel_copy workers and marked GUC_NOT_IN_SAMPLE. It gets its own
short Internal settings section rather than a row among the tuning knobs, because
it appears in pg_settings and a reader who finds it there deserves an answer rather
than silence.

Checked mechanically rather than by eye:

$ comm -23 <registered GUCs> <GUCs named in configuration.md>
(empty)

Two claims in limitations.md are wrong

"ANALYZE samples the rows through the fetch path and not by block." It does not.
columnar_scan_analyze_next_tuple reads with a reader restricted to one row group.
Measured with an instrumented build (an elog at the top of columnar_fetch_row,
PG18 assert, statement-marked log):

fetch_row calls during ANALYZE:              0
fetch_row calls during control point query:  2

The control is an indexed point query on the same table, so the probe is live and the
zero is real. The sentence is replaced with what is true and still explains the cost:
the sampler offers every row of every block it visits, so the cost follows rows
offered rather than rows kept.

"The cost therefore no longer increases with the width of the table." It does, in
two ways that are easy to meet at once, and this is the sharp edge jdatcmd asked to
have documented rather than left silent (#367):

Measured on ten text columns, same rows and same plan: 975 ms on the first
column against 194,798 ms on the tenth.

Note this is documented as current behaviour. #368 fixes the cost model so the
planner stops walking into it, which is a different thing from the fetch itself
becoming cheap — the fetch still decodes the prefix.

Style

test/ste_check.py passes on every user-facing document, which is what
docs_style.sh gates on. The measured sentences needed splitting to stay inside the
25-word STE limit; that is a real constraint on how these paragraphs read and I have
kept the numbers rather than the prose where they conflicted.

🤖 Generated with Claude Code

Part of the 1.0-alpha docs accuracy pass (commandprompt#367).

Every registered GUC is now in docs/configuration.md. Five were not:
enable_ungrouped_vector_agg, enable_parallel_vector_agg, enable_column_projection
and enable_index_fetch_penalty are user-facing and are documented as such;
bulk_parallel_writer is internal, is marked GUC_NOT_IN_SAMPLE, and is recorded in
its own section because it appears in pg_settings and a reader who finds it there
deserves an answer.

Two claims in limitations.md are wrong and are corrected:

ANALYZE does not sample through the fetch-by-row-number path. It reads with a
reader restricted to one row group. Measured with an instrumented build: zero
calls into columnar_fetch_row during ANALYZE, against two for a control point
query on the same table (commandprompt#359).

Fetch cost does increase with the width of the table, where the document said it
no longer does. An index fetch decodes the attribute prefix up to the highest
column the query reads, not the columns it reads (commandprompt#363), and columns that exceed
the fetch cache size limit are decoded again per fetch (commandprompt#359, commandprompt#364). Measured on
ten text columns, same rows and same plan: 975 ms on the first column against
194,798 ms on the tenth.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

@jdatcmd jdatcmd left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved

Docs-only, CI green (which runs docs_style over docs/*.md in full), and it
fixes the two things that actually mattered for an alpha.

The limitations.md correction is the important half. The old text said a fetch
"decodes only the columns that the executor asks for", which #363 disproves: it
decodes the prefix up to the highest-numbered column referenced. That sentence was
not vague, it was wrong, and it was the sentence a user would have relied on when
laying out a wide table. Replacing it with both causes and the 975 ms / 194,798 ms
measurement is the right level of specificity.

Documenting enable_column_projection and enable_index_fetch_penalty closes a
real gap
, since both are on by default. #372 covers the same two in the changelog,
so a reader arriving from either direction now finds them.

The bulk_parallel_writer entry is a good call. A GUC_NOT_IN_SAMPLE setting still
shows up in pg_settings, and "leave it alone" plus the reason it is safe to touch
is more useful than omitting it and letting someone guess.

One trivial note, not worth a round trip: the enable_index_fetch_penalty row says
"restore the pre-1.0-alpha planner behaviour" while VERSION still reads 1.0-dev
and nothing is cut yet. It reads fine once the alpha lands, which it will before
this text is user-visible. I will make sure the version cut does not contradict it.

Merging.

@jdatcmd
jdatcmd merged commit a2fe001 into commandprompt:main Aug 4, 2026
11 checks passed
@jdatcmd jdatcmd mentioned this pull request Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants