---
title: Segment Size
---

During every `INSERT`/`UPDATE`/`COPY`/`VACUUM`, the BM25 index runs a compaction process that looks for opportunities to merge [segments](/documentation/concepts/index#segment)
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`.

```sql
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.

```sql
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`.

```sql
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.

```sql
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.

```sql
ALTER INDEX search_idx SET (layer_sizes = '0', background_layer_sizes = '100kb, 1mb, 100mb');
```