Segment Reload Dry Run

Segment reload dry run previews what a table reload would change before you run the real reload. It samples table segments on the servers that host them, loads temporary segment copies with the proposed indexing config and schema, then returns the estimated index additions/removals, preprocessing time, size change, and any per-segment errors.

Dry run does not mutate the live segment directories. It creates temporary copies for sampled local segments and deletes them after the check.

When to Use

Use reload dry run before:

Adding, removing, or changing indexes on a large table.
Reloading segments after a schema or table-index config change.
Estimating segment size growth from new index settings.
Validating whether sampled segments can be reloaded successfully before triggering a full reload.
Comparing index changes across old, latest, or random segment samples.

For task-level planning such as Segment Backfill or Segment Purge, use the task dry-run APIs for those task types instead.

Endpoint

POST /tables/{tableNameWithType}/reload/dryRun
Content-Type: application/json

Path parameter:

Parameter	Description
`tableNameWithType`	Table name with type suffix, such as `orders_OFFLINE` or `events_REALTIME`.

The controller:

Resolves the table config and schema from ZooKeeper.
Applies only index-loading-related fields from the request’s proposed tableConfig.
Sends the enriched request to servers hosting the table.
Aggregates server responses into one controller-level response.

If segment preprocessing is disabled for the table, the response is empty because no index changes can be previewed.

Request Body

Field	Required	Default	Description
`tableConfig`	No	Current table config	Proposed table config to evaluate. The controller uses only relevant indexing and field-config changes from this object.
`schema`	No	Current schema	Proposed schema to evaluate.
`sampleStrategy`	No	`RANDOM`	Segment sampling strategy. Supported values: `RANDOM`, `OLDEST`, `LATEST`. Ignored when `targetSegments` is non-empty.
`sampleCount`	No	`5`	Number of segments to sample per server. Maximum is `10`.
`targetSegments`	No	`[]`	Explicit segment names to dry run. When set, sampling strategy and count are ignored.
`timeoutMs`	No	`10000`	Timeout in milliseconds for sampled segment dry-run work.

Example: Preview an Inverted Index

This request previews adding an inverted index to the status column and a bloom filter to customerId.

curl -sS -X POST "https://<controller-host>:9000/tables/orders_OFFLINE/reload/dryRun" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "sampleStrategy": "RANDOM",
    "sampleCount": 5,
    "timeoutMs": 30000,
    "tableConfig": {
      "fieldConfigList": [
        {
          "name": "status",
          "encodingType": "DICTIONARY",
          "indexTypes": ["INVERTED"]
        },
        {
          "name": "customerId",
          "encodingType": "DICTIONARY",
          "indexTypes": ["BLOOM"]
        }
      ]
    }
  }' | jq

Example response:

{
  "tableNameWithType": "orders_OFFLINE",
  "sampledSegments": [
    "orders_2026_01_01_0",
    "orders_2026_01_01_1"
  ],
  "avgTimeMsPerSegment": 842,
  "netColumnIndexChanged": {
    "status": {
      "added": ["inverted"],
      "removed": []
    },
    "customerId": {
      "added": ["bloom"],
      "removed": []
    }
  },
  "avgSizeChangeInBytes": 1843200,
  "totalSegmentsNeedReload": 214,
  "numExceptions": 0,
  "serverResults": {
    "Server_10.0.2.18_8098": {
      "totalSegmentsNeedReload": 107,
      "sampledSegmentResults": [
        {
          "name": "orders_2026_01_01_0",
          "timeMsPreprocess": 806,
          "sizeChangeInBytes": 1748992,
          "columnIndexChanged": {
            "status": {
              "added": ["inverted"],
              "removed": []
            }
          },
          "exception": null
        }
      ]
    }
  }
}

Example: Target Specific Segments

Use targetSegments when you want to dry run the exact segments that failed a previous reload or segments representative of a known time range.

curl -sS -X POST "https://<controller-host>:9000/tables/orders_OFFLINE/reload/dryRun" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "targetSegments": [
      "orders_2026_02_01_0",
      "orders_2026_02_01_1"
    ],
    "timeoutMs": 60000,
    "tableConfig": {
      "fieldConfigList": [
        {
          "name": "status",
          "encodingType": "DICTIONARY",
          "indexTypes": ["INVERTED"]
        }
      ]
    }
  }'

