Testing and Validation

Before an asset can be published, it should pass a preview execution. This page explains how preview mode works for both standard database assets and External API assets.

Two Execution Modes

Mode	Data Coverage	Use For
Preview / Test	10% of your data (sampled)	Fast validation during development
Process (Full)	100% of your data	Final validation before publishing; production use

Running a Preview Execution

Standard Database Assets (BigQuery, Snowflake, Redshift, etc.)

Click Preview / Test in the asset form. Spartera connects to your database, runs your SQL against a 10% sample, and returns the result.

# Via API
curl -X POST "https://api.spartera.com/companies/{company_id}/assets/{asset_id}/execute" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"preview": true}'

External API Assets

For External API connections, clicking Preview / Test opens a Parameter Input Dialog first. You must fill in all schema parameters before the test executes — this matches the buyer experience exactly.

The dialog shows each parameter with:

Display name (column alias) and data type
Input field appropriate to the type (text, number, dropdown, checkbox, date picker)
Validation before submission

If your External API asset has no parameters defined, the dialog will show a warning instead. Add parameters in the schema editor before testing.

Parameter Input Dialog (External API)

When testing an External API asset, each parameter must be filled in:

Parameter Type	Input	Validation
`STRING`	Text field	Required, non-empty
`INTEGER`	Number field	Must be a valid whole number
`FLOAT`	Number field	Must be a valid decimal number
`BOOLEAN`	Checkbox	`true` or `false`
`DATE`	Text field	Must be `YYYY-MM-DD` format
`TIMESTAMP`	Text field	Must be ISO 8601 format (`YYYY-MM-DDTHH:MM:SS`)

If a parameter has valid_values defined, it renders as a dropdown instead of a free-text field.

The dialog remembers your last-used values — if you test repeatedly, previous values are pre-filled for convenience.

How Sampling Works

Preview mode uses stratified random sampling — it selects 10% of your data while maintaining proportional representation across segments, time ranges, and categories. This means:

A 10M row table runs the preview on ~1M rows
Time-series data samples across all time periods, not just the most recent
Categorical distributions are preserved

This makes preview results statistically representative, not just a slice of the most recent data.

Validating Your Results

After a preview run, verify:

Output structure

Are column names what you expect?
Are data types correct (numbers as numbers, not strings)?

Value ranges

Do the numbers make sense for your dataset?
Are there unexpected nulls or zeros?

Null handling

What happens when a filter matches no rows?
Are edge cases handled (empty date ranges, missing foreign keys)?

Performance

Preview target: under 500ms for simple queries
Over 2 seconds on preview = optimize before publishing

Common Issues and Fixes

Issue	Likely Cause	Fix
Preview times out	Query is too complex or unindexed	Add indexes; simplify query
Unexpected nulls	Missing JOIN conditions	Add `WHERE` filters or `COALESCE`
Wrong row count	Sampling includes duplicates	Add `DISTINCT` or deduplicate upstream
Division by zero	Count returns zero	Wrap denominator in `NULLIF(count, 0)`
Type mismatch	Column is VARCHAR, expected NUMBER	`CAST(column AS FLOAT)`
External API timeout	API not reachable or too slow	Check IP whitelist; optimize model
Parameter validation error	Wrong format for type	Check type requirements above

Save Schema

For assets with dynamic parameters (things buyers can filter or customize), you need to save the schema before publishing. Click Save Schema after:

Selecting an asset type
Providing SQL logic (Calculation) or schema/table (Visualization)

Save Schema is not available for External API + Calculation assets — parameters are defined through the schema parameter editor instead.

Running a Full Execution

When you're confident in preview results, run a full execution to validate against complete data:

curl -X POST "https://api.spartera.com/companies/{company_id}/assets/{asset_id}/execute" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json"
# No "preview": true = full execution against 100% of data

Full executions consume credits from your account at the standard asset price.

Execution Response Structure

{
  "data": {
    "avg_clv": 4823.50
  },
  "meta": {
    "execution_id": "exec_abc123",
    "execution_time_ms": 312,
    "rows_returned": 1,
    "credits_used": 5,
    "data_freshness": "2025-04-01T02:00:00Z",
    "preview": false,
    "asset_version": "1.2.0"
  }
}

Before Publishing Checklist

Preview execution succeeds with no errors
Output values are in the expected range
Full execution completes in under 2 seconds (target)
Null and empty edge cases are handled gracefully
Output column names are stable (won't change without a version bump)
For External API: all schema parameters are defined and tested
Save Schema completed (if asset has dynamic parameters)

Once all boxes are checked, you're ready to publish.