Creating Visualizations

⚠️ Deprecated — three-tab editor. The three-tab Chart / Data Mapping / Display Options editor described on this page has been replaced by a visual Plotly chart editor that stores its output as a single JSON column called viz_spec. The content below remains for reference on existing assets created under the legacy model. For new visualization assets, use the current editor and refer to Visualization Spec Reference for the schema, column-reference convention, and validation rules.

The legacy viz_chart_type / viz_dep_var_col_name / viz_indep_var_col_name / etc. columns still exist on the asset record and are returned by the API for read access — integrations that read those fields don't break — but they are no longer used for visualization rendering. Only viz_spec drives the renderer.

Visualization assets return chart-ready data rendered as a static image (SVG/PNG). Unlike Calculation assets which run SQL, Visualization assets are configured through a visual editor — you select a table, map columns to chart axes/values, and tune display options without writing any queries.

External API connections do not support Visualization assets. Use a standard database connection (BigQuery, Snowflake, Redshift, etc.) for visualizations.

Three-Tab Configuration UI

The visualization editor has three tabs that unlock progressively:

Tab	What You Configure	Unlocks When
Chart	Data source (schema.table) and chart type	Always available
Data Mapping	Which columns map to which chart axes	After a table is selected
Display Options	Aggregation, sorting, limits, colors, toggles	After a chart type is selected

Tab 1 — Chart

Data Source

Select the database schema and table that contains your data. Spartera loads all available schemas from your connected database and lets you drill down to the specific table.

Format: schema_name.table_name

Chart Type

Type	Best For
BAR	Comparing values across categories (products, regions, departments)
LINE	Showing trends over time (revenue by month, users over time)
PIE	Showing proportions of a whole (market share, budget allocation)
DOUGHNUT	Same as Pie, with a hollow center — cleaner for dashboards
SCATTER	Revealing correlations between two numeric variables

Tab 2 — Data Mapping

Each chart type requires different column mappings. Spartera filters available columns by data type so you only see compatible options for each axis.

BAR

Axis	Field	Accepted Types
Value	Height of each bar	Any (numeric recommended)
Category	The groups being compared	Any

Best for: "Show me revenue by product category" or "Orders per region."

LINE

Axis	Field	Accepted Types
Value (Y-Axis)	The metric being tracked	NUMERIC only (INTEGER, FLOAT, DECIMAL, etc.)
Time Series (X-Axis)	The time dimension	DATE, DATETIME, TIMESTAMP only

Best for: "Show me monthly churn rate over the past year."

PIE / DOUGHNUT

Axis	Field	Accepted Types
Value (Size)	Determines how large each slice is	NUMERIC only
Labels (Categories)	Names for each slice	TEXT only (STRING, VARCHAR, CHAR)

Best for: "Show me market share by competitor" or "Revenue split by product line."

SCATTER

Axis	Field	Accepted Types
Y-Axis Value	Vertical position of each point	NUMERIC only
X-Axis Value	Horizontal position of each point	NUMERIC only
Point Size (optional)	Size of each data point	NUMERIC only

Best for: "Show me the relationship between ad spend and revenue" or "Customer age vs. lifetime value."

Field Type Reference

Category	Accepted SQL Types
NUMERIC	INTEGER, FLOAT, NUMERIC, NUMBER, DECIMAL, REAL, DOUBLE
DATE	DATE, DATETIME, TIMESTAMP
TEXT	STRING, VARCHAR, CHAR, TEXT

Tab 3 — Display Options

Data Transformation

Data Aggregation

Controls how multiple data points are combined into a single value per category or time period.

Option	Description	When to Use
None	Shows raw data rows	When your data is already pre-aggregated
Sum	Adds all values together	Total revenue per region
Average	Mean of all values	Average order value per month
Count	Number of records	Orders per category
Minimum	Lowest value	Cheapest product per category
Maximum	Highest value	Peak traffic per day

Sort Direction

Option	Result
No Sorting	Data appears in source order
Ascending	Smallest to largest (A→Z, 1→10)
Descending	Largest to smallest (Z→A, 10→1)

