Create report
fastero_create_reportCreate a report (a dashboard widget) from a saved query: a table, a number, a map or a chart. A chart or map needs assignments naming the result columns it plots, or it is refused. For a chart chartType can’t say, vegaLite instead of chartType and assignments. Column names become the labels people read, so alias them in SQL as they should appear ("Revenue", not revenue_sum). Or a text block: chartType text with text, a heading or note in markdown that sits between charts; it reads no query. fastero_update_dashboard places it on a dashboard. Returns the report with its _id and url, the chart’s own page. Starting from SQL, fastero_save_chart saves the query, makes the chart and places it in one call.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| text | No | For chartType text: the heading or note, in markdown (## for a heading). Up to 5,000 characters. | |
| 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". | |
| queryId | No | A saved query’s id, from fastero_list_queries. | |
| 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 | bar, horizontal_bar, stacked_bar, line, time_series, pie, scatter, waterfall, combo, heatmap, treemap, bubble for a chart (with assignments); or table; or number, a number card, which over a series (assignments { date, value }, one row per period) shows the latest value, its change against the previous period and a trend line; or map (assignments { latitude, longitude }); or kpi, gauge, scorecard, summary; or text for a text block. Defaults to table. 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. | |
| 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. |