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.query (what to group by, what to measure). Blue generates the segments for you.

If you supply neither chartSegments nor a metadata.query 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: {
        query: {
          dimensions: [{ type: PROJECT, title: "Workspace" }]
          metrics: [{ 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.query 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 keeps its established Boolean response for compatibility. It takes no sub-selection.

Parameters

RecalculateChartsInput

For automatic refresh coordination, call scheduleChartRecalculations with the same input. It returns ScheduleChartRecalculationsResult!, containing the chart IDs that the server scheduled and the configured retry delay. It also skips charts whose last computation exceeded the cost limit.

mutation ScheduleChartRecalculations {
  scheduleChartRecalculations(input: { chartIds: ["chart_123", "chart_456"], auto: true }) {
    scheduledChartIds
    retryAfterSeconds
  }
}

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. Read the new numbers from the subscription or by re-querying chart/charts. scheduleChartRecalculations is the automatic-refresh variant; it returns the IDs that passed the stale, cost, and cooldown guards.

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.

An export’s rows are read as the dashboard’s creator, which is the same scope the chart’s numbers were computed as — so the CSV matches the card. The dashboard creator can turn viewer access to those rows on or off with allowViewerChartData. Editors always retain access.

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.