> ## Documentation Index
> Fetch the complete documentation index at: https://docs.startree.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Forward Block Index

> Use the Forward Block index to map document blocks to forward-index byte ranges for more efficient remote reads.

## Overview and Purpose

The `forwardBlock` index records the byte ranges used by contiguous document ID blocks in a column's forward index. StarTree Cloud can use this metadata to prefetch the data needed by filtered scans, especially when segment files are read from cloud object storage.

Use the Forward Block index when a query first filters rows with one column and then projects or evaluates another column for the matching document IDs.

The index is especially useful for:

* Remote segment reads from cloud object storage.
* Large raw forward indexes with compressed chunks.
* Queries with selective filters followed by projection or expression evaluation.
* Columns where reading exactly the needed byte ranges is cheaper than scanning broad forward-index regions.

<Info>
  The Forward Block index does not evaluate predicates by itself. It helps StarTree Cloud read the forward-index byte ranges needed after another filter has selected candidate document IDs.
</Info>

## Availability

The Forward Block index is available in StarTree release 0.12 and later. The corresponding STP release branch is `release/1.5.0-STP-2.85.x`.

## How the Index Works

The Forward Block index maps document ID ranges to byte ranges in the column forward index.

At query time:

1. Another predicate, index, or scan produces candidate document IDs.
2. StarTree Cloud groups those document IDs by forward block.
3. The Forward Block index identifies the byte ranges needed for those blocks.
4. The server can prefetch those byte ranges before decoding values.

This reduces latency when random forward-index reads would otherwise issue many small remote reads.

## Configuration

To enable the Forward Block index, add `forwardBlock` to the target column's `fieldConfigList` entry.

```json theme={null}
{
  "fieldConfigList": [
    {
      "name": "payload",
      "encodingType": "RAW",
      "indexes": {
        "forward": {
          "compressionCodec": "ZSTD"
        },
        "forwardBlock": {
          "blockSize": 1024
        }
      }
    }
  ]
}
```

### Configuration Parameters

| Parameter   | Required | Description                                                                                                                                                                               |
| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockSize` | No       | Number of documents represented by each forward block. Smaller values improve read precision for selective filters. Larger values reduce metadata and can work better for adjacent reads. |

## Query Examples

Use the index on columns that are read after filtering. In this example, `payload` is projected only for rows that match the tenant and time filter:

```sql theme={null}
SELECT userId, payload
FROM clickstream
WHERE tenantId = 'acme'
  AND eventTimeMillis >= 1764556800000
LIMIT 100;
```

The Forward Block index can also help when expressions read a large raw column after a selective predicate:

```sql theme={null}
SELECT count(*)
FROM clickstream
WHERE tenantId = 'acme'
  AND regexp_like(payload, 'checkout')
  AND eventTimeMillis >= 1764556800000;
```

## Tuning Guidance

Choose `blockSize` based on how concentrated candidate document IDs are after filtering:

* Use a smaller `blockSize` when filters are very selective and matching rows are scattered.
* Use a larger `blockSize` when scans usually touch adjacent rows and prefetch overhead matters more than precision.
* Start with `1024` when you do not have enough benchmark data, then compare latency and remote bytes read.

## Performance Considerations

1. **Best with remote storage**: The benefit is largest when forward-index reads come from cloud object storage.
2. **Complements other filters**: Pair it with selective filters, inverted indexes, range indexes, Min/Max indexes, or sorted columns.
3. **Adds metadata**: Smaller blocks create more metadata. Measure index size when reducing `blockSize`.
4. **Reload existing segments**: After enabling the index, reload existing segments so StarTree Cloud builds the forward block metadata.