dashboard

package
v0.0.0-edge.45.cd52bb1 Latest Latest
Warning

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

 Go to latest Published: Jun 25, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	WidgetTypeMetric  = "metric"
	WidgetTypeChart   = "chart"
	WidgetTypeTable   = "table"
	WidgetTypeText    = "text"
	WidgetTypeDivider = "divider"
	WidgetTypeImage   = "image"
)

Widget type constants.

Variables

View Source 
var DateExpressionPattern = regexp.MustCompile(`^(TODAY([+-]\d+)?|\d{4}-\d{2}-\d{2})$`)

Functions

func IsTSXFile 

func IsTSXFile(name string) bool

IsTSXFile checks if a filename matches the .dashboard.tsx convention.

func ResolveDateExpression added in v0.2.3 

func ResolveDateExpression(expr string) string

func ResolveDatePreset 

func ResolveDatePreset(key string) map[string]any

ResolveDatePreset converts a preset key like "last_30_days" into a map with "start" and "end" date strings. Returns nil if the key is unknown.

func Validate 

func Validate(d *Dashboard) error

Validate checks a dashboard definition for correctness.

func ValidateAll 

func ValidateAll(dashboards []*Dashboard) error

Types

type AxisEncoding added in v0.2.1 

type AxisEncoding struct {
	Field  any    `yaml:"field" json:"field"`
	Type   string `yaml:"type,omitempty" json:"type,omitempty"`
	Title  string `yaml:"title,omitempty" json:"title,omitempty"`
	Format string `yaml:"format,omitempty" json:"format,omitempty"`
}

func (*AxisEncoding) FieldList added in v0.2.1 

func (a *AxisEncoding) FieldList() []string

func (*AxisEncoding) FieldString added in v0.2.1 

func (a *AxisEncoding) FieldString() string

func (*AxisEncoding) MarshalJSON added in v0.2.1 

func (a *AxisEncoding) MarshalJSON() ([]byte, error)

func (*AxisEncoding) MarshalYAML added in v0.2.1 

func (a *AxisEncoding) MarshalYAML() (any, error)

func (*AxisEncoding) UnmarshalJSON added in v0.2.1 

func (a *AxisEncoding) UnmarshalJSON(data []byte) error

func (*AxisEncoding) UnmarshalYAML added in v0.2.1 

func (a *AxisEncoding) UnmarshalYAML(node *yaml.Node) error

type ColorEncoding added in v0.2.2 

type ColorEncoding struct {
	Field string `yaml:"field" json:"field"`
}

func (*ColorEncoding) FieldString added in v0.2.2 

func (c *ColorEncoding) FieldString() string

type Dashboard 

type Dashboard struct {
	Schema      string            `yaml:"schema,omitempty" json:"schema,omitempty"`
	Name        string            `yaml:"name" json:"name"`
	Description string            `yaml:"description,omitempty" json:"description,omitempty"`
	Connection  string            `yaml:"connection,omitempty" json:"connection,omitempty"`
	Model       string            `yaml:"model,omitempty" json:"model,omitempty"`
	Models      map[string]string `yaml:"models,omitempty" json:"models,omitempty"`
	Filters     []Filter          `yaml:"filters,omitempty" json:"filters,omitempty"`
	Queries     map[string]Query  `yaml:"queries,omitempty" json:"queries,omitempty"`
	Rows        []Row             `yaml:"rows" json:"rows"`

	// FilePath is the source file path, not serialized to JSON for API consumers.
	FilePath string `yaml:"-" json:"-"`

	// FileType indicates the source format: "yaml" or "tsx".
	FileType string `yaml:"-" json:"file_type,omitempty"`
	// contains filtered or unexported fields
}

Dashboard represents a complete dashboard definition loaded from YAML.

func FindByName 

func FindByName(dashboards []*Dashboard, name string) *Dashboard

FindByName returns the dashboard with the given name from a slice, or nil.

func LoadDir 

func LoadDir(dir string, opts ...TSXOption) ([]*Dashboard, error)

LoadDir discovers and loads all dashboard files from the project's dashboards directory.

func LoadFile 

func LoadFile(path string) (*Dashboard, error)

LoadFile loads a single dashboard YAML file.

func LoadOneByName 

func LoadOneByName(dir, name string, opts ...TSXOption) (*Dashboard, error)

