Cookbook recipe

Heap vs index: what is stored where

Applies to PostgreSQL 13–17 Last reviewed May 2026 Grounded in source

What This Is

A production experience capsule based on real incident patterns.

Why It Matters

Builds production judgment under pressure.

Next Step

Run the decision point → · Enter full simulator →

Estimated investigation4 min

Scenario

People say "the heap" and "the index" as if they are different things — because they are. Knowing the split clarifies how lookups work. Diagnose it Compare heap and index sizes: SELECT pg_size_pretty(pg_relation_size('orders')) AS heap, pg_size_pretty(pg_indexes_size('orders'))…

Investigation Path

People say “the heap” and “the index” as if they are different things — because they are. Knowing the split clarifies how lookups work.

Diagnose it

Compare heap and index sizes:

SELECT pg_size_pretty(pg_relation_size('orders')) AS heap,
       pg_size_pretty(pg_indexes_size('orders')) AS indexes;

Why it happens

The heap holds the actual row data, unordered. An index holds sorted keys plus pointers (TIDs) to heap rows. A typical index scan finds the key in the index, then fetches the row from the heap.

This is a Pro lesson

Get every Learning Pathway and cookbook recipe — grounded in PostgreSQL source code, with diagnostics, fixes, and prevention for each topic.

Continue this lesson to learn:

  • How to fix it
  • Prevent it next time
  • Related & next steps
  • All 36 Learning Pathway lessons
  • 170+ cookbook recipes
  • Source-grounded diagnostics & fixes
Unlock everything — $24.99/month $199/year — save 35%

Secure checkout Cancel anytime Source-grounded

Career Impact

This scenario builds production judgment and operational confidence under pressure.

Open Career Dashboard →

Keep going

Related & next steps

More like this

Kill a runaway query or connection safely pg_upgrade Fails: Unclean Shutdown or Catalog Incompatibility How TOAST stores big values Character encoding and collation basics Checkpoints Too Frequent

Concepts on this page

Index Heap
Browse the cookbook Step-by-step recipes Follow a pathway Learn it in order Open the glossary Every concept, plainly
Was this helpful?

← All cookbook recipes