cursor_tuple_fraction

Definition PG 18 manual

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.

How it works

cursor_tuple_fraction tells the planner what fraction of a cursor's result is expected to be fetched. Lower fractions give more weight to startup cost; 1.0 plans like an ordinary query that consumes the full result.

The estimate can change join order and access paths by preferring a fast first row even when total execution would be slower. It does not stop FETCH after that fraction and is not a row limit.

It is consulted at planning time for cursor plans. Application behavior matters: cursors used for pagination, early exit, or full export have very different appropriate fractions. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value.

Operational considerations

Treating cursor_tuple_fraction as an executor resource limit rather than a planning assumption or policy.

Testing only one parameter set or one data distribution.

Expecting an already cached plan to be rewritten automatically.

Using a global override to hide stale statistics or fragile SQL structure.

Workload guidance

OLAP: Analytical SQL can make cursor_tuple_fraction more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.

OLTP: Keep cursor_tuple_fraction at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.

SMALL: On a small host, avoid increasing planning search or memory pressure through cursor_tuple_fraction without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override.