JavaScript Embedded AnalyticsServer-Side Data: Implementation

Studio calls your engine's execute() method with one or more AgExecuteRequest objects. Each request carries an AgStudioQuery that your engine translates into your backend's native query language. Return one AgExecuteResult per request, in the same order.

Query Anatomy Copy Link

Every field reference in an AgStudioQuery is an AgStudioQueryField object carrying key, fieldId, sourceId, and optional properties like aggregation.

Core Fields Copy Link

Additional Fields Copy Link

These fields appear when the dashboard uses features that require them. If your engine does not support a given field, the corresponding UI feature will not work correctly.

Computed Fields Copy Link

computedFields is a topologically sorted evaluation schedule. Each entry carries an expression AST and an explicit evaluation phase:

• phase: 'pre-agg': evaluated on source rows before grouping (SQL column expression)
• phase: 'post-agg': evaluated on grouped output after measures are computed
• synthetic: true: internally generated intermediates; exclude from user-facing result columns

Engines evaluate entries in array order. Each entry's dependencies are satisfied by prior entries or source scans.

Expression nodes are either operations ({ operator, inputs, options? }) or leaves: field references ({ field: AgStudioQueryField }), literals ({ literal: Primitive }), or alias references ({ ref: string }).

Field Identifiers Copy Link

Every field reference in a query is an AgStudioQueryField:

Measure fields also carry aggregation (e.g. 'sum', 'avg', 'count'). Access it via measure.field.aggregation.

Filter Structure Copy Link

The filter and having fields share the same recursive tree structure:

AgStudioFilterGroup: a boolean combinator ('and', 'or', or 'not') wrapping child nodes:

{
    combinator: 'and',
    conditions: [/* AgStudioFilterCondition | AgStudioFilterGroup */],
}

AgStudioFilterCondition: a leaf predicate on a single field:

{
    field: { key, fieldId, sourceId },
    operator: 'equals',
    value: 'EMEA',
}

Walk the tree recursively: groups become parenthesised boolean expressions; conditions become backend predicates. See the reference examples for complete filter translation.

Result Format Copy Link

Return an AgExecuteResult per request, discriminated on dataShape. Return 'rows' (default) or 'columns' depending on options.shape.

Both shapes carry an AgResultMetadata object. rowCount is the number of rows in the returned result. When your engine applies a limit, set totalRowCount to the pre-limit row count.

Rows Format (default) Copy Link

return {
    dataShape: 'rows',
    rows: [
        { 'sales.region': 'EMEA', 'sales.revenue': 123456 },
        { 'sales.region': 'APAC', 'sales.revenue': 234567 },
    ],
    metadata: { rowCount: 2, totalRowCount: 5432 },
};

Columns Format Copy Link

const columns = new Map<string, ReadonlyArray<Primitive | null>>();
columns.set('sales.region', ['EMEA', 'APAC']);
columns.set('sales.revenue', [123456, 234567]);

return {
    dataShape: 'columns',
    columns,
    metadata: { rowCount: 2 },
};

Sources and Joins Copy Link

When a widget pulls fields from multiple related sources (declared via Relationships), Studio produces a single AgStudioQuery with joins populated. Your execute() receives one query that spans multiple sources. Each field's sourceId and fieldId identify which backend table it belongs to, so your translator can resolve every reference.

If your backend does not support joins, throw a descriptive error when a query contains joins.

Batching and Cancellation Copy Link

Studio calls execute(...requests) with every request in the current render cycle. Each request carries an info object:

• batchId: All requests in the same execute() call share a batchId. Use it to coalesce backend round-trips (e.g. one combined request per batch). When absent, treat each request independently.
• queryId: Distinguishes independent queries from the same widget (e.g. 'rows' vs 'grandTotal'). Studio uses widgetId + queryId as the cancellation key.

Each request carries an optional options.signal: AbortSignal. Propagate it into your backend call to cancel superseded queries:

const res = await fetch(url, { signal: request.options?.signal });

Errors Copy Link

Throw from execute() when the backend fails. Any failed request in a batch will cause the whole batch to fail. This is to avoid partial data flowing into Studio.

async execute(...requests: AgExecuteRequest<AgResultShape>[]): Promise<AgExecuteResult[]> {
    try {
        return await this.runQueries(requests);
    } catch (error) {
        throw { message: 'Backend query failed', cause: error };
    }
}

Reference Examples Copy Link

ClickHouse over HTTP Copy Link

Translates AgStudioQuery to ClickHouse SQL, posts it over HTTP, and returns the response. The dashboard queries ClickHouse's uk_price_paid dataset (~28M rows) without downloading any of it.

Contains HM Land Registry data © Crown copyright and database right 2021. This data is licensed under the Open Government Licence v3.0. (Source, Fields)

REST API: World Bank Countries Copy Link

Queries the World Bank Open Data API. Supported predicates are sent as URL parameters; remaining filters, aggregation, and sorting are applied locally.

Contains data from The World Bank: Countries API, licensed under Creative Commons Attribution 4.0 (CC BY 4.0). (Terms of Use)