Custom Scan

A Custom Scan is a node supplied by an extension through the custom-scan provider API — used by add-ons that implement alternative execution strategies (columnar storage, GPU execution, etc.).

When an installed extension registers a provider and the planner accepts its cheaper path.

Behavior and tuning depend on the extension; consult its documentation. Its presence just means a non-core executor is in play.

An extension's alternative executor

A Custom Scan is a node produced by an extension that registered a custom-scan provider with PostgreSQL. The provider tells the planner what it can do and at what cost; if the planner picks its path, the executor calls back into the extension to actually produce rows.

It's how extensions plug in non-core execution strategies:

• citus uses Custom Scans for distributed planning.
• TimescaleDB uses them to skip chunks and to inject hypertable-aware plans.
• Columnar storage extensions use them to read from columnar formats.
• GPU executors and JIT'd plans appear here too.

What's tunable

The behavior, costs, and tuning of a Custom Scan all belong to its extension. The plan label often includes a hint of which provider produced it ("Custom Scan (ColumnarScan)", "Custom Scan (HypertableExpand)", …). Refer to that extension's documentation to understand the numbers and the levers.

The presence of a Custom Scan just means: a non-core executor is involved. Everything above it (joins, aggregates, sorts) is still PostgreSQL.

When you don't have an extension

If you see a Custom Scan in a plan and you don't recognize the provider, check pg_extension to see what's installed. Sometimes a third-party extension was installed and its planner hook is changing plans you didn't expect.

• Foreign Scan