Charts

Create, build, preview, recalculate, export, and query the STAT, PIE, and BAR charts that live inside a dashboard.

Charts are the visualizations that live inside a dashboard. Each chart is a STAT, PIE, or BAR card built either from auto-generated metadata (an x-axis/y-axis or group-by/value spec computed over records) or from manual segments containing formula-driven values. This section covers creating and managing charts, building their segments and values, previewing results before saving, recalculating and CSV-exporting chart data, and querying or subscribing to charts on a dashboard.

Charts are always scoped to a parent dashboard. Permissions derive from dashboard access: viewer access for reads, and dashboard ownership or the EDITOR role for any write. There is no organization- or workspace-level chart query — you reach charts through their dashboard.

Concepts and types

Product nounSchema typeWhat it is
ChartChartA single STAT/PIE/BAR card on a dashboard. type is ChartType.
Manual chartChart.chartSegmentsA chart driven by ChartSegments and formulas.
Auto-generated chartChart.metadata (ChartMetadata)A chart driven by a barChart (xAxis/yAxis) or pieChart (groupBy/value) spec.
SegmentChartSegmentA Formula plus a color and title; the building block of a manual chart.
Segment valueChartSegmentValueA named, project-scoped aggregation referenced by a segment’s formula via its uid.
Aggregate functionChartSegmentValueFunctionsCOUNT, COUNTA, SUM, AVERAGE, AVERAGEA, MIN, MAX — applied to a value.
Display rollupFormulaDisplay (ChartFunction)The segment-level display function. Same member names as ChartSegmentValueFunctions, but a distinct type.
RecordTodoRecords are Todo objects; values aggregate over a project’s records, optionally narrowed by a TodoFilterInput.
Manual vs auto-generated

A chart carries either chartSegments (manual) or metadata (auto-generated), not both. The segment and value mutations apply only to manual charts; barChart/pieChart metadata is supplied at create time. ChartFunction (on FormulaDisplay) and ChartSegmentValueFunctions (on each value and metadata axis) share member names but are different enums — keep them straight in examples.

In this section

PageWhat it covers
Create and manage chartsThe chart lifecycle: createChart (with optional inline chartSegments or barChart/pieChart metadata), editChart to rename/reposition/restyle, copyChart to duplicate with UID-remapped formulas, and deleteChart.
Build chart segments and valuesThe building blocks of manual charts: create/edit/delete for ChartSegment and ChartSegmentValue, the formula-UID linkage, ChartSegmentValueFunctions, and project/custom-field validation.
Preview, recalculate, and exportData operations: previewChart (a Query that computes a throwaway chart without persisting), recalculateCharts (force recomputation by id), and exportChartCSV (async, fire-and-forget CSV export).
Query and subscribe to chartsRead one chart with chart(id:) or list a dashboard’s charts with charts(filter:), including the todoFilter recalculation path, and subscribeToChart for real-time create/update/delete events.
Results are asynchronous

Creating, copying, and recalculating charts enqueue a background calculation rather than returning final numbers. The Chart flags isCalculating, needCalculation, and isCalculatingWithFilter reflect that pending state; final results arrive via subscribeToChart, not synchronously from the mutation.

  • Dashboards — Charts always belong to a dashboard; access is inherited from it.
  • Custom fields — Segment values and metadata axes can aggregate over a customFieldId.
  • List records — The TodoFilterInput used to scope a chart’s records is the same filter used to query records.