We just wrapped up AG Studio Launch Week See what we shipped

Angular Embedded AnalyticsSharing & Caching Data

Version 3.1.1

A Data Engine loads, processes, and caches data for Studio widgets.

Studio creates one automatically when you pass data sources via the data property, but you can create the built-in engine yourself to share it across instances, or cache it across a Studio instance's lifecycle.

Built-in Engine Copy Link

When you pass data sources directly to Studio, it creates a built-in Data Engine behind the scenes. Creating the engine externally with createDataEngine(data) gives you two benefits:

  • Sharing - multiple Studio instances can point at the same engine, so they share a single copy of the data.
  • Caching across lifecycles - the engine survives when Studio is destroyed and recreated, so data doesn't need to be re-fetched or reprocessed on remount.
const dataEngine = createDataEngine({
    sources: [{
        id: 'medals',
        data: [
            {
                year: 2000,
                sport: 'Swimming',
                country: 'United States',
                // ... other fields
            },
            // ... other rows
        ],
    }],
});
<ag-studio
    [data]="data"
    /* other studio properties ... */ />

this.data = dataEngine;

See Loading Data for the full range of data loading patterns.

createDataEngine(data) accepts a data object of type AgDataSourcesDefinition.

sourcesCopy Link
AgDataSource<TRegistry>[]
One or more data sources.
relationshipsCopy Link
AgRelationDefinition[]
When using multiple related tables, this describes the fields that link the tables together.
expressionsCopy Link
AgExpressionFieldDefinition<TRegistry, AgFormat<TRegistry>, any>[]
Expression field definitions for calculated columns.
formatsCopy Link
TRegistry["formats"]
Overrides to existing formats, or additional custom formats.
descriptionCopy Link
string
AI-facing overview of the entire dataset: what it contains, what it's for, domain quirks.
calendarsCopy Link
AgCalendar[]
Named time dimensions (calendars) that supply date fragments and a continuous date spine.
bucketsCopy Link
TRegistry["buckets"]
Additional date-fragment bucket definitions to register alongside the built-in set (year, quarter, month, week, day, monthOfYear, dayOfWeek, …). Use this to add project-specific groupings such as weekend, dayOfMonth, or hour that the built-in registry does not include. Provide via createBuckets so type-level registry inference works correctly.
optionsCopy Link
AgDataSourcesOptions
Engine-wide behavioural options, such as fan-out detection policy.

Retrieving the Engine Copy Link

api.getDataEngine() returns the engine the Studio instance is using, whether Studio created it or you passed your own in. It returns undefined until the engine is in place, which it is by the time the studioReady event fires.

If Studio created the engine, it is released when that Studio instance is destroyed. To keep the engine alive across a destroy and recreate, or to share it between instances, create it with createDataEngine() as above and pass it via the data property.

getDataEngineCopy Link
Function
Returns the data engine this Studio instance is currently using, or undefined if it does not have one. A Studio configured without the data property never has an engine, and one that is still loading does not have it yet - the engine is in place by the time the studioReady event fires. If Studio created the engine, its lifetime is tied to this Studio instance: the engine is released when Studio is destroyed. To keep an engine alive across a Studio instance being destroyed and recreated, or to share one engine between several instances, create it yourself with createDataEngine() and pass it via the data property. Studio then leaves it in your hands, and getDataEngine() returns that same engine.

Custom Engines Copy Link

Sharing and caching, as described above, are features of the built-in engine only. For larger datasets, or when you want to replace query execution with a backend you already own, see the Custom Engine guide in the Server-Side Data section.