Indexes · XB Field Notes

Partial uniqueness protects the active subset

Fri, 15 Oct 2027 00:00:00 +0000

A partial index stores entries only for rows satisfying its predicate. This can reduce index size when the useful subset is small, but it can also enforce a rule that applies only to that subset. For example, a seat may have many historical reservations while allowing at most one active reservation. A partial unique index expresses that rule at the database boundary.

Membership follows the predicate

CREATE INDEX ... WHERE active includes rows for which active evaluates to true. False and null do not satisfy the predicate. Whether null should be allowed is a separate schema decision; the experiment makes active non-null so each reservation is explicitly active or inactive. The indexed key need not be the same column used by the predicate.

Membership changes with ordinary writes. An inactive row becoming active must enter the index and pass its checks; an active row becoming inactive leaves the active subset. This is not an immutable archive boundary. Predicate evaluation and changing membership still cost work, so a smaller index does not mean every update is free or automatically faster.

Uniqueness can apply to a subset

A unique index on seat WHERE active rejects two active rows for the same seat, while permitting any number of inactive historical rows. The index enforces that rule even if no SELECT ever chooses it. Query acceleration and integrity enforcement are different reasons to retain an index, so usage counters alone cannot justify deleting this one.

An application-level “check first, insert later” is weaker because another transaction can insert between the check and the write. A unique index coordinates conflicting writes in PostgreSQL; the loser must handle a uniqueness error or another chosen conflict policy. The fixture exercises rejection sequentially, while concurrency behavior remains part of the database’s constraint contract rather than a claim about an application booking workflow.

Plan queries with the same boundary

To use a partial index as an access path, the planner must recognize that the query’s conditions imply the index predicate. Merely querying the seat does not prove the caller wants only active rows. A query that explicitly asks for active reservations can qualify, although a tiny table may still be cheaper to scan. A logically similar expression is useful only if the planner can establish the implication.

Do not create hundreds of overlapping partial indexes to simulate partitioning. Planning and maintenance costs grow, and the optimizer does not automatically understand them as one coordinated partition scheme. Choose a predicate from a stable workload or integrity requirement, then verify the actual query and transition behavior.

When it breaks

Forgetting the predicate in a query can return old reservations alongside the current one, even though active uniqueness is enforced perfectly. Conversely, treating the index as globally unique can reject valid history in application logic. Document whether the rule concerns all rows or only the current subset, and test both populations.

A failed reactivation is another important boundary. Changing an old inactive reservation back to active can conflict with the current holder. The application must keep the old row inactive when that update fails and report the conflict, not silently replace the active booking. Bulk imports and status migrations need the same checks as ordinary insertion.

Predicate membership and uniqueness transitions are separate from planner selection. Historical sequential SQL evidence does not establish concurrent bookings.

Check it quickly

Save this block as partial-unique.sql and run psql -X -v ON_ERROR_STOP=1 -f partial-unique.sql in a disposable PostgreSQL 18 database. It creates a temporary reservation table, so no real seat inventory is touched.

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE reservations (id integer PRIMARY KEY, seat text NOT NULL, active boolean NOT NULL);
CREATE UNIQUE INDEX one_active_seat ON reservations (seat) WHERE active;
INSERT INTO reservations VALUES (1,'A1',true),(2,'A1',false),(3,'A1',false);
DO $$ BEGIN
 INSERT INTO reservations VALUES (4,'A1',true);
 RAISE EXCEPTION 'two active reservations accepted';
EXCEPTION WHEN unique_violation THEN RAISE NOTICE 'active duplicate rejected';
END $$;
UPDATE reservations SET active=false WHERE id=1;
INSERT INTO reservations VALUES (4,'A1',true);
DO $$ BEGIN
 UPDATE reservations SET active=true WHERE id=2;
 RAISE EXCEPTION 'reactivation bypassed uniqueness';
