Update report
fastero_update_reportDestructiveIdempotent
Change a report (a dashboard widget) in place: its name or description, how it draws (chartType together with the assignments that chart needs), its display settings, or a text block’s text. Every dashboard that places it shows the change, and what it replaces is not kept, except on a Vega-Lite chart or one becoming one: vegaLite rebuilds it, and restoreRevision brings back any of its last 20 versions. Fields left out stay as they are, and each setting given (format, decimals, prefix, suffix, dataLabels, legend, regroup, lowerIsBetter, referenceLines, sortOrder, colors, columnFormats) changes that one and keeps the others. The saved query it reads cannot be changed here: fastero_update_query changes the SQL for every report on that query. To keep this report and add another view of the same query, fastero_create_report; to move it or take it off a dashboard, fastero_update_dashboard. A chartType sent without the columns its chart needs is refused, as is text for anything but a text block; assignments sent without chartType replace the old ones unchecked. Owners, admins and editors of the project can change it; a report with an access list of its own, only the editors that list names. Returns the updated report with its url.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | A new name, the title people see above the chart. | |
| text | No | A text block’s new text, in markdown. Refused for any other report. | |
| colors | No | A colour for each category value the chart draws, say { "East": "#22c55e" }: that bar, slice or tile in it (#rrggbb, #rgb or rgb(r, g, b)). Values left out keep the chart's own colours; on an update the map replaces the chart's, and {} removes it. | |
| format | No | How numbers read: currency adds $, percent adds %, compact abbreviates (1.2K). Defaults to number. | |
| legend | No | auto shows a legend for two series or more. | |
| prefix | No | Written before each number: a currency other than dollars, say "€". | |
| suffix | No | Written after each number: a unit, say " MWh" or " s". | |
| regroup | No | How the numbers combine when the dashboard's period switch groups dates by a longer period: sum for totals and counts (the default), average for rates, prices, averages and percentiles (the default for percent), last for levels such as active users or a balance. | |
| decimals | No | Digits after the decimal point, 0 to 6. Unset, money shows 2 and other numbers the digits they have. | |
| reportId | Yes | A report’s id, from fastero_list_reports, or from a dashboard’s items in fastero_get_dashboard. | |
| vegaLite | No | A Vega-Lite v6 description, only for a chart chartType can't say: several panels, several kinds of mark on one chart, bands, shaded periods, labelled lines, a log or reversed axis, a colour per row, floating bars, side-by-side boxplots. A plain bar, line or pie stays chartType: it is shorter, follows the dashboard's Day/Week/Month switch, and a person can edit it by hand, which nobody can do to this. Rebuild an existing chart this way only when asked for something its type can't do; its old version stays in its history. The rows are the query's, so give no data. Give no config, background, padding, autosize or top-level title: the app decides the look, and the widget's name is the title (title.subtitle stays). About 800 wide in all, in numbers: width 720, height 320. Leave text colours to the theme. Not available: params, selections, url, href, the image and geoshape marks, and nested data. A fixed level line takes y: { datum: 80 }, and x: null under a shared x, or it draws one line per x. Formulas may call only simple functions (format, round, toDate, year and the like). Anything else, and any number people will quote, belongs in the query, so it reads the same in every view. sort: null keeps the query's order. To read well: say the finding in the name or subtitle, with its number, or, on a chart that refreshes, in a text mark worked out from the rows, since typed words go stale; a mid grey plus one accent colour, mid-tones that read on a light and a dark card, more only where they mean something; a target or limit on the chart as a labelled mark; values on the marks or an axis, not both; label only the points the finding rests on; bars start at zero. On a chart that refreshes, keep words and legends off the plot, where a later bar can land on them: a legend with orient "top", a text mark with y: -6 and baseline "bottom". Example: { "width": 720, "height": 320, "encoding": { "x": { "field": "month", "type": "temporal" } }, "layer": [ { "mark": { "type": "bar", "color": "#94a3b8" }, "encoding": { "y": { "field": "orders", "type": "quantitative" } } }, { "mark": { "type": "line", "color": "#3b82f6" }, "encoding": { "y": { "field": "avg_3m", "type": "quantitative" } } }, { "mark": { "type": "rule", "strokeDash": [4, 4] }, "encoding": { "x": null, "y": { "datum": 500 } } } ] } | |
| chartType | No | Same values as fastero_create_report; give the assignments that chart needs with it. | |
| projectId | Yes | The project’s id, from fastero_list_projects. | |
| sortOrder | No | The order a bar, horizontal_bar, pie or waterfall chart draws its categories in: by value, smallest first (asc) or largest first (desc), or as the query returns them (none, the default). A horizontal_bar reads desc from the top. | |
| changeNote | No | For a Vega-Lite chart: what this change does and why, in a few words. People read it in Chart history. | |
| dataLabels | No | Values written on the chart. auto writes them on 12 points or fewer, and a pie's shares always. | |
| assignments | No | Which result columns a chart plots, by chart type: bar, horizontal_bar, stacked_bar {category, value_slot_1, value_slot_2...}; line {xAxis, yAxis, optional value_slot_2, value_slot_3...} (a line each); time_series {date, yAxis1, optional yAxis2}; pie {category, value}; scatter {xAxis, yAxis}; waterfall {category, value}; combo {category, bar_value, line_value}; heatmap {xAxis, yAxis, value}; treemap {name, value}; bubble {xAxis, yAxis, size, optional category}; map {latitude, longitude, optional size, category, label}. Values are column names from the query result. Write the query to return one row per point (aggregate in SQL). | |
| description | No | What the chart shows, in a sentence ("Booked revenue by region, last 90 days"): shown behind an (i) beside its title and read by screen readers. | |
| columnFormats | No | For a table: a number format for each column that holds numbers, say { "Spend": "currency", "Share": "percent" }. | |
| lowerIsBetter | No | For a number card: a fall is good news (costs, cancellations, churn), so a fall shows green. | |
| referenceLines | No | Lines and bands drawn across a bar, horizontal_bar, stacked_bar, line, time_series, combo or scatter chart: { type: "average" } a dashed line at the average of the points drawn; { type: "value", value } a line at a fixed value, such as a target; { type: "band", from, to } a shaded range. Each may have a label and a color (#rrggbb, #rgb or rgb(r, g, b)). The list replaces the chart's; [] removes them. | |
| restoreRevision | No | For a chart with a history: bring back this version, from chartHistoryNotes (fastero_get_report). Restoring is a change too, so it can be undone. |