---
title: Using range requests
description: Read only the byte ranges needed from large cloud-hosted assets.
hide_title: true
page_style: designed
---
import {DocPageHeader} from '@site/src/components/docs/doc-page-header';
import {DocOrientation, ReferenceBoundary} from '@site/src/components/docs/designed-doc';
import {RangeRequestGraphic} from '@site/src/components/docs/range-request-graphic';
Some tile formats store many tiles inside one large object. Loading each tile with an
independent HTTP request can waste round trips; loading the entire object can waste bandwidth.
loaders.gl Sources can use scheduled byte-range loading to take the middle path.
PMTiles URL sources use this path by default. The lower-level scheduler is available in
`@loaders.gl/core/loader-utils` for future byte-range Sources.
## How It Works
When a Source can resolve an application request to a byte offset and length, it can enqueue
that range in the shared `RangeRequestScheduler`.
The scheduler:
- waits for `rangeRequests.batchDelayMs`
- sorts queued reads by URL and byte offset
- expands a request by up to `rangeRequests.rangeExpansionBytes` to include a nearby read
- rejects a merge that would exceed `rangeRequests.maxMergedBytes`
- issues the merged HTTP `Range` request
- slices the merged response back into one promise per original tile
## Caching
Scheduling and caching are separate layers. `RangeRequestScheduler` combines compatible transport
work, while `RangeRequestCache` retains completed bytes and deduplicates exact requests that are
already in flight. Keeping those responsibilities separate lets Sources choose a memory budget
without changing request batching behavior.
`RangeRequestCache` follows the same insertion-order LRU model used by loaders.gl tile caches. It
supports entry and byte limits, protects pending requests from eviction, and serves a requested
range from a larger cached interval. Every cache hit returns standalone bytes so application code
cannot mutate or detach cache-owned storage. Large ranges that exceed the byte budget bypass the
cache rather than being copied and immediately evicted.
Use `RequestCache` for ordinary keyed asynchronous resources such as parsed 3D Tiles subtrees, and
`RangeRequestCache` for random-access file bytes. Frame-aware tile content caches remain specialized
because they must protect visible tiles and coordinate resource unloading.
This is automatic for PMTiles URL Sources. Callers can keep using `getTile()` or
`getTileData()`.
## Options
| Option | Default | Meaning |
| --------------------------------------- | --------- | ------- |
| `rangeRequests.batchDelayMs` | `50` | Time to wait for sibling tile requests before starting transport. |
| `rangeRequests.rangeExpansionBytes` | `65536` | Maximum byte gap to over-fetch when expanding one range to include the next close range. |
| `rangeRequests.maxGapBytes` | `65536` | Compatibility alias for `rangeExpansionBytes`. |
| `rangeRequests.maxMergedBytes` | `8388608` | Maximum byte length of one merged range request. |
| `rangeRequests.maxConcurrentRequests` | `6` | Reserved concurrency hint; transports may use it as they grow. |
| `rangeRequests.stats` | none | Optional probe.gl `Stats` object that receives shared scheduler counters. |
| `rangeRequests.onEvent` | none | Optional callback that receives scheduler diagnostics for queued, batched, completed, failed, and aborted range requests. |
Use `batchDelayMs: 0` when latency matters more than gathering sibling requests. Use a larger
`rangeExpansionBytes` when sibling tiles are usually close together and the server is far away.
Use a smaller `rangeExpansionBytes` when bandwidth is more constrained than request count.
## Range HTTP Requests
The shared scheduler currently merges close requests into one contiguous single-range HTTP
`Range` request. Single-range requests are fairly well supported by object stores, web servers,
and CDNs because they are required for common media playback, resumable downloads, and large
object caching. Well-known CDNs with documented range-request support include Amazon
CloudFront, Google Cloud CDN, Alibaba Cloud CDN, and BunnyCDN.
## Multi-Range/Multipart HTTP Requests
Multi-range requests use one comma-separated `Range` header to ask for several disjoint byte
ranges, and compatible servers return a `multipart/byteranges` response. This is part of HTTP,
but support is not as widely deployed or consistent as single-range responses. Production
deployments should not assume that object stores or CDNs support multipart range responses;
serving them may require a custom server or a CDN/server feature that has been explicitly
verified.
Test servers in this repository can return HTTP `multipart/byteranges` responses. That allows
loaders and Sources to be tested against comma-separated Range headers even when the production
transport chooses single, expanded ranges.
## Local Range Server
Website examples that need local PMTiles data can point at a companion loaders.gl range
server. The server serves a directory with CORS, regular `200` responses, single `206`
byte-range responses, and multipart `206` responses for comma-separated `Range` headers.
Ask example users to clone loaders.gl, install dependencies, choose a local data directory,
and run the server in a separate terminal:
```bash
git clone https://github.com/visgl/loaders.gl.git
cd loaders.gl
yarn install
yarn serve-range --root ./modules/tiles/test/pmtiles/data/pmtiles-v3 --port 9000
```
Then configure the website example with URLs below that server root:
```ts
const localPmtilesUrl = 'http://127.0.0.1:9000/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles';
```
Do not ask users to import these large archives into the website bundle. Fetch them by URL so
the Source can send HTTP `Range` headers.
Sources that read HTTP URLs can use `RangeRequestScheduler.fetch()` so the scheduler owns
common HTTP range behavior: creating `Range` headers, preserving caller headers, aborting
ignored `200 OK` full-object responses, parsing `416` content-range probes, and recording
transport diagnostics.
The server requires an explicit `--root` directory. Put only demo data in that directory when
using the default permissive CORS setting.
## Website Example Pattern
A website example can first try a configured URL. If that request fails because the local range
server is not running, show an inline instruction with the exact command that matches the
example's expected data directory. Keep the heavy data out of git and out of the website
static folder unless it is intentionally published as a small fixture.
Production examples should keep using public URLs from object storage or a CDN with normal
single-range support. The local server is for contributors, reviewers, and examples that use
private or very large data.
## Diagnostics
Pass a probe.gl `Stats` object when you need to understand aggregate range behavior across
helper classes. `createRangeStats` initializes the expected counters and `getRangeStats`
returns a typed snapshot:
```ts
import {createRangeStats, getRangeStats} from '@loaders.gl/core/loader-utils';
const stats = createRangeStats('pmtiles-range-transport');
const source = await createDataSource(url, [PMTilesLoader], {
rangeRequests: {
stats,
onEvent: event => console.log(event.type, event)
}
});
const rangeStats = getRangeStats(stats);
```
The shared scheduler reports logical caller ranges, batches, merged transport ranges, response
bytes, overfetch bytes, failed transport requests, aborted logical requests, and full-response
fallbacks.
## Servers That Ignore Range Headers
URL range transports send an abortable `fetch()` request with a `Range` header and expect a
`206 Partial Content` response. If the server responds with `200 OK`, the transport aborts the
fetch immediately, cancels the response body, and rejects the range request instead of reading
a whole PMTiles archive into memory.
## Blob And In-Memory Sources
Blob-backed Sources usually read slices directly from the Blob and bypass the default
`batchDelayMs`. The delay is intended to collect network work. Tests can still use Blobs in
node to exercise metadata parsing and decode paths without starting an HTTP server.
## Failure And Abort Behavior
Each caller receives an independent promise. If a caller aborts before the batch starts, that
request is rejected and removed. If a merged transport request fails, every child range in that
merged request is rejected.