Descending + Category Limit is a common combination for "Top N" charts.

Category Limit

Limits how many data points are displayed. Set to 0 to show all data.

Chart Type	What the Limit Controls
BAR	Max number of bars
PIE / DOUGHNUT	Max number of slices
LINE	Max number of data points
SCATTER	Max number of points

Use with Filter Direction to specify whether the limit shows the top N or bottom N items.

Filter Direction

Option	Result
Top N	Show the N highest values
Bottom N	Show the N lowest values

Example: Category Limit = 10, Filter Direction = Top N → shows the 10 highest-value items.

Appearance

Color Scheme — Choose from a set of curated palettes. Applied consistently across all data series in the chart.

Value	Description
`Default`	Spartera default palette
`Sequential`	Single-hue gradient, best for ordered data (low → high)
`Diverging`	Two-hue gradient from a midpoint, best for above/below comparisons
`Categorical`	Distinct colors for unrelated categories
`Monochrome`	Single color in varying shades
`Pastel`	Softer, lighter tones
`Dark`	High-contrast dark palette
`Light`	Subtle light palette

Show Legend (default: on) — Displays a key identifying each data series. Recommended for charts with multiple categories.

Show Grid Lines (default: on) — Adds horizontal and vertical reference lines to make it easier to read values from axes.

Chart-Specific Options

LINE and SCATTER

Show Trendline — Overlays a linear regression line showing the overall direction of the data. Helps identify whether values are generally increasing, decreasing, or flat.

Smooth Lines (LINE only) — Uses spline interpolation to create curved lines instead of sharp angles between data points. Makes the chart look more polished, but can obscure sudden changes in the data.

BAR

Stacked Bars — Stacks multiple data series vertically instead of side-by-side. Best for showing part-to-whole relationships and cumulative totals across categories.

Configuration Summary

As you configure your visualization, a summary chip bar appears at the top of the editor showing your current selections — chart type, table, column mappings, and active display options. Clicking any chip jumps you directly to that setting.

Example Configurations

Monthly Revenue Trend

Setting	Value
Chart Type	LINE
Table	`analytics.monthly_sales`
Y-Axis (Value)	`revenue_usd`
X-Axis (Time Series)	`month_date`
Aggregation	Sum
Sort	Ascending
Smooth Lines	On
Show Trendline	On

Top 10 Products by Sales

Setting	Value
Chart Type	BAR
Table	`sales.product_summary`
Value	`total_sales`
Category	`product_name`
Aggregation	Sum
Sort	Descending
Category Limit	10
Filter Direction	Top N

Market Share by Region

Setting	Value
Chart Type	PIE
Table	`market.regional_revenue`
Value (Size)	`revenue_usd`
Labels (Categories)	`region_name`
Aggregation	Sum
Category Limit	8
Filter Direction	Top N

Customer Age vs. Lifetime Value

Setting	Value
Chart Type	SCATTER
Table	`customers.lifetime_metrics`
Y-Axis	`lifetime_value_usd`
X-Axis	`age_at_signup`
Point Size	`total_orders`
Show Trendline	On

Tips

Always check your aggregation setting. If your source table has one row per transaction and you're charting by month, you almost certainly need Sum or Average aggregation — otherwise each month shows only one data point.

Use Category Limit + Descending for "Top N" insights. This is the most common pattern for marketplace visualizations — buyers want to see the leaders, not every row.

Pie charts work best with 5–8 slices. More than 8 slices makes them hard to read. Use Category Limit to cap them.

Smooth Lines can hide volatility. If your data has meaningful spikes (stock prices, traffic anomalies), keep Smooth Lines off so the raw shape is visible.

Scatter plots require clean numeric data. Nulls and non-numeric values in either axis field will cause points to be dropped. Clean your data upstream before building scatter visualizations.

Visualization Spec Reference — The current schema for visualization assets. Start here for new assets.
Assets Overview — Asset types and key concepts
Creating Assets — Full asset creation guide including Calculation assets
Testing and Validation — Preview your visualization before publishing
Publishing to Marketplace — Going live