EXCEPTION WHEN unique_violation THEN RAISE NOTICE 'conflicting reactivation rejected';
END $$;
SELECT active,count(*) FROM reservations GROUP BY active ORDER BY active;
SELECT id FROM reservations WHERE active AND seat='A1';
DO $$ BEGIN
 IF (SELECT id FROM reservations WHERE active AND seat='A1') IS DISTINCT FROM 4 THEN
 RAISE EXCEPTION 'wrong active reservation';
 END IF;
 IF (SELECT count(*) FROM reservations WHERE NOT active) <> 3 THEN
 RAISE EXCEPTION 'history was not preserved';
 END IF;
END $$;
ROLLBACK;

The first active duplicate is rejected while two historical duplicates are accepted. Deactivating reservation one releases the seat for reservation four. Reactivating reservation two then fails because four is active. The final counts are three inactive rows and one active row, whose identifier is four. Assertions check both the current holder and retained history.

Retained PostgreSQL 18.6 standalone SQL logs record these checks passing; this source review did not rerun them. That earlier adaptation omitted the psql directive and folded statement whitespace, so client invocation and concurrent bookings remain untested. The exception blocks catch only the expected uniqueness violation; an unexpected success raises a different error and fails the script. Rollback removes the fixture. This verifies subset membership and uniqueness transitions, not payment atomicity, distributed reservations, or the performance of a large historical table.

Sources

PostgreSQL partial indexes, predicate membership and partial uniqueness, checked 2026-10-15.
PostgreSQL CREATE INDEX, unique index enforcement and predicates, checked 2026-10-15.

Covering indexes can avoid heap visits

Thu, 14 Oct 2027 00:00:00 +0000

A covering index contains the values needed by a particular query. PostgreSQL can sometimes return those values through an index-only scan, avoiding heap visits for qualifying rows. The word “sometimes” matters: having the columns is a structural requirement, while visibility information determines whether execution can actually skip the heap. An Index Only Scan label alone does not prove zero table access.

Coverage supplies values; the heap page’s visibility bit governs whether an index-only scan must visit the heap. Writes and eligible vacuum can change that state. Heap visits are not necessarily physical disk reads.

Cover the actual projection

For a lookup by sku that returns price, a B-tree on sku with INCLUDE (price) stores price as payload. The sku key guides the search; the included price does not become another search key or establish an ordering by price. If the index is unique, uniqueness applies to its key columns, not to the included payload.

A later query change can invalidate the coverage assumption. Selecting a description column absent from the index requires another source for that value, usually the heap. Selecting every column casually can therefore turn a carefully covered lookup into a different access pattern. Start from the real predicate and projected columns, including expressions and visibility needs, rather than adding all table columns to a speculative index.

Not every access method can reconstruct complete values for index-only execution. B-tree supports it, while GIN generally stores extracted keys rather than the complete original value and does not support index-only scans. A matching index must support the needed operation as well as contain or reconstruct the requested data. Similar terminology across database engines does not imply identical implementation details.

The visibility map decides heap visits

PostgreSQL needs to know whether a candidate tuple is visible to the query’s MVCC snapshot. Index entries do not carry all the required visibility information. An index-only scan checks the heap page’s all-visible bit in the visibility map; when that bit is set, the value can be returned without fetching the heap tuple.

A write can clear the page’s all-visible status, making later scans visit the heap again even when their plan name remains unchanged. Vacuum can establish all-visible status when the page’s tuples meet the visibility requirements. Long-running transactions and ongoing changes affect that process. It is a page-level property, so an update to one row can influence the visibility check for another row on that page.

When it breaks

The common mistake is declaring success from EXPLAIN’s plan label. Read Heap Fetches and relevant buffers in EXPLAIN ANALYZE, and confirm the actual returned values. A write-heavy table may require frequent heap checks, reducing the read benefit while still paying for duplicated index payload. Repeating VACUUM after every application write is not a substitute for evaluating the workload.

Wide payload columns also consume space and cache, increase maintenance work, and can exceed index tuple limits. Updating an included column must maintain the index and can prevent a heap-only update that might otherwise have been possible. Include only values whose read benefit justifies their write and storage cost; a covering index is not a free materialized copy of the table.

