Save chart to dashboard
fastero_save_chartKeep a chart on a dashboard in one step: saves the query, makes the chart and adds it at the bottom of the dashboard. dashboard.id picks an existing dashboard; dashboard.name alone uses the project's dashboard of that name, or creates it. Same arguments as fastero_show_chart; the query must be read-only. Returns the new query’s and chart’s ids, and the dashboard’s id, name, url (the page where a signed-in member opens it) and whether it was created.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One read-only statement returning one row per point: aggregate in SQL (GROUP BY), and ORDER BY the x axis. | |
| title | Yes | The chart’s title, as people will see 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. | |
| 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 | line or time_series for a measure over time; bar to compare categories (horizontal_bar for long labels, stacked_bar for the parts of each); pie or treemap for shares of one whole (a pie shows the 7 largest slices and groups the rest as Other); waterfall for steps that add up to a total; combo for two measures on different scales; scatter to relate two measures, bubble for three; heatmap for one measure across two categories. number for a number card: over a series (assignments { date, value }, one row per period) it shows the latest value, its change against the previous period and a trend line. | |
| dashboard | Yes | Where Save puts the chart; its button names it. { id, name } for an existing dashboard (fastero_list_dashboards); { name } alone for a new one, which Save creates. | |
| projectId | Yes | The project the chart is saved into if the person keeps it: a 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. | |
| 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). | |
| connectionId | Yes | A data connection’s id, from fastero_list_connections; fastero_create_file_connection makes one of an uploaded CSV or Excel file. | |
| 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. |