During every INSERT/UPDATE/COPY/VACUUM, the BM25 index runs a compaction process that looks for opportunities to merge segments together. The goal is to consolidate smaller segments into larger ones, reducing the total number of segments and improving query performance. Segments become candidates for merging if their combined size meets or exceeds one of several configurable layer thresholds. These thresholds define target segment sizes — such as 10KB, 100KB, 1MB, etc. For each layer, the compactor checks if there are enough smaller segments whose total size adds up to the threshold. Both the layer sizes and whether merging happens in the foreground (blocking) or background (non-blocking) are configurable.

Foreground Layer Sizes

By default, layer sizes 1KB, 10KB, 100KB and 1MB are merged in the foreground. This can be configured with layer_sizes, either at CREATE INDEX time or afterward with ALTER INDEX.
CREATE INDEX search_idx ON mock_items USING bm25 (id, description, rating) WITH (key_field = 'id', layer_sizes = '1kb, 10kb, 100MB');
ALTER INDEX search_idx SET (layer_sizes = '100kb, 1mb, 100mb');
Setting layer_sizes to 0 disables foreground merging.
ALTER INDEX search_idx SET (layer_sizes = '0');

Background Layer Sizes

By default, layer sizes 10MB, 100MB, 1GB, 10GB, 100GB, and 1TB are merged in the background. This can be configured with background_layer_sizes, either at CREATE INDEX time or afterward with ALTER INDEX.
CREATE INDEX search_idx ON mock_items USING bm25 (id, description, rating) WITH (key_field = 'id', background_layer_sizes = '100MB, 1GB');
ALTER INDEX search_idx SET (background_layer_sizes = '100MB, 1GB');
Setting background_layer_sizes to 0 disables background merging.
ALTER INDEX search_idx SET (background_layer_sizes = '0');

Choosing Layer Sizes

As a general rule of thumb, merging larger layers is expensive and should happen in the background, whereas merging smaller layers is cheap and should happen in the foregorund to reduce the overhead of creating many background processes. Write throughput can be improved by moving more layers to the background, at the expense of launching more background processes. For instance, the following command moves all merging to the background.
ALTER INDEX search_idx SET (layer_sizes = '0', background_layer_sizes = '100kb, 1mb, 100mb');