Check it quickly

Save this as covering.sql and run psql -X -v ON_ERROR_STOP=1 -f covering.sql against a disposable PostgreSQL 18 database. Keep psql’s normal autocommit behavior: VACUUM cannot run inside an explicit transaction block. The temporary table remains confined to this session.

\set ON_ERROR_STOP on
CREATE TEMP TABLE products (sku integer, price integer);
INSERT INTO products SELECT g, g*10 FROM generate_series(1,10000) AS g;
CREATE INDEX products_price_lookup ON products (sku) INCLUDE (price);
VACUUM (ANALYZE) products;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
UPDATE products SET price=price+5 WHERE sku=4321;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
VACUUM (ANALYZE) products;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
DO $$ BEGIN
 IF (SELECT price FROM products WHERE sku=4321) IS DISTINCT FROM 43215 THEN
 RAISE EXCEPTION 'covering lookup returned an obsolete price';
 END IF;
END $$;
DROP TABLE products;

The first vacuum makes this quiescent fixture eligible for heap-free reads. The retained PostgreSQL 18.6 report used Index Only Scan in all three plans, with Heap Fetches zero, then two after the price update, then zero after vacuum. The assertion confirms the new price is 43215 rather than an obsolete indexed value. Temporary objects are removed explicitly and also disappear when the session ends.

The exact intermediate count can vary with implementation and page state; its significance is that heap access can occur under the same plan label. Heap Fetches counts heap visits, not necessarily physical disk reads: the pages may already be cached. This is a controlled visibility demonstration, not a guarantee that production vacuum will immediately make every page all-visible. Compare representative reads before and after real update activity when deciding whether coverage pays off.

Sources

PostgreSQL index-only scans, visibility maps and included payload, checked 2026-09-10.
PostgreSQL CREATE INDEX, INCLUDE semantics and index restrictions, checked 2026-09-10.

Full table scans can win on small tables

Thu, 16 Sep 2027 00:00:00 +0000

An index trades storage and write work for a possible reduction in read work. A full scan can win when the table is small or a predicate selects much of it, but neither row count nor selectivity decides alone. Projection, ordering, caching, row width, and available access paths change the comparison. Start with the query’s actual result contract.

Understand the competing work

A B-tree range scan does not descend from the root for every matching index entry. After finding the range, it can advance through adjacent entries. A non-covering path may then need table lookups for missing columns; those lookups can dominate a broad query. A covering index can avoid them, so even a query matching most rows can benefit from an index.

Pages matter, but they are not the only currency. PostgreSQL’s default seq_page_cost and random_page_cost are relative planner estimates, not milliseconds or a charge mechanically applied to every returned row. Caching, correlation, CPU work, bitmap scans, and index-only scans matter too. SQLite stores ordinary table rows in a rowid B-tree; that is a different storage model from PostgreSQL’s heap. Do not transfer a measured ratio between them.

SQLite’s PRAGMA page_count reports the whole database file, including indexes and other objects. It is not the page count of one named table. Likewise, logical page traversal is not a guarantee of contiguous physical disk reads. Compare consistent object scopes and record page size, schema, payload width, and cache conditions alongside row count.

Keep earlier measurements in context

Earlier notes recorded SQLite 3.53 measurements with a 2 MB page cache. For a broad predicate, scan/index times were 0.04/0.05 ms at 1,000 rows, 1.79/6.61 ms at 50,000, and 44.37/531.18 ms at one million. A selective million-row query instead took 0.61 ms through the index versus 17.88 ms scanning. Equal-row narrow/wide fixtures were reported as 12/1,010 pages and 0.02/1.30 ms.

Those are historical observations, not universal thresholds or measurements repeated here. The earlier data generator and complete benchmark environment are unavailable in this review. The exercise below therefore establishes a separate reproducible comparison and prints its runtime version. It does not claim to reproduce the earlier timings, page counts, or automatic planner choices.

