--- title: Configuration Reference description: Runtime settings and per-index options for ParadeDB and pg_search canonical: https://www.paradedb.com/docs/reference/configuration --- ParadeDB exposes runtime configuration through Postgres settings, also known as GUCs. Most settings can be changed per session: ```sql SHOW paradedb.enable_custom_scan; SET paradedb.enable_custom_scan = off; RESET paradedb.enable_custom_scan; ``` For persistent configuration, use normal Postgres mechanisms such as `ALTER DATABASE`, `ALTER ROLE`, or `ALTER SYSTEM`. ```sql ALTER DATABASE app SET paradedb.max_topk_chunk_size = 200000; ALTER ROLE app_user SET paradedb.vector_cluster_max_probe = 500; ``` Planner and execution settings can change query plans, memory use, latency, or recall. Change them deliberately and prefer session-level `SET` while testing. ## Query Planning These settings control whether ParadeDB proposes custom plans for eligible queries. | Setting | Default | Context | Description | | --------------------------------------------------- | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paradedb.enable_custom_scan` | `on` | user | Enables ParadeDB's base custom scan, which replaces table scans with ParadeDB index scans. | | `paradedb.enable_aggregate_custom_scan` | `on` | user | Enables the aggregate custom scan for eligible `pdb.agg` and `GROUP BY` queries. | | `paradedb.enable_join_custom_scan` | `on` | user | Enables the join custom scan, which pushes eligible joins into the ParadeDB executor. | | `paradedb.enable_rank_join` | `on` | user | Enables `RankJoinExec` and lazy probe-side top-K execution for eligible joins with `ORDER BY ... LIMIT`. | | `paradedb.rank_join_min_rows` | `10000` | user | Minimum estimated matching rows on join inputs before replacing a one-pass `HashJoinExec` with `RankJoinExec` or lazy sort. | | `paradedb.rank_join_unscored_selectivity_threshold` | `0.08` | user | Minimum unscored input or disjunctive base-filter selectivity for `RankJoinExec` before preferring `HashJoinExec`. | | `paradedb.enable_custom_scan_without_operator` | `off` | user | Allows custom scans without a ParadeDB search operator when the whole `WHERE` clause can push down. | | `paradedb.enable_filter_pushdown` | `on` | user | Allows non-indexed predicates to use heap filtering after the ParadeDB scan. | | `paradedb.enable_range_partitioned_join` | `on` | user | Enables range co-partitioned joins and asymmetric range alignment for MPP joins on indexes configured with `partition_by`. | | `paradedb.enable_segment_pruning` | `on` | user | Prunes non-matching index segments using per-segment min/max field statistics during planning and scan execution. | | `paradedb.enable_heuristic_selectivity` | `on` | user | Uses cheap planner selectivity estimates for expensive fuzzy, regex, and range query shapes. | | `paradedb.per_tuple_cost` | `100000000.0` | user | Planner cost multiplier that discourages using ParadeDB operators outside a supported index plan. | | `paradedb.explain_recursive_estimates` | `off` | user | Shows recursive document-count estimates in `EXPLAIN VERBOSE`; intended for debugging. | | `paradedb.planner_warnings` | `warning` | user | Controls warnings when an optimized scan cannot be used, and `EXPLAIN` warnings explaining why a faster plan variant within a scan was not used. Accepts `off`, `warning`, or `error`. | | `paradedb.spill_to_disk` | `off` | user | Allows eligible join and aggregate queries to spill to disk when they exceed `work_mem`. | | `paradedb.max_term_set_size` | `262144` | user | Maximum number of terms in a single term set (e.g. `pdb.term_set`, `===` with an array) before ParadeDB errors. Warns once per statement above half this value. | ## Synonyms These settings affect the queries that expand with `pdb.expand`. See [Synonyms](/reference/tokenizers/synonyms). | Setting | Default | Context | Description | | ------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `paradedb.synonyms_max_alternatives` | `32` | user | Most alternatives one run of query words expands to in a match query, and most phrases a phrase query searches. The query parser has the first limit for a word and the second for a quoted phrase. The typed words stay when a rule lists them. | | `paradedb.synonyms_max_rules_per_key` | `1024` | user | Most rules one synonym word reads in a segment. A word in more rules reads only the first ones. | ## Top K These settings affect queries that combine a ParadeDB predicate with `ORDER BY ... LIMIT`. See [Top K](/reference/full-text/top-k). | Setting | Default | Context | Description | | -------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `paradedb.limit_fetch_multiplier` | `1.0` | user | Multiplies the query `LIMIT` to choose the initial Top K fetch size. | | `paradedb.topk_retry_scale_factor` | `2` | user | Multiplies the fetch size on retries when the first Top K pass does not collect enough rows. | | `paradedb.max_topk_chunk_size` | `100000` | user | Maximum chunk size for Top K collection. | | `paradedb.enable_segmented_topk` | `on` | user | Enables segmented Top K pruning for late-materialized string and byte columns. | | `paradedb.expensive_query_cost_factor` | `25.0` | user | Scales planner cost estimates for fuzzy, regex, and more-like-this queries. | | `paradedb.disjunction_pruning` | `auto` | user | Selects the pruning algorithm for eligible scored Top K disjunctions. Accepts `auto`, `wand`, or `maxscore`. | ## Aggregates These settings affect `pdb.agg`, `GROUP BY`, and faceted search. See [Aggregate Syntax](/reference/aggregates/overview). | Setting | Default | Context | Description | | ---------------------------------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `paradedb.max_term_agg_buckets` | `65000` | user | Maximum number of terms aggregation buckets or groups before ParadeDB errors. | | `paradedb.max_window_aggregate_response_bytes` | `1048576` | user | Maximum serialized response size for a window aggregate during a parallel scan, in bytes. | | `paradedb.enable_bitmap_postings` | `on` | user | Uses posting bitmaps for eligible counts; disable to use ordinary postings. | | `paradedb.visibility_threshold` | `10000` | user | With aggregate visibility set to `threshold`, applies transaction visibility checks below this estimated matching row count. Reads raw index data at or above it. | ## Vector Search These settings affect vector queries over `pgvector`'s `vector` type. See [Indexing Vectors](/reference/indexing/indexing-vectors) and [Tuning Recall and Latency](/reference/vector/tuning). | Setting | Default | Context | Description | | --------------------------------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `paradedb.vector_adaptive_probing` | `on` | user | Stops cluster probing when competitive-candidate admission decays, within the same routing and work budgets. | | `paradedb.vector_cluster_max_probe` | `100` | user | Global probe budget normalized by filter selectivity (`1`–`1000000`); also controls the router request. | | `paradedb.vector_clustering_threshold` | `500` | user | Segment document-count threshold at which merged vector storage switches from flat to IVF. | | `paradedb.vector_fixed_probe_cost_rows` | Tantivy default | user | Fixed per-probe cost used by the IVF probe-budget model; mainly for testing and calibration. | | `paradedb.vector_stats` | `off` | user | Shows per-segment vector scan statistics in `EXPLAIN (ANALYZE, VERBOSE)`; for diagnostics. | ## Parallel Execution These settings control ParadeDB's parallel execution and MPP paths. | Setting | Default | Context | Description | | ----------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `paradedb.min_rows_per_worker` | `300000` | user | Minimum estimated rows per parallel worker. Set to `0` to use segment-based parallelism only. | | `paradedb.mpp_min_rows` | `500000` | user | Minimum estimated source row count before MPP execution can engage. Set to `0` to disable the gate. | | `paradedb.mpp_queue_size` | `8MB` | user | Per-query DSM ring budget divided across all `2 * N * (N - 1)` SPSC rings (`N = W + 1` processes, floored at `16kB` per ring). | | `paradedb.mpp_debug` | `off` | user | Emits verbose MPP runtime diagnostics to the Postgres server log. | | `paradedb.mpp_trace` | `off` | user | Emits MPP setup timing diagnostics to the Postgres server log. | | `paradedb.mpp_test_panic_in_worker` | `off` | user | Debug-build testing hook that intentionally panics in an MPP worker. Not available in release builds. | ## Columnar Execution These settings control how ParadeDB reads columnar data from the index. | Setting | Default | Context | Description | | ----------------------------------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------- | | `paradedb.enable_fast_field_exec` | `on` | user | Enables optimized columnar executors for narrow projections. | | `paradedb.enable_columnar_exec` | `on` | user | Enables the columnar executor for multi-column string and numeric projections. | | `paradedb.columnar_exec_column_threshold` | `3` | user | Number of projected index columns below which the columnar executor is used instead of normal row fetch. | ## Term Set Pushdown These settings affect pushed-down `IN`, `ANY`, and term-set queries. | Setting | Default | Context | Description | | -------------------------------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `paradedb.hash_join_inlist_pushdown_max_size` | `16777216` | user | Maximum byte size of a join-derived `IN` list dynamic filter before falling back to a hash-table lookup filter. | | `paradedb.hash_join_inlist_pushdown_max_distinct_values` | `20000` | user | Maximum distinct values in a join-derived `IN` list on standard unsorted joins (above which hash-table lookup filters are faster); joins with `ORDER BY ... LIMIT` using lazy probe-side top-K execution use `paradedb.lazy_sort_inlist_pushdown_max_distinct_values`. Set to `0` to disable globally. | | `paradedb.lazy_sort_inlist_pushdown_max_distinct_values` | `131072` | user | Maximum distinct values in a join-derived `IN` list for joins with `ORDER BY ... LIMIT` using lazy probe-side top-K execution (higher than `paradedb.hash_join_inlist_pushdown_max_distinct_values` so top-K and vector collectors filter during collection). Set to `0` to disable. | | `paradedb.term_set_gallop_enabled` | `on` | user | Enables galloping execution for term-set queries on sorted columnar segments. | | `paradedb.term_set_bitset_max_density_unique` | `0.0005` | user | Density threshold for selecting bitset execution on unique-valued columns. | | `paradedb.term_set_bitset_max_density_multi` | `0.005` | user | Density threshold for selecting bitset execution on columns where multiple rows share a value. | | `paradedb.dynamic_filter_batch_size` | `0` | user | Caps scanner batch size during dynamic filter pushdown. `0` uses the scanner default. | ## Index Maintenance These settings affect segment layout and background merging. | Setting | Default | Context | Description | | ------------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `paradedb.global_target_segment_count` | `0` | sighup | Overrides every index's `target_segment_count` when non-zero. Requires config reload. | | `paradedb.global_enable_background_merging` | `on` | sighup | Enables write-triggered background segment merging globally. Does not control periodic mutable sweeps. Requires config reload. | | `paradedb.global_mutable_segment_rows` | `-1` | user | Overrides every index's `mutable_segment_rows` when set to a non-negative value. | | `paradedb.mutable_sweep_interval` | `1s` | sighup | Interval between periodic mutable-segment sweeps. Set to `0` to disable; write-triggered merging is unchanged. | ## Per-Index Search Options Set these options in the index's `WITH` clause. The linked guides explain when changes require rebuilding the index. | Option | Default | Description | Reference | | ---------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `partition_by` | None | Columns used to partition index segments. | [Index Partitioning](/reference/indexing/partition-by) | | `target_segment_count` | Automatic | Target number of segments during `CREATE INDEX` or `REINDEX`. Overridden by a non-zero `paradedb.global_target_segment_count`. | [Read Throughput](/operate/performance-tuning/reads#adjusting-target-segment-count) | | `search_tokenizer` | Indexed field's tokenizer | Default search-time tokenizer for text and JSON fields. | [Search Tokenizer](/reference/tokenizers/search-tokenizer) | | `training_sample_ratio` | `0.32` | Fraction of vectors sampled for training. Defaults to 32%. Set `0` for automatic sampling: 128 training vectors per list, at least 16, limited by `maintenance_work_mem`. Values from `0` through `1` are accepted. | [Vector Index Options](/reference/indexing/indexing-vectors#index-options) | | `target_leaf_size` | `400` | Target indexed vectors per cluster. With automatic sampling this is `n / target_leaf_size` lists. | [Vector Index Options](/reference/indexing/indexing-vectors#index-options) | | `quantization` | `[1,1]` | Quantization layer widths shared by all vector fields. Set to `0` to disable quantization. | [Vector Index Options](/reference/indexing/indexing-vectors#index-options) | | `vector_router_quantization` | `true` | Route through one-bit centroid codes with an exact rerank of the shortlisted centroids; `false` keeps full-precision routing. | [Vector Index Options](/reference/indexing/indexing-vectors#index-options) | | `replication` | `2` | Number of IVF clusters each vector is assigned to; `2` adds a second cluster chosen to cover queries the first misses. | [Vector Index Options](/reference/indexing/indexing-vectors#index-options) | ## Per-Index Write Options Set these options with `CREATE INDEX ... WITH (...)` or `ALTER INDEX ... SET (...)`. See [Write Throughput](/operate/performance-tuning/writes) for tuning guidance. | Option | Default | Description | | ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `layer_sizes` | Disabled | Foreground merge thresholds. Set to `'0'` to disable foreground merging. | | `background_layer_sizes` | `100KB, 1MB, 10MB, 100MB, 1GB, 10GB` | Write-triggered background merge thresholds. Set to `'0'` to disable; periodic mutable sweeps are controlled separately. | | `mutable_segment_rows` | `1000` | Number of rows buffered in mutable segments. Overridden by `paradedb.global_mutable_segment_rows` when that setting is non-negative. | ## Related Postgres Settings ParadeDB also relies on standard Postgres memory settings: | Setting | Used for | | ---------------------- | -------------------------------------------------------------------------------- | | `maintenance_work_mem` | Index builds and index maintenance. Each parallel worker needs at least 15MB. | | `work_mem` | Query execution memory; ParadeDB clamps the effective Tantivy budget internally. |