Documentation
¶
Overview ¶
Package chartquery turns a Flint chart spec bound to a metrics view (the arguments external MCP clients pass to create_chart and chart_data) into the metrics view queries that fetch its data, and runs them within fixed budgets.
The queries follow from the kinds of the bound fields: a top-N query for each dimension on an axis, series or facet channel, a main query that groups by every bound dimension (time fields floored to the grain) and keeps the selected values, and a total and an "Other" query for a pie or donut chart (see BuildFlint).
The package is pure: it builds metricsview.Query values and runs them through a caller-provided Runner.
Index ¶
Constants ¶
const ( // MaxNominalValues caps the values of a dimension on an axis. MaxNominalValues = 50 // MaxColorValues caps the values of a dimension on a series channel (color, group, shape or strokeDash). MaxColorValues = 20 // MaxFacetValues caps the values of a dimension on a facet channel (column or row). MaxFacetValues = 8 // MaxRows caps the rows of the main query. MaxRows = 1500 // MaxDataBytes caps the JSON size of the chart data, the rows and the domain values together; rows are trimmed from the tail to fit. // It leaves room for the rest of a result under the size at which hosts stop passing a result through // (Claude writes one over about 150,000 characters to a file, which the widget never receives). MaxDataBytes = 100 << 10 )
Budgets for the chart data. They bound the number of categories, rows and bytes a chart result may carry, since MCP hosts cap tool results and the widget renders every row it receives.
const DetailChannel = "detail"
DetailChannel is a Rill extension to Flint's channels: a dimension bound to it sets the grain of the rows (one row per value) without being drawn, which charts of individual observations need on aggregated data. Chart types that have their own detail channel keep its meaning; for the others the widget drops it before compiling.
const PrevSuffix = "_prev"
PrevSuffix names the comparison period value of a measure; the widget reads the same suffix.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FieldKind ¶
type FieldKind string
FieldKind is the role of a metrics view field in a chart: a measure, a dimension, or a time dimension.
type FlintCatalog ¶
type FlintCatalog struct {
FlintVersion string `json:"flint_version"`
ChartTypes []*FlintChartType `json:"chart_types"`
}
FlintCatalog lists the Flint chart types create_chart accepts, with the channels and properties of each. It is generated from the installed flint-chart package by web-mcp-app/scripts/generate-flint-catalog.mjs, so the server validates against the same compiler the widget renders with.
func (*FlintCatalog) ChartType ¶
func (c *FlintCatalog) ChartType(name string) *FlintChartType
ChartType returns the catalog entry of a chart type, or nil when the name is unknown.
func (*FlintCatalog) Names ¶
func (c *FlintCatalog) Names() []string
Names returns the chart type names in catalog order.
type FlintChartType ¶
type FlintChartType struct {
Name string `json:"name"`
Channels []string `json:"channels"`
Properties []*FlintProperty `json:"properties"`
}
FlintChartType is a chart type of the catalog.
func (*FlintChartType) AcceptsChannel ¶
func (ct *FlintChartType) AcceptsChannel(channel string) bool
AcceptsChannel reports whether a chart spec may bind the channel: one of the chart type's own channels, or the detail extension.
type FlintEncoding ¶
type FlintEncoding struct {
Channel string
Field string
Kind FieldKind
// Type is the type the spec declares for the field (quantitative, nominal, ordinal or temporal), or empty.
// A dimension declared temporal is a time field; the other types only affect how the widget draws the field.
Type string
// Limit is the top-N limit the spec asks for on a dimension channel, or 0 for the default.
Limit int
// SortOrder is "ascending", "descending" or empty; SortBy names the channel or the field the values are sorted by.
SortOrder string
SortBy string
}
FlintEncoding is one field bound to a channel.
type FlintProperty ¶
type FlintProperty struct {
Key string `json:"key"`
Label string `json:"label"`
// Type is "continuous", "discrete" or "binary".
Type string `json:"type"`
Min *float64 `json:"min,omitempty"`
Max *float64 `json:"max,omitempty"`
Step *float64 `json:"step,omitempty"`
Options []*FlintPropertyOption `json:"options,omitempty"`
Default any `json:"default,omitempty"`
}
FlintProperty is a tunable property of a chart type (a key of chartProperties in a chart spec).
type FlintPropertyOption ¶
FlintPropertyOption is a value of a discrete property.
type FlintSpec ¶
type FlintSpec struct {
ChartType string
MetricsView string
TimeRange *TimeRange
ComparisonTimeRange *TimeRange
Where *metricsview.Expression
// TimeGrain floors the bound time fields. It is set only when one is bound, defaulting to day.
TimeGrain metricsview.TimeGrain
// Encodings are the channel bindings in the channel order of the chart type (the detail extension last);
// a channel bound to an array of fields has one entry per field.
Encodings []*FlintEncoding
}
FlintSpec is a parsed Flint chart spec (chartType and encodings) bound to a metrics view through the data block of create_chart. It is not normalized per chart type: the queries follow from the kinds of the bound fields alone.
func ParseFlintSpec ¶
ParseFlintSpec parses the chart_spec and data arguments of a Flint chart call. kinds classifies the metrics view's fields; a field the chart binds must be in it. It validates the chart type and channels against the catalog, what the queries need from the data block, and that the chart can draw what it binds (see checkFlintChart).
func (*FlintSpec) Dimensions ¶
func (s *FlintSpec) Dimensions() []*FlintEncoding
Dimensions returns the bindings of dimensions other than time fields, in channel order. A dimension bound to several channels appears once per channel.
func (*FlintSpec) FieldOn ¶
func (s *FlintSpec) FieldOn(channel string) *FlintEncoding
FieldOn returns the first field bound to a channel, or nil.
func (*FlintSpec) Fields ¶
Fields returns the names of the metrics view fields the chart binds, in channel order and without duplicates.
func (*FlintSpec) Measures ¶
Measures returns the bound measures in channel order, without duplicates.
func (*FlintSpec) TimeGrainName ¶
TimeGrainName returns the TIME_GRAIN_* name of the resolved grain, or an empty string when no time field is bound.
type OtherQuery ¶
type OtherQuery struct {
// Field is the slice dimension and Measure the measure the slices are sized by.
Field string
Measure string
// Query builds the query from the selected domain values, which it leaves out.
Query func(domain map[string][]any) *metricsview.Query
}
OtherQuery aggregates the measure of a pie or donut chart over the values of its slice dimension that the top-N query cut. Execute adds the result as an "Other" slice when the measure adds up to the chart's total (the "total" query of Plan.Extra).
type Output ¶
type Output struct {
// TimeGrain is the TIME_GRAIN_* name used to floor temporal fields, or empty when none is used.
TimeGrain string
// Data are the rows of the main query keyed by field name.
// Comparison values are under <measure>_prev and temporal values are RFC3339 UTC strings of the bucket start.
Data []map[string]any
// DomainValues lists the ordered values selected for each top-N dimension,
// followed by the label of the "Other" slice when one was added (see Plan.Other).
DomainValues map[string][]any
// Limits is the effective top-N limit of each dimension after defaults and caps,
// keyed by the channel of the chart spec (x, y, color, column, ...) and then by field,
// so that a renderer can show the limit that was applied.
Limits map[string]map[string]int
// Totals holds the total of each measure for pie and donut charts.
Totals map[string]any
// Types maps the columns of the main query to their type codes.
Types map[string]string
ResolvedTimeRange *TimeRange
ResolvedComparisonTimeRange *TimeRange
// Truncated reports whether any budget cut the data; TruncationWarning explains what was cut.
// RowsTruncated reports whether the rows of the main query were cut (by the row cap or the byte budget) as opposed to a top-N cut;
// a temporal chart then keeps its newest buckets, so its time axis is incomplete at the start.
Truncated bool
RowsTruncated bool
TruncationWarning string
}
Output is the chart-ready data produced by Execute.
type Plan ¶
type Plan struct {
// Spec is the chart spec the queries were planned for.
Spec *FlintSpec
// TopN are pre-queries that select the values of a dimension on an axis, series or facet channel.
// They run in order before the main query, and their values filter it and order its categories.
TopN []TopNQuery
// Main builds the main query from the selected domain values (keyed by field name).
Main func(domain map[string][]any) *metricsview.Query
// Extra are queries whose single row is returned as totals (pie and donut charts), keyed by name.
Extra map[string]*metricsview.Query
// Other aggregates the values of a pie or donut chart's slice dimension that its top-N query cut, for an "Other" slice (see Execute).
Other *OtherQuery
// RowLimit caps the rows returned from the main query; the query itself asks for one more row to detect truncation.
RowLimit int
// TimeField is the temporal field the main query is ordered by, newest first, when the chart has a time axis.
// Ordering newest first makes the row cap and the byte budget drop the oldest rows; Execute restores ascending order.
TimeField string
}
Plan is the set of queries that fetch a chart's data.
func BuildFlint ¶
BuildFlint plans the queries for a Flint chart spec from the kinds of its bound fields: a top-N query for each dimension on an axis, series or facet channel, and a main query that groups by every bound dimension (time fields floored to the grain), selects every bound measure (with its comparison value when a comparison is set), filters to the top-N values and keeps the row cap. A pie or donut chart also gets a total query and an "Other" query (see Plan.Other).
type Result ¶
type Result struct {
// Rows are the result rows keyed by column name.
Rows []map[string]any
// Types maps column names to their type code without the CODE_ prefix (e.g. STRING, INT64, TIMESTAMP).
Types map[string]string
// TimeRange and ComparisonTimeRange are the time ranges the query resolved to.
TimeRange *TimeRange
ComparisonTimeRange *TimeRange
}
Result is the outcome of one query.
type Runner ¶
Runner runs a metrics view query. It is implemented by the AI tools on top of the runtime's metrics resolver.
type TimeRange ¶
type TimeRange struct {
Start time.Time `json:"start"`
End time.Time `json:"end"`
TimeZone string `json:"time_zone,omitempty"`
}
TimeRange is an absolute time range with an optional IANA time zone.
type TopNQuery ¶
type TopNQuery struct {
// Channel is the channel of the chart spec whose values are selected (x, y, color, column, ...).
Channel string `json:"channel"`
// Field is the dimension whose values are selected.
Field string `json:"field"`
// Limit is the number of values to keep. The query asks for one more row to detect truncation.
Limit int `json:"limit"`
Query *metricsview.Query `json:"query"`
}
TopNQuery selects the values of one dimension.