When it breaks

A growing tenant can invalidate an old selectivity estimate while every query still returns correct rows. Statistics are one suspect, not proof of the cause: changed parameters, index coverage, cache state, or competing workload can also explain a slower plan. Check estimated versus observed work before forcing a permanent access path.

Fresh statistics do not guarantee a scan for every broad range predicate. SQLite builds differ in optional statistics support, and plan text can change between versions. A SCAN entry can even describe a covering-index scan rather than a table scan. Read the entire plan and compare equivalent query results instead of turning one keyword into a pass/fail rule.

The tenant index lacks payload, so its range path includes table lookups. All three fixture paths must return equal results; no winner is asserted. Historical timings remain unreplicated.

Check it quickly

Save this as scans.py and run python3 scans.py. It uses Python’s SQLite binding, creates its own temporary database, and never opens an existing application database. All three paths must return 2,880,000 for the broad predicate and 3,200 for the selective one. Seven alternating-order warm samples report medians without asserting which path wins.

from pathlib import Path
from tempfile import TemporaryDirectory
from statistics import median
from time import perf_counter
import sqlite3

with TemporaryDirectory(prefix="scan-crossover-") as directory:
 db = sqlite3.connect(Path(directory) / "fixture.db")
 try:
 db.executescript("""CREATE TABLE events(id INTEGER PRIMARY KEY, tenant INTEGER, payload TEXT);
 CREATE INDEX events_tenant ON events(tenant);""")
 db.executemany("INSERT INTO events VALUES(?,?,?)",
 ((i, i % 1000, "x" * 64) for i in range(50000)))
 db.commit()
 db.execute("ANALYZE")
 print("SQLite", sqlite3.sqlite_version)
 print("database pages", db.execute("PRAGMA page_count").fetchone()[0],
 "page size", db.execute("PRAGMA page_size").fetchone()[0])
 for predicate, expected in [("tenant < 900", 2880000), ("tenant = 7", 3200)]:
 base = "SELECT sum(length(payload)) FROM events {} WHERE " + predicate
 paths = {"chosen": "", "scan": "NOT INDEXED", "index": "INDEXED BY events_tenant"}
 queries = {name: base.format(clause) for name, clause in paths.items()}
 samples = {name: [] for name in queries}
 for name, query in queries.items():
 assert db.execute(query).fetchone()[0] == expected
 print(predicate, name, db.execute("EXPLAIN QUERY PLAN " + query).fetchall())
 for repeat in range(7):
 names = list(queries) if repeat % 2 == 0 else list(reversed(queries))
 for name in names:
 start = perf_counter()
 result = db.execute(queries[name]).fetchone()[0]
 samples[name].append((perf_counter() - start) * 1000)
 assert result == expected
 print("warm median ms", {k: round(median(v), 3) for k, v in samples.items()})
 old = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 db.execute("UPDATE events SET tenant=5")
 db.commit()
 stale = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 assert stale == old
 db.execute("ANALYZE")
 fresh = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 assert fresh.split()[:2] == ["50000", "50000"] and fresh != old
 print("statistics before/stale/fresh", old, stale, fresh)
 try:
 db.execute("SELECT * FROM events INDEXED BY absent_index")
 except sqlite3.OperationalError as error:
 assert "no such index" in str(error), error
 else:
 raise AssertionError("missing required index was silently ignored")
 print("missing INDEXED BY target rejected")
 finally:
 db.close()

The payload expression requires data absent from the tenant index, making this a non-covering comparison. INDEXED BY requires the named index; it is not merely a suggestion. The missing-index negative control confirms that requirement. NOT INDEXED disables secondary indexes here; elsewhere it does not prohibit a rowid lookup. Keep these controls in diagnosis, rather than copying them into application queries without justification.

After the data changes to one tenant, sqlite_stat1 remains stale until ANALYZE. The refreshed entry reports 50,000 rows sharing that key. This tests statistics maintenance, not a guaranteed plan flip. In production, follow the SQLite version’s recommended PRAGMA optimize workflow and schedule expensive analysis appropriately.

