JavaScript Embedded AnalyticsData Overview

Data is provided to Studio using the data property.

Data is retrieved from data sources. A data source represents one or more tables of data.

When multiple tables are provided, Relationships describe how the tables are linked.

There are two main types of data source:

• Sync Data - for data already loaded in the application.
• Async Data - for data lazily loaded on demand.

See Sharing & Caching Data to reuse one data source across multiple instances of Studio.

The example above demonstrates configuring a single Sync Data.

const studioProperties = {
    data: {
        sources: [{
            id: 'medals',
            data: [
                {
                    year: 2000,
                    sport: 'Swimming',
                    country: 'United States',
                    // ... other fields
                },
                // ... other rows
            ],
        }],
    },

    // other studio properties ...
}

Relationships Copy Link

When multiple tables are provided, if there are relationships between the data, then these should be provided alongside the data sources. This will allow fields from different tables to be displayed together in the same widget.

The example above demonstrates two tables, Medals and Capitals, linked together by country. Both tables are Sync Data.

const studioProperties = {
    data: {
        sources: [{
            id: 'medals',
            data: [
                {
                    year: 2000,
                    sport: 'Swimming',
                    country: 'United States',
                    // ... other fields
                },
                // ... other rows
            ],
        }, {
            id: 'capitals',
            data: [
                {
                    country: 'United States',
                    capital: 'Washington, D.C.',
                    // ... other fields
                },
                // ... other rows
            ],
        }],
        relationships: [
            {
                id: 'medals-capitals',
                source: {
                    tableId: 'medals',
                    fieldId: 'country',
                },
                target: {
                    tableId: 'capitals',
                    fieldId: 'country',
                },
                type: 'many-to-one'
            },
        ],
    },

    // other studio properties ...
}

Normal relationships are defined using the AgDataRelationDefinition interface:

Joining Dates Copy Link

By default date fields are joined the same way as any other field, where matching rows are linked by exact date value.

It is also possible to join date fields of different granularities, or to override the granularity at which they are joined.

This is done by using a ::unit field ID in the relationship, Studio derives a bucketed column from the base date field and uses it as the join key.

The following units are supported. The value column shows the integer each unit produces, which is what the join key is compared against.

Both sides of the relationship can use ::unit. When they do, both must declare the same unit. Using different units on each side is a configuration error.

A plain date column can also appear on one side without a ::unit suffix. Studio extracts the same unit from it automatically, so both keys are comparable integers.

// Valid: both sides extract the same unit
{
    id: 'orders-targets',
    source: { tableId: 'orders', fieldId: 'order_date::quarter' },
    target: { tableId: 'targets', fieldId: 'target_date::quarter' },
    type: 'many-to-one',
}

// Valid: one side declares the common unit; the plain date side inherits it
{
    id: 'orders-targets',
    source: { tableId: 'orders', fieldId: 'order_date' },
    target: { tableId: 'targets', fieldId: 'target_date::quarter' },
    type: 'many-to-one',
}

// Error: mismatched units
{
    id: 'orders-targets',
    source: { tableId: 'orders', fieldId: 'order_date::month' },
    target: { tableId: 'targets', fieldId: 'target_date::year' },
    type: 'many-to-one',
}

The example above demonstrates joining at different granularities.

Modelling Data Copy Link

A dashboard's queries mostly do two things: filter/group by an attribute, and summarise a measure against it. Splitting tables along that line - tables you group by, and tables you summarise - is the basis of a data model that suits Studio well.

Star Schema Copy Link

A star schema puts this into practice: one fact table - the table holding your measures - related to several dimension tables, each by its own many-to-one relationship. It's named for the shape: the fact table sits at the centre with its dimensions radiating out around it.

The example above groups the orderItems fact table by two of its dimensions, products and regions, in a single widget - each dimension contributes its own many-to-one relationship, with no join between dimensions themselves.

Galaxy Schema Copy Link

Sometimes the data behind a dashboard arrives at more than one grain - daily order items and individual shipments, for example.

Avoid joining tables like these to each other directly. Instead, give each fact its own star, reusing the same dimension tables where they apply - a conformed dimension is a dimension table shared by more than one fact's star.