LoadOneByName finds a dashboard by name using a two-pass approach: first a cheap metadata scan (no query execution) to find the file path, then a full load of just that one file. Returns nil, nil if not found.

func LoadTSXFile 

func LoadTSXFile(path string, opts ...TSXOption) (*Dashboard, error)

LoadTSXFile loads a single .dashboard.tsx file by transpiling it with esbuild and executing it with goja to produce a Dashboard struct.

func (*Dashboard) DateRangeFilterName 

func (d *Dashboard) DateRangeFilterName() string

DateRangeFilterName returns the name of the first date-range filter, or "".

func (*Dashboard) DefaultFilters 

func (d *Dashboard) DefaultFilters() map[string]any

DefaultFilters returns a map of filter names to their default values. For date-range filters, string defaults like "last_30_days" are resolved to {start, end} maps so that query templating works correctly.

func (*Dashboard) ResolveSemanticModel 

func (d *Dashboard) ResolveSemanticModel(ref string) (*sem.Model, string, error)

func (*Dashboard) ResolveWidgetSemanticJob 

func (d *Dashboard) ResolveWidgetSemanticJob(w *Widget) (*SemanticJob, bool, error)

func (*Dashboard) SetProjectContext 

func (d *Dashboard) SetProjectContext(projectRoot string, semanticModels map[string]*sem.Model, semanticInvalid map[string]error)

type Filter 

type Filter struct {
	Name     string         `yaml:"name" json:"name"`
	Type     string         `yaml:"type" json:"type"`
	Multiple bool           `yaml:"multiple,omitempty" json:"multiple,omitempty"`
	Default  any            `yaml:"default,omitempty" json:"default,omitempty"`
	Options  *FilterOptions `yaml:"options,omitempty" json:"options,omitempty"`
}

type FilterOptions 

type FilterOptions struct {
	Values     []string `yaml:"values,omitempty" json:"values,omitempty"`
	Query      string   `yaml:"query,omitempty" json:"query,omitempty"`
	Connection string   `yaml:"connection,omitempty" json:"connection,omitempty"`
	Presets    []string `yaml:"presets,omitempty" json:"presets,omitempty"` // date-range: which presets to show
}

type NoQueryError 

type NoQueryError struct {
	Widget string
}

func (*NoQueryError) Error 

func (e *NoQueryError) Error() string

type ProjectPaths 

type ProjectPaths struct {
	RootDir      string
	DashboardDir string
	SemanticDir  string
	ThemesDir    string
}

func ResolveProjectPaths 

func ResolveProjectPaths(dir string) ProjectPaths

func ResolveProjectPathsForFile 

func ResolveProjectPathsForFile(path string) ProjectPaths

type Query 

type Query struct {
	SQL        string                 `yaml:"sql,omitempty" json:"sql,omitempty"`
	Connection string                 `yaml:"connection,omitempty" json:"connection,omitempty"`
	Model      string                 `yaml:"model,omitempty" json:"model,omitempty"`
	Dimensions []SemanticDimensionRef `yaml:"dimensions,omitempty" json:"dimensions,omitempty"`
	Metrics    []string               `yaml:"metrics,omitempty" json:"metrics,omitempty"`
	Filters    []SemanticQueryFilter  `yaml:"filters,omitempty" json:"filters,omitempty"`
	Segments   []string               `yaml:"segments,omitempty" json:"segments,omitempty"`
	Sort       []SemanticSort         `yaml:"sort,omitempty" json:"sort,omitempty"`
	Limit      int                    `yaml:"limit,omitempty" json:"limit,omitempty"`
}

Query represents a named query definition.

func (*Query) IsSemantic 

func (q *Query) IsSemantic() bool

type QueryNotFoundError 

type QueryNotFoundError struct {
	Name   string
	Widget string
}

func (*QueryNotFoundError) Error 

func (e *QueryNotFoundError) Error() string

type Row 

type Row struct {
	Tab     string   `yaml:"tab,omitempty" json:"tab,omitempty"`
	Height  any      `yaml:"height,omitempty" json:"height,omitempty"`
	Widgets []Widget `yaml:"widgets" json:"widgets"`
}

type SemanticDimensionRef 

type SemanticDimensionRef struct {
	Name        string `yaml:"name" json:"name"`
	Granularity string `yaml:"granularity,omitempty" json:"granularity,omitempty"`
}

type SemanticJob 

