Reload a Table Segment

Reload a table segment in Apache Pinot.

When Pinot writes data to segments in a table, it saves those segments to a deep store location specified in your table configuration, such as a storage drive or Amazon S3 bucket.

Schema and transform changes on realtime tables need a plan for consuming segments. When pinot.server.instance.reload.consumingSegment is true (default), reload of a consuming segment requests a force commit (sets a flag on the consumer); the segment seals asynchronously in the consumption loop and a replacement consumer then starts on the latest schema. Reload job success is not the same as “new consumers are ONLINE” — for a hard barrier, use forceCommit and poll forceCommitStatus, or wait until consuming segment generations advance. Transform-heavy changes may still want a pause boundary. See the schema evolution decision table and add a new column during ingestion.

Use the Pinot Controller API to reload segments

Pinot exposes three reload-related controller endpoints:

POST /segments/{tableName}/reload
POST /segments/{tableName}/{segmentName}/reload
GET /segments/segmentReloadStatus/{jobId}

The reload requests are asynchronous. Pinot returns a reload job ID, and you can poll that job ID until the reload finishes.

Reload all segments in a table

To reload all segments for a table, use:

POST /segments/{tableName}/reload

tableName can be either a typed table name such as myTable_OFFLINE, or a raw table name such as myTable.

Supported query parameters:

Parameter	Description
type	Optional table type filter when the path uses a raw table name. Supported values are OFFLINE and REALTIME.
forceDownload	Re-download immutable segments from deep store before reloading. Defaults to false.
targetInstance	Send reload messages only to the specified server instance.
instanceToSegmentsMap	JSON map of server instance to segment list. When present, Pinot reloads only the listed segments on the listed servers.

Consuming segments: there is no separate includingConsuming query flag on this API. Whether consuming segments are included is controlled by the server config pinot.server.instance.reload.consumingSegment (default true). When enabled and allowed by consuming-segment consistency mode, each consuming segment reload requests a force commit on that consumer; sealing and starting the replacement consumer are asynchronous and are not tracked by the reload job id. To commit consumers without reloading every completed segment, and to poll completion, call POST /tables/{tableName}/forceCommit and GET /tables/forceCommitStatus/{jobId} instead.

Example:

curl -X POST "http://localhost:9000/segments/baseballStats/reload?type=OFFLINE&forceDownload=true" \
  -H "accept: application/json"

When forceDownload=true and you pass a raw table name without a type, Pinot automatically limits the request to the OFFLINE table because forced deep-store download is only supported for immutable segments.

If you use instanceToSegmentsMap, URL-encode the JSON map and send it as a query parameter.

Typical response:

{
  "status": "{\"baseballStats_OFFLINE\":{\"numMessagesSent\":\"24\",\"reloadJobId\":\"6b2f9d35-0d3f-4ef5-91db-f77cb6fdd1c0\",\"reloadJobMetaZKStorageStatus\":\"SUCCESS\"}}"
}

The status field is a JSON string keyed by table name. Each table entry includes the submitted reloadJobId, the number of reload messages sent to servers, and whether Pinot successfully persisted job metadata in ZooKeeper.

Reload segments in a time range

To reload only segments whose time column falls within a specified time window, use the optional startTimestamp and endTimestamp query parameters:

POST /segments/{tableName}/reload?startTimestamp=<ms>&endTimestamp=<ms>

This approach is significantly more efficient than reloading the entire table when you only need to reload recent data.

Supported query parameters (in addition to the standard type, forceDownload, and targetInstance):

Parameter	Type	Description
startTimestamp	long	Start of the time window in milliseconds since epoch (inclusive). Segments are selected if their time range overlaps with [startTimestamp, endTimestamp).
endTimestamp	long	End of the time window in milliseconds since epoch (exclusive).
excludeOverlapping	boolean	When true, only reload segments whose time range is fully contained within [startTimestamp, endTimestamp). When false (default), also reload segments that partially overlap the window.

Prerequisites:

• The table must have a time column defined in its table configuration.

• Segments without time metadata will not match a time window and will not be reloaded.

Examples:

Reload segments in a one-month window:

curl -X POST "http://localhost:9000/segments/baseballStats/reload?startTimestamp=1740787200000&endTimestamp=1743465600000" \
  -H "accept: application/json"

Reload only segments fully contained within the window (no partial overlaps):

curl -X POST "http://localhost:9000/segments/baseballStats/reload?startTimestamp=1740787200000&endTimestamp=1743465600000&excludeOverlapping=true" \
  -H "accept: application/json"

Combine with other parameters (e.g., force download and target a specific instance):

curl -X POST "http://localhost:9000/segments/baseballStats/reload?type=OFFLINE&forceDownload=true&startTimestamp=1740787200000&endTimestamp=1743465600000" \
  -H "accept: application/json"

Time-range filtering is supported on both the table-level endpoint (POST /segments/{tableName}/reload) and the segment-level endpoint (POST /segments/{tableName}/{segmentName}/reload).

Added in Pinot 1.6.

Reload one segment

To reload a single segment from a table, use:

POST /segments/{tableName}/{segmentName}/reload

Supported query parameters:

Parameter	Description
forceDownload	Re-download the segment from deep store before reloading. Defaults to false.
targetInstance	Reload the segment only on the specified server instance.

Example:

curl -X POST "http://localhost:9000/segments/baseballStats_OFFLINE/baseballStats_2026-04-01_0/reload?targetInstance=Server_localhost_8098" \
  -H "accept: application/json"

Typical response:

{
  "status": "Submitted reload job id: 4f947c6f-8f51-4dbf-b4e7-a8f4f446ce88, sent 1 reload messages. Job meta ZK storage status: SUCCESS"
}

If the table path omits the type suffix, Pinot derives the table type from the segment name.

Check reload job status

To check the progress of a submitted reload job, use the reloadJobId returned by either reload endpoint:

curl -X GET "http://localhost:9000/segments/segmentReloadStatus/6b2f9d35-0d3f-4ef5-91db-f77cb6fdd1c0" \
  -H "accept: application/json"

Typical response:

{
  "status": "IN_PROGRESS",
  "timeElapsedInMinutes": 0.6,
  "estimatedTimeRemainingInMinutes": 1.4,
  "totalSegmentCount": 24,
  "successCount": 10,
  "totalServersQueried": 6,
  "totalServerCallsFailed": 0,
  "failureCount": 0,
  "metadata": {
    "jobId": "6b2f9d35-0d3f-4ef5-91db-f77cb6fdd1c0"
  },
  "segmentReloadFailures": []
}

Check whether a table needs reload

Before reloading, you can ask Pinot whether any servers think the table needs reload:

curl -X GET "http://localhost:9000/segments/baseballStats_OFFLINE/needReload?verbose=true" \
  -H "accept: application/json"

This endpoint requires a typed table name. With verbose=true, Pinot includes per-server decisions:

{
  "needReload": true,
  "serverToSegmentsCheckReloadList": {
    "instance123": {
      "needReload": true,
      "instanceId": "instance123"
    }
  }
}

Use the Pinot Admin Console to reload segments

To use the Pinot Admin Console, do the following:

1. From the left navigation menu, select Cluster Manager.

2. Under TENANTS, select the Tenant Name.

3. From the list of tables in the tenant, select the Table Name.

4. Do one of the following:

   • To reload all segments, under OPERATIONS, click Reload All Segments.

   • To reload a specific segment, under SEGMENTS, select the Segment Name, and then in the new OPERATIONS section, select Reload Segment.