Sets the planner’s estimate of the fraction of a cursor’s rows that will be retrieved.
At a glance
| Property | Value |
|---|---|
| Parameter | cursor_tuple_fraction |
| Category | Query Planning |
| Default | 0.1 |
| Value type | floating point |
| Change scope | Per-session (SET) |
| Available in | PostgreSQL 12, 13, 14, 15, 16, 17, 18, 19 (added in 12) |
What it does
Sets the planner’s estimate of the fraction of a cursor’s rows that will be retrieved. The default is 0.1. Smaller values of this setting bias the planner towards using “fast start” plans for cursors, which will retrieve the first few rows quickly while perhaps taking a long time to fetch all rows. Larger values put more emphasis on the total estimated time. At the maximum setting of 1.0, cursors are planned exactly like regular queries, considering only the total estimated time and not how soon the first rows might be delivered.
(Description quoted from the official PostgreSQL documentation.)
How to apply a change
Can be set per session with SET, per role/database with ALTER ROLE/DATABASE ... SET, or globally in postgresql.conf.
Inspect the current value and source with SHOW cursor_tuple_fraction; or SELECT name, setting, unit, context, source FROM pg_settings WHERE name = 'cursor_tuple_fraction';.
Tuning guidance
Lower it toward 0.01-0.1 when cursors fetch only the first few rows and you want fast-start plans; raise it toward 1.0 when cursors are typically drained to completion.