Multiple stars linked by conformed dimensions like this form a galaxy schema (also called a fact constellation). Joining the two facts directly can multiply rows on both sides, inflating measures in a way that's easy to miss.

The example below extends the star above with a second fact table: shipments (one row per shipment, a coarser grain than orderItems). Both facts relate to products and regions - now conformed dimensions, shared across both stars - while customers still relates to orderItems only:

const studioProperties = {
    data: {
        sources: [
            { id: 'products', data: [/* ... */] },
            { id: 'customers', data: [/* ... */] },
            { id: 'regions', data: [/* ... */] },
            { id: 'orderItems', data: [/* ... */] },
            { id: 'shipments', data: [/* ... */] },
        ],
        relationships: [
            {
                id: 'order-items-products',
                source: { tableId: 'orderItems', fieldId: 'productId' },
                target: { tableId: 'products', fieldId: 'id' },
                type: 'many-to-one',
            },
            {
                id: 'order-items-customers',
                source: { tableId: 'orderItems', fieldId: 'customerId' },
                target: { tableId: 'customers', fieldId: 'id' },
                type: 'many-to-one',
            },
            {
                id: 'order-items-regions',
                source: { tableId: 'orderItems', fieldId: 'regionId' },
                target: { tableId: 'regions', fieldId: 'id' },
                type: 'many-to-one',
            },
            {
                id: 'shipments-products',
                source: { tableId: 'shipments', fieldId: 'productId' },
                target: { tableId: 'products', fieldId: 'id' },
                type: 'many-to-one',
            },
            {
                id: 'shipments-regions',
                source: { tableId: 'shipments', fieldId: 'regionId' },
                target: { tableId: 'regions', fieldId: 'id' },
                type: 'many-to-one',
            },
        ],
    },

    // other studio properties ...
}

Keep each fact's measure in its own widget, both grouped by products.name: one widget for sum(orderItems.netSales), another for count(shipments.id). Both widgets agree on which products they're showing, since they share the same products dimension.

The example above shows each fact as its own widget, both grouped by products.name.

Snowflake Schema Copy Link

A dimension table can itself be normalised into further tables - splitting products into products and categories, for example, so each category's name is stored once rather than repeated on every product row. Following a dimension's relationships out another hop like this is called a snowflake schema, named for the way its dimensions branch further outward than a star's.

The example above groups orderItems.netSales by categories.name and products.name together. categories is not a dimension of orderItems directly - the join reaches it by following products' own relationship out one more hop.

Fan-out Detection Copy Link

Fan-out is row duplication introduced by a join: a shape where a single fact row can match more than one row on the other side, so a measure summed across the join counts some rows more than once. Two relationship shapes trigger it:

• Two fact tables joined directly, rather than through a shared conformed dimension (see Galaxy Schema above).
• A dimension related to a fact through a many-to-many relationship, so a fact row can attribute to more than one dimension member and vice versa.

In the shape above, an order item tagged with three tags contributes to sum(orderItems.netSales) three times over once grouped by tags.name - once per tag - rather than once.

By default, Studio detects both shapes and reports a warning through the same collector used for other query validation issues, then runs the query anyway.

Accept the duplication for a specific relationship with acceptFanout: true, silencing its warning regardless of the data.options.fanout policy below:

{
    id: 'order-items-tags',
    source: { tableId: 'orderItems', fieldId: 'tagId' },
    target: { tableId: 'tags', fieldId: 'id' },
    type: 'many-to-many',
    acceptFanout: true,
}

Or control fan-out detection for the whole data model with data.options.fanout:

const studioProperties = {
    data: {
        sources: [/* ... */],
        options: {
            fanout: {
                warning: true, // default - report a warning for any unaccepted fan-out finding
                execute: 'allow', // default - run the query anyway; set to 'prevent' to block it instead
            },
        },
    },

    // other studio properties ...
}

const studioProperties = {
    data: {
        sources: [/* ... */],
        options: {
            fanout: false, // shorthand for { warning: false, execute: 'allow' } - never warn, never block
        },
    },

    // other studio properties ...
}

Data API Copy Link