Assets Overview

An analytics asset is the core insight unit of Spartera. It's a named, versioned piece of SQL logic that runs inside your database and returns either:

A single value (a number, a string, a percentage) — a Calculation asset
A chart or graph (PNG/SVG) — a Visualization asset

Assets are how data providers package and sell answers. If you need to return multiple rows of data — like a normal REST API response — you want an Endpoint instead.

Asset or Endpoint? Use this rule of thumb:

"What is the average air distance for an NFL quarterback?" → single number → Calculation asset

"Show me a chart of air distance over time" → image → Visualization asset

"Give me air distance per quarterback" → rows → Endpoint

Asset Types

Calculation Assets

Return a single computed value — the insight itself, not the data behind it. Examples:

4.2 (monthly churn rate as a percentage)
"New York" (top-performing city this quarter)
87 (customer satisfaction score)
"$24,300" (median deal size)

-- Example: Monthly churn rate — returns ONE value
SELECT
  ROUND(
    COUNT(CASE WHEN status = 'churned' THEN 1 END) * 100.0 / COUNT(*),
    2
  ) AS churn_rate_pct
FROM customers
WHERE created_at >= DATE_SUB(CURRENT_DATE, INTERVAL 12 MONTH)

If your query returns multiple rows or columns, you don't have a calculation asset — you have an endpoint.

Visualization Assets

Return chart-ready data paired with a chart configuration. Spartera renders the result as a static image (SVG/PNG) that buyers can embed or screenshot.

Charts are configured via a single JSON column called viz_spec, which holds a Plotly figure JSON. Any trace type Plotly supports can be authored — bar, line/scatter, pie, scatter, heatmap, sunburst, treemap, polar, and more. See Visualization Spec Reference for the full schema.

Examples:

Weekly revenue trend (line chart)
Sales by region (bar chart)
Market share breakdown (pie chart)

# Creating a visualization asset with viz_spec
{
    "asset_type": "VISUALIZATION",
    "connection_id": "your-connection-id",
    "source_schema_name": "finance",
    "source_table_name": "weekly_revenue",
    "viz_spec": {
        "data": [
            {
                "type": "scatter",
                "mode": "lines+markers",
                "xsrc": "week",
                "ysrc": "revenue_usd"
            }
        ],
        "layout": {
            "title": "Weekly Revenue"
        }
    },
    "viz_data_limit": 52  # Optional: cap at 52 rows (1 year of weekly data)
}

Column references use the *src convention (xsrc, ysrc, labelssrc, etc.) — the renderer hydrates these with live data from your connection at execution time. See Visualization Spec Reference for the full hydration table and validation rules.

Legacy viz_* columns. The older chart-definition fields (viz_chart_type, viz_dep_var_col_name, viz_indep_var_col_name, viz_color_scheme, viz_show_legend, etc.) still exist on the asset record for read access but are no longer used for chart rendering. Only viz_spec drives the renderer. viz_data_limit is the exception: it's still a functional row cap (see Visualization Spec Reference).

Asset Lifecycle

Draft → Tested → Published → Active (earning revenue)
         │
         └─► Archived (removed from marketplace)

Stage	Description
Draft	Asset created but not yet validated
Tested	Preview execution completed successfully
Published	Live in marketplace, buyers can purchase and execute
Archived	Removed from marketplace; existing buyers retain access

How Assets Execute

When a buyer calls your asset's API endpoint, here's what happens in order:

Spartera validates the buyer's API key and credit balance
The platform connects to your database via your stored credentials
Your asset's SQL logic executes inside your database — raw data never leaves
The result (a single value, or a rendered chart) is returned through the Spartera API to the buyer
Credits are deducted from the buyer and added to your earnings balance

Total execution time is typically 100–500ms for well-optimized queries.

Key Properties of Every Asset

Property	Required	Description
`name`	✅	Unique, descriptive name (shown in marketplace)
`description`	✅	What the asset does, what insight it returns
`connection_id`	✅	Which database connection to use
`asset_type`	✅	`CALCULATION` or `VISUALIZATION`
`sql_logic`	✅	The SQL query to execute
`sell_in_marketplace`		`true` = public; `false` = internal only
`visibility`		`PUBLIC` or `PRIVATE`
`price_usd`		Set via the pricing API after creation
`tags`		Helps buyers discover your asset
`category`		Business category for marketplace browsing

Asset Visibility Options

Public (Marketplace)

Asset appears in marketplace search. Any buyer can discover, purchase, and execute it. You earn 80% of each execution.

Private (Internal Only)

Asset is only accessible to members of your organization. Useful for internal analytics you're not ready to monetize, or proprietary workflows.

Versioning

Assets are versioned automatically. When you update the SQL logic of a published asset, Spartera creates a new version. Existing buyers continue using the previous version until they opt into the update.

Breaking changes (different output type or shape): increment major version (1.x → 2.0)
Non-breaking changes (performance, filters): increment minor version (1.0 → 1.1)

Best Practices

Return one thing. A calculation asset should return a single value. If you find yourself returning multiple columns or multiple rows, you probably want an endpoint instead.

Optimize for performance. Your SQL runs on your database on someone else's schedule. Use indexes, limit result sets, and avoid SELECT *. Target sub-500ms execution.

Write great descriptions. Buyers can't see your SQL. A clear description of what insight the asset returns, what data it uses, and how fresh the data is directly affects conversion.

Price based on value, not cost. A churn prediction model that helps a buyer retain customers is worth far more than a simple revenue sum — price accordingly.

Test with real data. Always run the preview execution against real data before publishing. Sample data often hides edge cases.

Endpoints Overview — When you need rowset data instead of a single value
Creating Assets — Step-by-step asset creation guide
Testing and Validation — How preview mode works
Publishing to Marketplace — Going live
Credit System — How pricing and payouts work