Export a Complete Server Report

exportCsv(), exportXlsx() and getVisibleExportData() export the currently loaded logical report. A server viewport can contain only a small window. Use exportFullReport() when the user needs every filtered analytical group and column.

const controller = new AbortController();
const result = await pivotPlugin.exportFullReport('xlsx', {
  signal: controller.signal,
  limits: { maxRows: 5000, maxCells: 100000 },
  onProgress: progress => console.log(progress.phase, progress.receivedBytes),
});
// result.content is Uint8Array for XLSX, string for CSV.
// Let your application save it using its normal download flow.

The stock Pivot context menu exposes Complete Filtered CSV and Complete Filtered XLSX for server reports. These commands remain disabled unless the engine explicitly advertises fullExport: true. A shared accessible dialog displays busy/received-byte status, supports cancel and dismissal, and reports failures. Retry by reopening Export. A committed report change, clear or destroy cancels the request and prevents a stale download.

Backend contract

Implement optional PivotEngineAdapter.exportReport(request, context) or PivotRemoteStore.exportReport(request, context) and advertise capabilities.fullExport. HttpPivotRemoteStore posts JSON to /api/pivot/export; configure its capabilities, authProvider, credentials and hooks as usual. Injected adapters use the same validated contract.

PivotFullExportRequest.query includes the committed view, registry version, source filters, aggregate filters, summaries, sorting, UI hints, semantic collapse paths, value-axis placement, totals configuration and field/measure labels. It deliberately excludes axis offset/limit windows. The canonical queryKey must be echoed exactly. A correlation ID and query key identify the export; neither grants permission.

The backend must authenticate each request, authorize view and fields, bind tenant scope from the authenticated session, enforce its own limits, and reject unsupported layouts/calculations explicitly. Do not trust client capability flags or tenant/user labels. Do not build a complete export by walking changing viewport pages.

Return PivotFullExportResponse with:

• Matching requestId and queryKey.
• scope: 'complete-filtered-report' and complete: true.
• A nonempty snapshot ID and snapshot.consistency: 'atomic-at-export'.
• Primitive columns, rows and totals; column headers are string paths and optional summaryId identifies the configured measure. rowCount includes total rows and columnCount includes label and expanded measure columns.

An atomic export-time database transaction/snapshot must cover domains, counts, cells and totals. This guarantee captures data at export time. It does not promise the same dataset version as an earlier on-screen viewport. Applications requiring that stronger guarantee must pin and authorize a backend dataset version in their semantic view contract.

The library rejects incomplete, stale or mismatched metadata, invalid cells, unknown measure identities and oversized tables. It reuses the existing CSV/XLSX writers, preserves raw numbers and safe native Excel measure formats, and never follows a server-provided file URL. Arbitrary/custom appearance and conditional-format rules are not exported as workbook styling.

Limits and cancellation

All requests include four positive hard limits, each bounded by library ceilings: 10,000 rows including totals, 256 flattened columns including labels, 500,000 cells and 16,000,000 bytes. Applications may lower these limits. Backends must reject an oversized complete result; they must never silently truncate it. Both the response JSON and formatted CSV/XLSX output must fit the byte limit.

The HTTP store checks declared content length and counts stream bytes before JSON decoding. Each export owns its transport lifetime, authentication, telemetry and cancellation. Public export promises settle on cancellation even when an injected adapter ignores the signal; such adapters still need actual backend query cancellation/timeouts to release server resources. Local formatting is bounded synchronous work.

Real SQL reference

packages/pivot/server-reference includes a SQLite implementation using one read transaction and independent golden acceptance assertions. It covers complete flat reports beyond normal load windows, source WHERE, row HAVING, independent full-source grand totals, duplicate/no-ID measures, authorized tenants/fields, limits and pre-cancellation. Run:

pnpm --filter @revolist/pivot test:backend

The reference supports at most one row and one column field with values on columns. It rejects hierarchical expansion/collapse, subtotals, value rows, independent leaf summaries, calculations, date grouping and suppressed totals. SQL COUNT/null semantics remain as documented in backend validation. Synchronous SQLite statements cannot be interrupted while executing. This repository reference and kit do not certify a customer backend, production authentication, concurrency or warehouse performance.