The fixture warms data and measures one process without competing writers. It cannot establish cold-storage latency, production concurrency, or the best long-term index budget. Retain representative distributions and query projections in performance tests, and repeat them as the table grows; an acceptable scan today can become expensive without any correctness failure.

Sources

SQLite query planning, range traversal, table lookups, and covering indexes, checked 2026-10-15.
SQLite EXPLAIN QUERY PLAN, SCAN/SEARCH meaning and unstable presentation, checked 2026-10-15.
SQLite PRAGMA page_count, database-wide page count, checked 2026-10-15.
SQLite ANALYZE, statistics and recommended optimize workflow, checked 2026-10-15.
SQLite INDEXED BY, required indexes and NOT INDEXED scope, checked 2026-10-15.
PostgreSQL planner cost constants, relative costs and cache assumptions, checked 2026-10-15.
PostgreSQL using EXPLAIN, row estimates, bitmap scans, and index-only scans, checked 2026-10-15.

Composite indexes match multi-column queries

Wed, 15 Sep 2027 00:00:00 +0000

A composite B-tree index orders tuples by its first key, then by the next key within each first-key group. This structure can make a tenant-specific time range cheap to locate. The useful rule is about how much index space a predicate narrows, not a prohibition against mentioning later columns or writing WHERE conditions in a different textual order.

A local excerpt of tenant-first key order, followed by a possible later-key search strategy. Repeated searches are cost-dependent; the diagram is not a plan trace, and output ordering still depends on the chosen path.

Order the keys, not the SQL clauses

For an index on (tenant, happened), equality on tenant and a range on happened describe a compact portion of the tree. PostgreSQL can search that range rather than inspecting all tenants. Writing the time condition before the tenant condition in SQL does not change the logical conjunction or the index’s key order. The schema’s column order and the query’s presentation order are different things.

Leading equality conditions and the first non-equality key generally determine the range that must be scanned. Conditions on later keys can still be checked within the index, saving heap visits even when they do not further shrink a simple contiguous range. Reversing key columns changes these opportunities; it does not make an index universally unusable.

Later keys can still help

PostgreSQL 18 can use B-tree skip scans when repeated searches over missing leading-key values are cheaper than reading most of the index. With only a few tenants, a predicate on happened alone can search within each tenant group. With many distinct leading values, that strategy may be too expensive, and the planner can prefer a sequential scan or another index.

Even without a profitable skip scan, a composite index can sometimes be scanned for a condition involving a later key. The question is cost, coverage, and selectivity, not whether such SQL is legal or whether the index must be ignored. Do not use the shorthand “leftmost prefix” as an absolute claim that contradicts the target engine’s actual access methods.

Include ordering and the workload

Fixing the tenant key can make the following happened key useful for ordered results. Across several tenants, however, the index groups by tenant first; it does not provide one globally time-sorted stream. A bitmap scan also loses index ordering and may need a separate sort. Look at the complete plan instead of inferring final order from an index declaration.

Equality-first and range-next is a useful starting point for one query shape, but there is no universal “most selective column first” recipe. Shared prefixes, joins, sort direction, LIMIT, parameter distributions, and write costs all affect the choice. Compare actual recurring queries, then keep the smallest useful set of indexes. Redundant wide indexes consume cache and maintenance work even when nobody benefits from them.

When it breaks

A team may build (tenant, happened) for per-tenant queries, then add a global timeline and assume it is equally efficient. The timeline’s ordering and selectivity differ. Another regression comes from testing one tiny tenant while another owns most rows: the same parameterized SQL can have very different costs. Statistics and representative values matter more than a screenshot of one favorable plan.

Incorrect rules also cause unnecessary index churn. Adding one index per suffix because “the existing index cannot be used” can duplicate useful storage. Conversely, assuming skip scan always rescues a missing prefix can hide a costly path. Measure the chosen plan, actual rows, buffers, and sort work before changing the schema.

