Working with visualization objects

Read measures, attributes, filters, and identity from IInsight with the insight* accessors, and derive copies with insightSet*.

Note

The term ‘insight’ is an obsolete expression for ‘visualizations’ but is still employed within the SDK’s components and functions.

A saved visualization is an IInsight. Read it with the accessors below, and derive a changed copy with the setters.

Concepts

IInsightDefinition holds what the visualization shows: buckets of measures and attributes, filters, sorts, visualization properties, a title, and a visualizationUrl naming the visualization type. IInsight extends it with identity: the object reference, identifier, URI, and audit fields.

You get an IInsight from backend.workspace(workspace).insights().getInsight(ref), from the selectInsights selector in the Dashboard component, or as the insight prop of a custom visualization component registered by a dashboard plugin.

All data sits under insight.insight. Don’t read that body directly: the accessors validate their input and keep working when the internal layout changes.

Read the definition

Accessor	Returns
`insightTitle(insight)`	`string`
`insightVisualizationUrl(insight)`	`string`, for example `"local:column"` or `"local:table"`
`insightBuckets(insight, ...ids)`	`IBucket[]`, optionally only the buckets with the given local identifiers
`insightBucket(insight, id)`	`IBucket \| undefined`
`insightMeasures(insight, predicate?)`	`IMeasure[]` across all buckets
`insightAttributes(insight, predicate?)`	`IAttribute[]` across all buckets
`insightFilters(insight)`	`IFilter[]`
`insightSorts(insight)`	`ISortItem[]`
`insightProperties(insight)`	`VisualizationProperties`
`insightTags(insight)`	`string[]`

Combine them with the measure and attribute accessors:

import {
    attributeDisplayFormRef,
    insightAttributes,
    insightFilters,
    insightMeasures,
    insightTitle,
    measureIdentifier,
    type IInsight,
} from "@gooddata/sdk-model";

function summarize(insight: IInsight) {
    return {
        title: insightTitle(insight),
        measureIdentifiers: insightMeasures(insight).map(measureIdentifier),
        displayForms: insightAttributes(insight).map(attributeDisplayFormRef),
        filterCount: insightFilters(insight).length,
    };
}

To read one bucket, ask for it by local identifier. The identifiers depend on the visualization type. For example, a column chart uses measures, view, and stack.

import { bucketMeasures, insightBucket, type IInsight } from "@gooddata/sdk-model";

function primaryMeasures(insight: IInsight) {
    const measuresBucket = insightBucket(insight, "measures");

    if (!measuresBucket) {
        return [];
    }

    return bucketMeasures(measuresBucket);
}

Tags are the usual way to group saved visualizations. insightTags returns an empty array when there are none, so insightTags(insight).includes("featured") needs no guard.

Read the identity

Accessor	Returns
`insightRef(insight)`	`ObjRef`
`insightId(insight)`	`string`
`insightUri(insight)`	`string`
`insightCreated(insight)`	`string \| undefined`
`insightUpdated(insight)`	`string \| undefined`

Compare references with areObjRefsEqual, not by identifier string. See Working with object references.

Derive a modified copy

The setters return a new object and leave the input unchanged. When you pass an IInsight, you get an IInsight back with the identity intact.

Setter	Replaces
`insightSetFilters(insight, filters)`	the filters
`insightSetSorts(insight, sorts)`	the sorts
`insightSetProperties(insight, properties)`	the visualization properties
`insightSetBuckets(insight, buckets)`	the buckets

The common case is adding filters before execution:

import { insightFilters, insightSetFilters, type IFilter, type IInsight } from "@gooddata/sdk-model";

function withExtraFilters(insight: IInsight, extraFilters: IFilter[]): IInsight {
    return insightSetFilters(insight, [...insightFilters(insight), ...extraFilters]);
}

Execute the copy with backend.workspace(workspace).execution().forInsight(copy); see ExecuteInsight. Inside a dashboard, useWidgetFilters gives you the filters to pass here; see useWidgetFilters.

Notes

insightMeasures and insightAttributes accept a predicate to pick items, for example insightMeasures(insight, isSimpleMeasure).
insightVisualizationUrl is the stable way to learn the visualization type. Compare the whole string; do not parse it.