docs: record that ANALYZE collects no column statistics

[ChronicallyJD]

Third audit finding. Docs-only, because the fix is either large (implement sampling) or harmful (make it loud), and neither belongs in the same change as recording the state.

What I found

static bool
columnar_scan_analyze_next_block(COLUMNAR_ANALYZE_NEXT_BLOCK_ARGS)
{
    return false;
}

static bool
columnar_scan_analyze_next_tuple(COLUMNAR_ANALYZE_NEXT_TUPLE_ARGS)
{
    return false;
}

Both are wired into the AM routine, so ANALYZE on a columnar table samples zero rows and writes nothing to pg_statistic. It reports success.

That makes it the one unsupported operation with no signal. TABLESAMPLE, whose callbacks sit twenty lines further down in the same file, raises through COLUMNAR_UNSUPPORTED. A user running ANALYZE on a columnar table gets the same output they would get on a heap table and no indication that nothing was collected — they would have to query pg_stats and notice it is empty.

Nothing in docs/ mentions it. Every "ANALYZE" in the documentation today is EXPLAIN ANALYZE, which is unrelated.

What is and is not affected

Not affected: the planner's row count. columnar_relation_estimate_size derives *tuples from row-group metadata rather than from pg_class.reltuples, and deliberately so, per its comment. Scan and join cardinality at the top level is sized correctly.

Affected: everything ANALYZE would say about the values — most-common values, histograms, n_distinct, null fraction, average width. Predicates fall back to the planner's defaults, so WHERE col = 'x' is estimated at DEFAULT_EQ_SEL regardless of the actual distribution, and join orders are chosen from default distinct counts. For an extension whose documentation recommends indexes and index-only scans for selective access, those are exactly the estimates that decide whether the index gets used.

One thing I could not check without running a server: whether ANALYZE also writes pg_class.reltuples = 0 as a side effect of sampling nothing. The planner would not care, since it uses the callback above, but autovacuum's thresholds read reltuples directly, and a zero there would make the analyze threshold trivially reachable on every table. Worth confirming before deciding how urgent the real fix is — if it does, autoanalyze may be running far more often than intended on every columnar table in a cluster.

Why docs rather than a behaviour change

• Erroring like TABLESAMPLE would break autovacuum, which calls analyze on its own schedule.
• A WARNING would be emitted on every autoanalyze cycle, into the server log, forever.
• Implementing sampling is the real fix, and it is not small: the sample callbacks would need to map PostgreSQL's block sampler onto row groups, and it wants its own tests against a heap oracle.

So this PR only records the state. If you would rather have the implementation than the paragraph, say so and I will close it.

Verification

Read-only: the two callbacks and their registration in the AM routine, the TABLESAMPLE contrast, columnar_relation_estimate_size's independence from ANALYZE, and that no existing doc covers it. Zero em-dashes in the added prose, per the project convention.

Not built, not gated — no PostgreSQL server headers in my environment. Docs-only, so the risk is confined to whether the paragraph is accurate rather than whether it compiles.

🤖 Generated with Claude Code

[jdatcmd]

Verified, and the framing is right: this belongs in the docs rather than being fixed in the same change.

Checked each supporting claim rather than the headline:

• Both columnar_scan_analyze_next_block and columnar_scan_analyze_next_tuple are return false, and both are wired into the AM routine. ANALYZE reports success and writes nothing.
• The row count really is unaffected: columnar_relation_estimate_size computes *tuples by summing rowCount across row-group metadata, not from pg_class.reltuples. So the distinction the text draws between accurate cardinality and absent column statistics is exact, not approximate.
• TABLESAMPLE does raise, through COLUMNAR_UNSUPPORTED, twenty lines below the analyze callbacks. The contrast you draw is real and is the sharpest part of the finding: the one unsupported operation that stays silent.

The advice at the end is the right shape too, since it tells a user what to do (check EXPLAIN, keep filtered columns in heap) rather than just what is missing.

Approving. Docs only, nothing to gate.

Worth a follow-up issue for the underlying gap, so it does not live only in a limitations entry: sampling for ANALYZE is implementable here (a row-group-aware sampler could feed pg_statistic without a full scan), and it is the sort of thing that quietly costs plan quality on exactly the wide filtered tables this storage is for. Say the word and I will open it.