type SemanticJob struct {
	Model      *sem.Model
	ModelName  string
	Connection string
	Query      sem.Query
}

type SemanticQueryFilter 

type SemanticQueryFilter struct {
	Dimension  string `yaml:"dimension,omitempty" json:"dimension,omitempty"`
	Operator   string `yaml:"operator,omitempty" json:"operator,omitempty"`
	Value      any    `yaml:"value,omitempty" json:"value,omitempty"`
	Expression string `yaml:"expression,omitempty" json:"expression,omitempty"`
}

type SemanticSort 

type SemanticSort struct {
	Name      string `yaml:"name" json:"name"`
	Direction string `yaml:"direction,omitempty" json:"direction,omitempty"`
}

type TSXOption 

type TSXOption func(*tsxConfig)

TSXOption configures TSX loading behavior.

func WithQueryFunc 

func WithQueryFunc(fn func(connection, sql string) (map[string]interface{}, error)) TSXOption

WithQueryFunc provides a query function for load-time SQL execution.

type TableColumn 

type TableColumn struct {
	Name   string `yaml:"name" json:"name"`
	Label  string `yaml:"label,omitempty" json:"label,omitempty"`
	Format string `yaml:"format,omitempty" json:"format,omitempty"`
}

type ValidationError 

type ValidationError struct {
	Dashboard string
	Errors    []string
}

ValidationError holds all validation issues for a dashboard.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type ValidationSetError 

type ValidationSetError struct {
	Errors []error
}

func (*ValidationSetError) Error 

func (e *ValidationSetError) Error() string

type ValueEncoding added in v0.2.1 

type ValueEncoding struct {
	Field  string `yaml:"field" json:"field"`
	Type   string `yaml:"type,omitempty" json:"type,omitempty"`
	Format string `yaml:"format,omitempty" json:"format,omitempty"`
}

func (*ValueEncoding) FieldString added in v0.2.1 

func (v *ValueEncoding) FieldString() string

func (*ValueEncoding) MarshalJSON added in v0.2.1 

func (v *ValueEncoding) MarshalJSON() ([]byte, error)

func (*ValueEncoding) MarshalYAML added in v0.2.1 

func (v *ValueEncoding) MarshalYAML() (any, error)

func (*ValueEncoding) UnmarshalJSON added in v0.2.1 

func (v *ValueEncoding) UnmarshalJSON(data []byte) error

func (*ValueEncoding) UnmarshalYAML added in v0.2.1 

func (v *ValueEncoding) UnmarshalYAML(node *yaml.Node) error

type Widget 