Each server intersects the requested list with its locally hosted segments. A server that does not host any requested segment returns an empty per-server response.

Sampling Strategies

Strategy	Behavior
`RANDOM`	Reservoir-samples local segments on each server. Use this for broad estimates.
`OLDEST`	Samples the oldest local segments by segment creation time. Use this when old segments may have outdated formats or configs.
`LATEST`	Samples the newest local segments by segment creation time. Use this when recent ingestion changes might affect reload behavior.

Remote segments that are not locally materialized can be counted as needing reload but are excluded from sample execution. The dry-run response can therefore show totalSegmentsNeedReload greater than sampledSegments.length.

Response Fields

Field	Description
`tableNameWithType`	Resolved table name with type.
`sampledSegments`	Flat list of segments that completed dry run successfully.
`avgTimeMsPerSegment`	Average preprocessing/load time across successful sampled segments.
`netColumnIndexChanged`	Union of per-column index additions and removals across successful samples.
`avgSizeChangeInBytes`	Average size delta for successful sampled segments. Positive means segment directories grew.
`totalSegmentsNeedReload`	Sum of server-reported segments that need reload.
`numExceptions`	Total per-server and per-segment exception count.
`serverResults`	Per-server detail, keyed by server instance ID.

Per-segment result fields:

Field	Description
`name`	Segment name.
`timeMsPreprocess`	Time spent preprocessing/loading the temporary copy. Omitted when the segment fails.
`sizeChangeInBytes`	Size delta for the temporary segment directory. Omitted when the segment fails.
`columnIndexChanged`	Per-column index additions/removals for that segment.
`exception`	`null` on success, otherwise a segment-level failure message.

Operational Notes

Dry run uses temporary segment directories and deletes them after the request.
Dry-run work is isolated from the real reload executor so it does not consume real reload worker threads.
sampleCount is capped at 10 to prevent expensive accidental scans.
timeoutMs applies to sampled segment dry-run work. Timed-out segments appear with an exception such as Dry-run timed out.
The controller always starts from the ZooKeeper table config and applies proposed indexing and field-config changes from the request.
Tier backend settings are adjusted so dry-run loading uses local temporary copies rather than writing to remote tier storage.

Interpreting Results

Use netColumnIndexChanged to confirm the reload would perform the expected index transition. For example:

{
  "status": {
    "added": ["inverted"],
    "removed": []
  },
  "message": {
    "added": ["text"],
    "removed": ["fst"]
  }
}

Use avgSizeChangeInBytes as a sample-based estimate, not an exact whole-table storage forecast. Multiply it by the number of segments that need reload to estimate rough footprint change, then validate with a larger or targeted sample if the result is close to your storage budget. If numExceptions is non-zero, inspect serverResults before triggering a full reload. Common failures include invalid index config, incompatible schema changes, segment format issues, or request timeout.

Troubleshooting

Symptom	Cause	Fix
`Sample count cannot exceed 10`	`sampleCount` is above the server-side limit.	Reduce `sampleCount` or use `targetSegments`.
Empty response	Table preprocessing is disabled or no hosted segments need reload.	Check `skipSegmentPreprocess`, table config, and segment reload status.
`Dry-run timed out`	A sampled segment did not finish before `timeoutMs`.	Increase `timeoutMs`, reduce sample size, or target fewer segments.
Segment appears in `totalSegmentsNeedReload` but not in samples	Segment is remote-only on that server or was not selected by sampling.	Use targeted segments hosted locally or run a larger sample.
Proposed index change does not appear	Request table config did not include the relevant `fieldConfigList` or `indexingConfig` change.	Include the proposed field/index config in the request body.

Get Started

Ingestion

External Tables

Query Data

Manage Data

Observability

Visualize Data

Cluster Operations

Manage Security

Release Notes

Reference

When to Use

Endpoint

Request Body

Example: Preview an Inverted Index

Example: Target Specific Segments

Sampling Strategies

Response Fields

Operational Notes

Interpreting Results

Troubleshooting

​When to Use

​Endpoint

​Request Body

​Example: Preview an Inverted Index

​Example: Target Specific Segments

​Sampling Strategies

​Response Fields

​Operational Notes

​Interpreting Results

​Troubleshooting

When to Use

Endpoint

Request Body

Example: Preview an Inverted Index

Example: Target Specific Segments

Sampling Strategies

Response Fields

Operational Notes

Interpreting Results

Troubleshooting