Server-Side Data moves query execution from the browser to your own backend. Your engine receives queries from Studio, translates them for your backend, and returns results in the format widgets expect.
You may not need Server-Side Data. The built-in engine accepts arrays of rows via Synchronous Data Sources and Asynchronous Data Sources. Only adopt Server-Side Data when you need to push query execution to a backend.
Dashboards can place severe load on data backends. Ensure the backends you communicate with are scaled suitably for your use case.
The example below is using a custom engine that demonstrates how to set up server-side data access.
When to Use Server-Side Data Copy Link
The built-in engine loads all row data into the browser and runs operations in-memory. This works well when the dataset fits in browser memory, you can afford the initial transfer latency, and you want instant filtering and sorting with no server round-trip.
Adopt Server-Side Data when:
- Dataset is too large: The data cannot be shipped to the browser and must be queried remotely.
- Analytics backend: You already have a system (e.g. ClickHouse, Snowflake, BigQuery, a REST API) that serves aggregated data.
- Computation delegation: You want to push aggregation, filtering, and sorting to a database engine rather than compute them client-side.
The AgDataEngine Interface Copy Link
Implement the AgDataEngine interface. Your engine declares its data sources via getDataSources(), executes queries via execute(), and optionally performs async setup in init(). If your engine discovers its schema from a remote service, await that discovery in init() and return the result from getDataSources().
export class MyDataEngine implements AgDataEngine {
async init(): Promise<void> {
// Optional: async setup before the schema is consulted.
}
getDataSources(): AgDataSourcesDefinition {
return {
sources: [
{
id: 'sales',
fields: [
{ id: 'region', format: 'textFormat' },
{ id: 'revenue', format: 'numberFormat' },
],
},
],
};
}
async execute(...requests: AgExecuteRequest<AgResultShape>[]): Promise<AgExecuteResult[]> {
return Promise.all(requests.map((req) => this.runOne(req)));
}
private async runOne(request: AgExecuteRequest<AgResultShape>): Promise<AgExecuteResult> {
const { query } = request;
const rows = await this.queryBackend(query); // Your backend call
return { dataShape: 'rows', rows, metadata: { rowCount: rows.length } };
}
}
Properties available on the AgDataEngine interface.
Optional async lifecycle hook called by Studio before the engine is queried. Use this to bootstrap resources that must resolve before the schema is consulted — wasm compilation, HTTP fetches, database connections. Studio awaits this before calling getDataSources or finalize. Engines with no async setup can omit this entirely.
|
Declare the data sources the engine exposes to Studio. Called once, after init resolves. Studio uses this to build the canonical schema it operates against — the engine never sees Schema or SchemaModel objects. The return value is the same AgDataSourcesDefinition shape a caller would pass on the data property when using the built-in engine. Engines that know their fields upfront can build this eagerly in a constructor; engines that discover fields from a remote service will typically await that discovery in init and return the resulting definition here. Schema is read once per engine lifecycle; if your underlying schema can change, rebuild the engine on the host application side.
|
Called after getDataSources once Studio has built its schema view. Built-in engines use this to freeze their query infrastructure; custom engines usually have nothing to do here.
|
Execute one or more queries. Results are returned in request order, one AgExecuteResult per AgExecuteRequest. Studio batches requests that arrive together (typically within one render cycle). All requests in a batch share info.batchId. Engines that can coalesce backend calls should group by batchId. Cancellation: each request carries an optional options.signal that Studio aborts when the batch is superseded. Propagate it into your backend call (e.g. pass to fetch).
|
Invalidate any cached state so the next query recomputes against the current data. Engines without caches can omit this.
|
Subscribe a listener to validation events the engine emits. Engines that never emit validation events can omit this. If you implement this method, you MUST also implement removeEventListener — Studio calls it on teardown.
|
Unsubscribe a listener previously registered via addEventListener. |
Release large data structures to reduce GC pressure on page unload. |
Apply in-place updates to the engine's data sources. Engines that manage their data externally (read-only backends, on-demand fetchers) can omit this.
|
Using Your Engine Copy Link
<ag-studio
[data]="data"
/* other studio properties ... */ />
this.data = new MyDataEngine();Studio calls init() during startup, then getDataSources() once to freeze the schema. From that point on, Studio calls execute() as the user interacts with the dashboard.
getDataSources() is called once per engine lifecycle. The schema is frozen after that call; Studio will not re-read it. If your underlying schema changes at runtime (e.g. new columns added to a database), destroy the Studio instance and create a new one with a fresh engine.
Migrating from the Built-In Engine Copy Link
Swap the data property from an inline data definition to an engine instance:
Before:
<ag-studio
[data]="data"
/* other studio properties ... */ />
this.data = {
sources: [{
id: 'sales',
fields: [/* ... */],
data: [/* rows */]
}]
};After:
<ag-studio
[data]="data"
/* other studio properties ... */ />
this.data = new MyDataEngine();Extract the schema from your current config into your engine's getDataSources(), then implement query translation in execute(). See Implementation for the full query anatomy.