Check it quickly

Save this as composite.sql and run psql -X -v ON_ERROR_STOP=1 -f composite.sql on a disposable PostgreSQL 18 database. The temporary fixture contains four tenant values and twenty thousand ordered event numbers.

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE events (tenant integer, happened integer, body text);
INSERT INTO events SELECT g % 4, g, repeat('x',40) FROM generate_series(1,20000) AS g;
CREATE INDEX events_tenant_time ON events (tenant, happened);
ANALYZE events;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT happened FROM events WHERE tenant=2 AND happened BETWEEN 100 AND 120
ORDER BY happened;
SELECT array_agg(happened ORDER BY happened) AS matching_times
FROM events WHERE happened BETWEEN 100 AND 120 AND tenant=2;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT tenant FROM events WHERE happened=12346;
DO $$ BEGIN
 IF (SELECT array_agg(happened ORDER BY happened) FROM events
 WHERE happened BETWEEN 100 AND 120 AND tenant=2)
 IS DISTINCT FROM ARRAY[102,106,110,114,118] THEN
 RAISE EXCEPTION 'wrong composite range';
 END IF;
 IF (SELECT tenant FROM events WHERE happened=12346) IS DISTINCT FROM 2 THEN
 RAISE EXCEPTION 'suffix predicate lost the row';
 END IF;
END $$;
ROLLBACK;

The tenant-range query returns exactly 102,106,110,114,118, including when the WHERE conditions are written in the opposite order. The retained PostgreSQL 18.6 report used a bitmap index scan followed by a sort. The suffix-only lookup returned tenant two through an index-only scan with repeated index searches, demonstrating a usable path without tenant equality.

Plan names, buffer counts, and search counts are observations for this dataset, not guaranteed outputs across configurations. The assertions verify result semantics, and rollback removes all objects. Repeat the measurement with more leading-key values to assess whether the suffix path remains worthwhile for a real workload.

Sources

PostgreSQL multicolumn indexes, leading constraints and skip scans, checked 2026-09-10.
PostgreSQL indexes and ORDER BY, ordered scans and sort choices, checked 2026-09-10.

Prepared plans must prove a partial-index predicate

Sat, 17 Oct 2026 00:00:00 +0000

A queue with a hundred ready jobs and thousands of completed jobs can benefit from an index containing only ready work. PostgreSQL calls this a partial index: its predicate determines which table rows have entries. The benefit depends on the actual query population and write pattern, not simply on making every index smaller.

Eligibility requires the query to imply the predicate. Cost and visibility still affect the chosen access path.

When it breaks

The direction of implication matters. The query conditions must imply the index predicate, so every row the query might need is represented. A ready-only index cannot answer an unrestricted query about all jobs. Merely having compatible-looking conditions is insufficient, and PostgreSQL does not prove every mathematical equivalence. A predicate written close to the application’s filter is easier for the planner and reviewers to recognize.

Planning also determines what values are known. A custom prepared plan can use the supplied state value to choose a partial index. A generic plan must be valid for every possible parameter value; it cannot assume that a state parameter always means ready. This explains why testing a literal query can look good while an application’s prepared query uses a different access path.

Check it quickly

Run the blocks in one fresh psql -X -v ON_ERROR_STOP=1 session on a disposable PostgreSQL 18 database. The fixture has no full-table index, making the eligible access paths easy to inspect. Create ten thousand jobs, of which exactly one hundred are ready:

CREATE SCHEMA partial_demo;
CREATE TABLE partial_demo.jobs (id integer,state text);
INSERT INTO partial_demo.jobs
SELECT g,CASE WHEN g%100=0 THEN 'ready' ELSE 'done' END
FROM generate_series(1,10000) AS g;
CREATE INDEX ready_jobs ON partial_demo.jobs(id) WHERE state='ready';
VACUUM (ANALYZE) partial_demo.jobs;
SELECT state,count(*) FROM partial_demo.jobs GROUP BY state ORDER BY state;

