Preview, recalculate, and export charts

Three operations work over chart results rather than chart structure: previewChart computes a chart without saving it (for live editor previews), recalculateCharts forces saved charts to recompute, and exportChartCSV ships a chart’s underlying records to CSV. Charts are Chart objects in the API, and every chart belongs to a dashboard (Dashboard) — these operations are authorized through that dashboard.

To create, edit, or delete charts, see Create and manage charts. To read or subscribe to saved charts, see Query and subscribe to charts.

previewChart

previewChart is a query, not a mutation, even though it accepts CreateChartInput. It computes a chart and returns it without persisting anything — no chart, segment, or segment value is written to the database. Use it to render a live preview in a chart editor before the user commits to saving.

The returned Chart is fabricated: it carries a throwaway id/uid, position is always 65535, and createdAt/updatedAt are the current time. Don’t store or re-reference these — call createChart to persist the chart for real.

A preview works two ways, mirroring the two kinds of chart:

• Manual chart — pass chartSegments. Each segment’s formula is evaluated against its segment values (each value is an aggregate over one workspace’s records).
• Auto-generated chart — omit chartSegments and pass metadata.barChart (an x-axis/y-axis spec) or metadata.pieChart (a group-by/value spec). Blue generates the segments for you.

If you supply neither chartSegments nor a metadata.barChart/metadata.pieChart block, the query fails.

Request

Preview an auto-generated bar chart that counts records per workspace, without saving it.

query PreviewBarChart {
  previewChart(
    input: {
      dashboardId: "dashboard_123"
      title: "Records by workspace"
      type: BAR
      metadata: {
        barChart: {
          xAxis: { type: PROJECT, title: "Workspace" }
          yAxis: { function: COUNT, title: "Records" }
        }
      }
    }
  ) {
    id
    title
    type
    position
    chartSegments {
      uid
      title
      formulaResult
    }
  }
}

Parameters

previewChart takes the same CreateChartInput as createChart. The fields relevant to a preview:

CreateChartInput

ChartType

ChartMetadataInput

BarChartMetadataInput

BarChartXAxisInput

BarChartYAxisInput

PieChartMetadataInput is the same shape with groupBy (a PieChartGroupByInput, no interval) and value (a PieChartValueInput, identical to BarChartYAxisInput).

BarChartXAxisType

ChartSegmentValueFunctions

Response

{
  "data": {
    "previewChart": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Records by workspace",
      "type": "BAR",
      "position": 65535,
      "chartSegments": [
        { "uid": "ck0seg1", "title": "Sales", "formulaResult": 128 },
        { "uid": "ck0seg2", "title": "Marketing", "formulaResult": 74 }
      ]
    }
  }
}

Returns

previewChart returns a Chart. Every field is computed in memory; the chart is not saved.

ChartSegment.formulaResult is the per-segment number; for a STAT chart there is typically one segment whose formulaResult is the headline value.

Errors

Two failure modes raise a generic error rather than a coded Blue error: a manual chartSegments value that references a workspace the caller doesn’t belong to (the preview throws Access denied to projects: …), and supplying neither chartSegments nor a metadata.barChart/metadata.pieChart block (there is nothing to compute).

recalculateCharts

recalculateCharts forces one or more saved charts to recompute their results immediately, then republishes them so subscribers see fresh numbers. Use it after data changes that wouldn’t otherwise trigger a recalculation, or to refresh a stale chart on demand.

The call is all-or-nothing on access: every id in chartIds must resolve to a chart the caller can view. If any one is inaccessible, the whole call is rejected with FORBIDDEN and no chart is recalculated.

Request

mutation RecalculateCharts {
  recalculateCharts(input: { chartIds: ["chart_123", "chart_456"] })
}

recalculateCharts returns a nullable Boolean (true on success), so it takes no sub-selection.

Parameters

RecalculateChartsInput

Response

{
  "data": {
    "recalculateCharts": true
  }
}

Each recalculated chart is republished over subscribeToChart as a ChartSubscriptionPayload with mutation: UPDATED, carrying the recomputed isCalculating/needCalculation/formulaResult values on node. The mutation itself returns only the boolean — read the new numbers from the subscription or by re-querying chart/charts.

Errors

An unknown id is treated the same as an inaccessible one — both reduce the viewable count below the requested count and trigger FORBIDDEN.

exportChartCSV

exportChartCSV enqueues an asynchronous CSV export of the records behind a chart and returns true immediately. The export runs as a background job; the finished CSV is delivered out-of-band (emailed / served from the calling host), not in the GraphQL response. Pass an optional filter to scope which records are exported.

A per-chart, per-user lock prevents duplicate exports: once you start an export, a second exportChartCSV call for the same chart by the same user fails with CHART_ALREADY_EXPORTING until the lock expires after 6 hours (21,600 seconds).

Request

Export every record behind a chart.

mutation ExportChartCSV {
  exportChartCSV(chartId: "chart_123")
}

exportChartCSV returns Boolean!, so it takes no sub-selection. true means the job was accepted — not that the file is ready.

Parameters

TodoFilterInput is the standard record filter used across the API; see List records for its full field set.

Response

{
  "data": {
    "exportChartCSV": true
  }
}

The boolean confirms the job was enqueued. The CSV arrives separately once the worker finishes; there is no operation that returns the file URL synchronously.

Full example

Export only the records that match a filter — here, records on a specific list.

mutation ExportFilteredChartCSV {
  exportChartCSV(chartId: "chart_123", filter: { todoListIds: ["list_123"] })
}

Errors

{
  "errors": [
    {
      "message": "Chart is already being exported.",
      "extensions": { "code": "CHART_ALREADY_EXPORTING" }
    }
  ]
}

Permissions

All three operations derive their permissions from the chart’s parent dashboard. There is no organization- or workspace-level chart access — a chart is reachable only through a dashboard you can see.

See Dashboards for how dashboard creators and dashboardUsers (with EDITOR/VIEWER roles) are managed.

Related

• Create and manage charts — persist a chart with createChart; previewChart shares its CreateChartInput.
• Build chart segments and values — the manual chartSegments/chartSegmentValues building blocks.
• Query and subscribe to charts — read recalculated results and stream UPDATED events over subscribeToChart.
• Charts — section overview.
• Dashboards — the parent objects charts and their permissions hang off.
• List records — the TodoFilterInput used by exportChartCSV.