gin_pending_list_limit

Definition PG 18 manual

Sets the maximum size of a GIN index's pending list, which is used when fastupdate is enabled. If the list grows larger than this maximum size, it is cleaned up by moving the entries in it to the index's main GIN data structure in bulk. If this value is specified without units, it is taken as kilobytes. The default is four megabytes (4MB). This setting can be overridden for individual GIN indexes by changing index storage parameters. See Section 65.4.4.1 and Section 65.4.5 for more information.

How it works

gin_pending_list_limit sets the maximum size of the pending list for GIN index. With a GIN index's fastupdate enabled, crossing this limit triggers bulk migration from the pending list into the main index; per-index storage parameters can override it.

gin_pending_list_limit is a USER-context setting. An authorized role can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.

GIN behavior also depends on per-index storage parameters, work or maintenance memory, autovacuum, and the shape of indexed values and predicates.

Operational considerations

Changing gin_pending_list_limit in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.

Applying a cluster-wide GIN value to fix one exceptional index instead of using its storage parameters.

Ignoring cleanup latency, I/O bursts, autovacuum interaction, or result completeness while tuning.

Changing gin_pending_list_limit globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: For batch loads or broad searches, test gin_pending_list_limit against ingestion latency, cleanup spikes, result completeness, and maintenance windows.

OLTP: Change gin_pending_list_limit only after measuring the affected GIN maintenance or search path. Prefer an index-level override when one index, rather than the whole cluster, is exceptional.

SMALL: Do not raise gin_pending_list_limit merely because the default is reached; bound memory and I/O bursts, and keep exact-query semantics unless approximation is explicitly acceptable.