Parameter · Client Connection Defaults / Statement Behavior
gin_pending_list_limit
Sets the maximum size of the pending list for GIN index.
- Default:
4MB - Type: integer (kB)
- Range: 64kB … max (2147483647)
- Applies: Session (any user)
In plain words
Updating a GIN index (full-text, jsonb, arrays) is expensive, so by default new entries first go to a quick "pending list". When that list grows past this size, it is merged into the main index in one go. A bigger limit means faster inserts but occasional longer pauses and slower searches.
For DBAs and operators
Only for GIN indexes with fastupdate = on (the default). Inserts append to the unsorted pending list; searches must scan the whole list in addition to the index. Once the list exceeds the limit, the inserting backend that crossed it performs the cleanup, so that one INSERT is suddenly slow. Autovacuum (and VACUUM, gin_clean_pending_list()) also flush it.
Tuning:
- Spiky insert latency on a GIN-indexed table: lower the limit, flush more often from autovacuum, or call
SELECT gin_clean_pending_list('idx')regularly. - Bulk loads: a larger limit (or disabling
fastupdateduring the load and then creating the index) is faster.
Override per index: ALTER INDEX idx SET (gin_pending_list_limit = 1024) (in kB). Inspect the list with pageinspect's gin_metapage_info() (n_pending_pages, n_pending_tuples).
How to change it
Any user can change it for their session with SET.