The grouped counts are 9,900 done and 100 ready. The indexed column is the job identifier, while the predicate uses state; those columns need not be the same. Inspect a literal query:

EXPLAIN (ANALYZE,COSTS OFF,TIMING OFF,SUMMARY OFF,FORMAT JSON)
SELECT id FROM partial_demo.jobs WHERE state='ready' ORDER BY id LIMIT 5;

The tested plan contains an Index Only Scan using ready_jobs beneath Limit, returning five rows. Vacuum established the visibility information needed to avoid heap fetches in this fixture. Partial indexing alone does not promise an index-only scan: selected columns and visibility still matter. The important eligibility evidence is the index name and correct result.

Prepare the same request with a state parameter and force a custom plan for comparison:

PREPARE next_jobs(text) AS
SELECT id FROM partial_demo.jobs WHERE state=$1 ORDER BY id LIMIT 5;
SET plan_cache_mode=force_custom_plan;

EXPLAIN (ANALYZE,COSTS OFF,TIMING OFF,SUMMARY OFF,FORMAT JSON)
EXECUTE next_jobs('ready');

This plan also uses ready_jobs, because the supplied ready value is available when planning. Now request a generic plan for the same prepared statement:

SET plan_cache_mode=force_generic_plan;

EXPLAIN (ANALYZE,COSTS OFF,TIMING OFF,SUMMARY OFF,FORMAT JSON)
EXECUTE next_jobs('ready');

The generic plan scans the table, filters out 9,900 rows, and sorts the matching identifiers before taking five. Its state expression remains a parameter, so the ready-only index cannot cover every possible execution. These forced modes isolate the distinction; they are diagnostic controls, not a recommendation to force one mode globally.

Execute both parameter values, then move one ready job across the predicate boundary:

EXECUTE next_jobs('ready');
EXECUTE next_jobs('done');
DEALLOCATE next_jobs;
RESET plan_cache_mode;
UPDATE partial_demo.jobs SET state='done' WHERE id=100;
SELECT id FROM partial_demo.jobs WHERE state='ready' ORDER BY id LIMIT 5;
SELECT count(*) FROM partial_demo.jobs WHERE state='ready';
DO $$ BEGIN
 IF (SELECT array_agg(id ORDER BY id) FROM
 (SELECT id FROM partial_demo.jobs WHERE state='ready' ORDER BY id LIMIT 5) AS q)
 IS DISTINCT FROM ARRAY[200,300,400,500,600] THEN
 RAISE EXCEPTION 'partial-index membership result mismatch';
 END IF;
END $$;
DROP SCHEMA partial_demo CASCADE;

The first request returns identifiers 100, 200, 300, 400, and 500. The done request returns one through five. After job 100 becomes done, the first five ready identifiers are 200 through 600 in steps of one hundred, and 99 ready jobs remain. The assertion checks that maintenance follows the updated predicate membership. Removing the prepared statement and schema leaves no experimental data behind.

Evaluate the whole workload

Updates that enter or leave the subset change index membership. Even updates outside it still perform ordinary table work; a partial index does not eliminate all write cost. Measure index size, query plans, and maintenance under representative state transitions. If most jobs become ready, the expected advantage may disappear, and a sequential scan can be the right choice.

A partial unique index enforces uniqueness only among rows satisfying its predicate. Rows outside that subset remain unconstrained by that index, which can be useful for historical records but is wrong for a global identifier rule. Also avoid predicates based on a moving current time: index expressions and predicates require immutable functions, and yesterday’s membership would not automatically change as the clock advances. Prefer an explicitly maintained business state when that state defines the real query contract.

Sources

PostgreSQL 18 partial indexes, predicate implication and subset uniqueness, checked 2026-10-15.
PostgreSQL 18 CREATE INDEX, index predicates and immutable-expression requirements, checked 2026-10-15.
PostgreSQL 18 PREPARE, generic and custom prepared plans and their controls, checked 2026-10-15.