Complete and Viewport Data

Use this advanced provider only when a large time or numeric domain cannot be returned as one chart frame. Start with the complete chart provider for ordinary reports. A viewport is the visible interval, such as January through March; the provider must describe that interval and the full source domain accurately.

Ordinary load returns all members for the selected chart scope. Add loadViewport when the chart must request only a numeric or time interval; the two methods have separate response requirements.

Try a requested window

Interactive example

Load just the visible days

Request four days at a time from a twelve-day source.

Try it: Choose Days 5–8, then All 12 days.

The example loads when visible.

Reset

What to notice: The chart and request window change; the full domain stays 1–12. Query reuses fresh identical reads.

Choose Days 1–4, then Days 5–8, then All 12 days. The line chart and request summary show which interval the simulated backend returned. Changing the window requests data for that interval; it does not page source orders and calculate partial totals in the browser.

Enable windowed reads

import type { PivotChartDataProvider } from '@revolist/pivot';

const dataProvider: PivotChartDataProvider = {
  capabilities: { viewport: true },
  query: { staleTime: 10_000 },
  load: (request, { signal }) => api.loadCompleteChartFrame(request, signal),
  loadViewport: (request, { signal }) => api.loadChartWindow(request, signal),
};

api is your application transport. Both entry points receive an abort signal and both use the shared Query readers. Complete frames and viewport frames have separate cache keys and validators.

Request and response

PivotChartViewportDataRequest extends the complete request. Its chart payload adds:

Field	Meaning
purpose	'detail' for the chart frame or 'overview' for the full-domain navigator.
viewport	The requested numeric/time ranges, including named axes where configured. Category windows are not supported by this contract.
pixelWidth	A positive integer the backend can use to choose resolution.
timePolicies	Optional financial-session policies associated with time axes.
histogram / histograms	Complete-bin requirements when those chart families request them.

PivotChartViewportDataResponse includes the ordinary category, series and value matrices plus the exact purpose and viewport echoes and a stable fullDomain. For overview reads, echo the requested empty viewport. The source total may exceed the returned category count; all requested series must still be present.

The returned frame must be complete for its declared window. Its full-domain bounds describe the source rather than the current window. Response correlation, semantic scope, analytical query echoes, matrix dimensions and limits are still validated. This capability never permits partial responses through ordinary load.

Ownership and cancellation

The source captures the committed Pivot revision, scope and analytical query. Changes to those inputs replace its source; superseded responses cannot update the new chart. Forward the supplied signal to your network and computation work.

Query keys include the semantic request, purpose, viewport, pixel width, bindings and applicable time/histogram policies. Detail and overview responses are not interchangeable. Read Query and Lifecycle for freshness, source sharing and teardown.

Next steps

See your first chart, data and measures and the API reference.