type Widget struct {
	ID          string `yaml:"id,omitempty" json:"id,omitempty"`
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description,omitempty" json:"description,omitempty"`
	Type        string `yaml:"type" json:"type"`
	Col         int    `yaml:"col,omitempty" json:"col,omitempty"`

	// Query source (pick one)
	QueryRef  string `yaml:"query,omitempty" json:"query,omitempty"` // reference to queries map key
	SQL       string `yaml:"sql,omitempty" json:"sql,omitempty"`
	MetricRef string `yaml:"metric,omitempty" json:"metric,omitempty"` // reference to metrics map key
	Model     string `yaml:"model,omitempty" json:"model,omitempty"`

	// Inline static data — an alternative to a query source. A widget with
	// Data renders without a connection or SQL; encoding fields (x/y/value/
	// label/columns) reference the column names in Data. Used for hardcoded
	// or sample dashboards, e.g. before a warehouse is connected.
	Data *WidgetData `yaml:"data,omitempty" json:"data,omitempty"`

	// Connection override for inline queries
	Connection string `yaml:"connection,omitempty" json:"connection,omitempty"`

	// Declarative chart fields (use with source + metrics)
	Dimension   string                 `yaml:"dimension,omitempty" json:"dimension,omitempty"` // GROUP BY column
	Granularity string                 `yaml:"granularity,omitempty" json:"granularity,omitempty"`
	Dimensions  []SemanticDimensionRef `yaml:"dimensions,omitempty" json:"dimensions,omitempty"`
	MetricRefs  []string               `yaml:"metrics,omitempty" json:"metrics,omitempty"` // metric names to aggregate
	Filters     []SemanticQueryFilter  `yaml:"filters,omitempty" json:"filters,omitempty"`
	Segments    []string               `yaml:"segments,omitempty" json:"segments,omitempty"`
	Sort        []SemanticSort         `yaml:"sort,omitempty" json:"sort,omitempty"`
	Limit       int                    `yaml:"limit,omitempty" json:"limit,omitempty"` // LIMIT for dimensional queries

	// Chart fields
	Chart      string         `yaml:"chart,omitempty" json:"chart,omitempty"` // line, bar, area, pie, scatter, bubble, combo, histogram, boxplot, funnel, sankey, heatmap, calendar, sparkline, waterfall, xmr, dumbbell, gauge, treemap, radar, candlestick
	X          *AxisEncoding  `yaml:"x,omitempty" json:"x,omitempty"`
	Y          *AxisEncoding  `yaml:"y,omitempty" json:"y,omitempty"`
	Label      string         `yaml:"label,omitempty" json:"label,omitempty"` // for pie/funnel/treemap
	Value      *ValueEncoding `yaml:"value,omitempty" json:"value,omitempty"` // metric: the value; pie/funnel/heatmap/calendar/treemap/gauge: value column
	Color      *ColorEncoding `yaml:"color,omitempty" json:"color,omitempty"`
	Stacked    bool           `yaml:"stacked,omitempty" json:"stacked,omitempty"`
	Normalized bool           `yaml:"normalized,omitempty" json:"normalized,omitempty"`
	Horizontal bool           `yaml:"horizontal,omitempty" json:"horizontal,omitempty"`
	Size       string         `yaml:"size,omitempty" json:"size,omitempty"`
	Source     string         `yaml:"source,omitempty" json:"source,omitempty"` // sankey: source column
	Target     string         `yaml:"target,omitempty" json:"target,omitempty"` // sankey: target column, gauge: target (max) column
	Bins       int            `yaml:"bins,omitempty" json:"bins,omitempty"`     // histogram: number of bins
	Lines      []string       `yaml:"lines,omitempty" json:"lines,omitempty"`   // combo: which y series render as lines
	YMin       string         `yaml:"yMin,omitempty" json:"yMin,omitempty"`     // xmr: min control limit column
	YMax       string         `yaml:"yMax,omitempty" json:"yMax,omitempty"`     // xmr: max control limit column
	Open       string         `yaml:"open,omitempty" json:"open,omitempty"`     // candlestick: open price column
	High       string         `yaml:"high,omitempty" json:"high,omitempty"`     // candlestick: high price column
	Low        string         `yaml:"low,omitempty" json:"low,omitempty"`       // candlestick: low price column
	Close      string         `yaml:"close,omitempty" json:"close,omitempty"`   // candlestick: close price column

	// Table fields
	Columns []TableColumn `yaml:"columns,omitempty" json:"columns,omitempty"`

	// Text fields
	Content string `yaml:"content,omitempty" json:"content,omitempty"`

	// Image fields
	Src string `yaml:"src,omitempty" json:"src,omitempty"`
	Alt string `yaml:"alt,omitempty" json:"alt,omitempty"`
}

Widget represents a single dashboard widget. Query resolution priority: query (named ref) > sql (inline) > data (static).

func (*Widget) ColorField added in v0.2.2 

func (w *Widget) ColorField() string

func (*Widget) HasInlineData added in v0.4.0 

func (w *Widget) HasInlineData() bool

HasInlineData reports whether the widget carries static inline data.

func (*Widget) IsSemantic 

func (w *Widget) IsSemantic() bool

func (*Widget) ResolvedQuery 

func (w *Widget) ResolvedQuery(dashboard *Dashboard) (sql, connection string, err error)

ResolvedQuery returns the SQL and connection for this widget, resolving named query references. Widgets with MetricRef are handled separately and should not call this method.

func (*Widget) ValueField added in v0.2.1 

func (w *Widget) ValueField() string

func (*Widget) XField added in v0.2.1 

func (w *Widget) XField() string

func (*Widget) YFields added in v0.2.1 

func (w *Widget) YFields() []string

type WidgetData added in v0.4.0 

type WidgetData struct {
	Columns []string `yaml:"columns" json:"columns"`
	Rows    [][]any  `yaml:"rows" json:"rows"`
}

WidgetData holds inline result data for a widget so it can render without a connection. Columns are column names; each entry in Rows is positional and must have one value per column. This mirrors the {columns, rows} shape the frontend uses for executed query results.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.