chartquery

package
v0.92.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

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

View Source
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.

View Source
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.

View Source
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.

const (
	FieldKindMeasure   FieldKind = "measure"
	FieldKindDimension FieldKind = "dimension"
	FieldKindTime      FieldKind = "time"
)

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 Catalog

func Catalog() *FlintCatalog

Catalog returns the embedded Flint chart catalog.

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

type FlintPropertyOption struct {
	Value any    `json:"value"`
	Label string `json:"label"`
}

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

func ParseFlintSpec(chartSpec, data map[string]any, kinds map[string]FieldKind) (*FlintSpec, error)

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

func (s *FlintSpec) Fields() []string

Fields returns the names of the metrics view fields the chart binds, in channel order and without duplicates.

func (*FlintSpec) Measures

func (s *FlintSpec) Measures() []string

Measures returns the bound measures in channel order, without duplicates.

func (*FlintSpec) TimeField

func (s *FlintSpec) TimeField() string

TimeField returns the first bound time field, or an empty string.

func (*FlintSpec) TimeGrainName

func (s *FlintSpec) TimeGrainName() string

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.

func Execute

func Execute(ctx context.Context, plan *Plan, runner Runner) (*Output, error)

Execute runs the plan's queries in order and assembles the chart data within the budgets.

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

func BuildFlint(s *FlintSpec) (*Plan, error)

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

type Runner interface {
	Query(ctx context.Context, q *metricsview.Query) (*Result, error)
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL