Remote API Reference

The Remote Pivot API is a transport-agnostic JSON contract that allows RevoGrid to communicate with analytical backends, OLAP cubes, or custom SQL planners.

Load Request

The PivotLoadRequest is sent whenever the grid needs to materialize a visible window of analytical data.

Root Properties

• viewId: Semantic identifier for the dataset (e.g., sales_cube).
• fieldsVersion: Version of the field registry used to resolve selectors.
• loadOptions: The analytical query definition.
• viewport: Request windows for row and column axes.
• uiState: Optional hints for engine-side formatting.

Load Options

The loadOptions object defines the shape of the analytical query:

• rows: Array of group descriptors for the row axis.
• columns: Array of group descriptors for the column axis.
• values: Measures to aggregate.
• filter: Complex filter expression tree.
• sort: Sorting directives (can include sort-by-summary).
• groupSummary: Measures to calculate at every group level.

Viewport

The viewport defines independent analytical windows:

• rowAxis: Contains offset, limit, and expandedPaths.
• columnAxis: Contains offset, limit, and expandedPaths.

Use analytical paths for expansion state, not visible row indexes.

Normalization Limits

Before planning/execution, requests are typically normalized against backend limits (PivotLimits) to keep payloads and query complexity bounded.

Common limits include:

• maxRowWindowSize: Maximum allowed rowAxis.limit.
• maxColumnWindowSize: Maximum allowed columnAxis.limit.
• maxExpandedPaths: Maximum number of expansion paths per axis.
• maxExpansionDepth: Maximum hierarchy depth of a single expansion path.
• maxDrilldownLimit: Maximum page size for drilldown requests.

For maxExpansionDepth, depth is the number of path segments. Example: ['Region', 'Country', 'City'] has depth 3.

Load Response

PivotLoadResponse returns only the data needed for the current visible window.

Root Properties

• data: Array of row records (expected to have __rowPath and __columnPath).
• summary: Optional grand-total or pinned rows.
• rowAxis: Window metadata for the row axis.
• columnAxis: Window metadata for the column axis.
• groupAggregates: Optional grouped-row measures.
• meta: Diagnostic metadata.

Important response metadata:

• cacheStatus: ‘hit’, ‘miss’, ‘warm’, or ‘bypass’.

Axis Metadata

Both rowAxis and columnAxis use the same metadata structure.

Field	Role	Description
paths	Required (Columns)	Array of analytical paths used to generate headers.
totalCount	Required (Rows)	Total members on server. Required for row-axis scrollbars and pagination.

Drilldown

Drilldown uses PivotDrilldownRequest and PivotDrilldownResponse.

The request identifies a visible summary cell by:

• rowPath
• columnPath
• optional dataIndex

The backend should reuse the same analytical filter context as the Pivot request, then return matching fact rows with pagination.

UI State Hints

uiState hints allow the backend to optimize its output format:

• rowHeaderLayout: ‘tree’ or ‘flat’.
• showTotalsPrior: Placement of subtotals.
• collapsedByDefault: Initial hierarchy state.