> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# ExecuteInsight

> Run a saved visualization and pass the resulting data view to a render-prop child.

API reference: [ExecuteInsight](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) (variable), [IExecuteInsightProps](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md) (interface)

The [`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) component loads a visualization saved in the workspace (referenced by [`ObjRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.objref/index.md)), runs its execution, and passes the loading state, error, and data view to its `children` render function. Use it to render the data of a saved visualization with your own code instead of [`InsightView`](https://www.gooddata.ai/docs/gooddata-ui/latest/visualisations/insightview/index.md).

> **Note:**
>  The term 'insight' is an obsolete expression for 'visualizations' but is still employed within the SDK's components and functions.

## [Basic usage](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#basic-usage)

```tsx
import { ExecuteInsight } from "@gooddata/sdk-ui";
import { idRef } from "@gooddata/sdk-model";

export const Example = () => (
    <ExecuteInsight insight={idRef("<visualization-id>")}>
        {({ isLoading, error, result }) => {
            if (isLoading) {
                return <div>Loading...</div>;
            }
            if (error) {
                return <div>Error: {error.message}</div>;
            }
            return <pre>{JSON.stringify(result?.dataView.data, null, 2)}</pre>;
        }}
    </ExecuteInsight>
);
```

## [States](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#states)

The `children` function receives a [`WithLoadingResult`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.withloadingresult/index.md) in one of these states.

| `isLoading` | `result` | `error` | When |
|-------------|----------|---------|------|
| `false` | `undefined` | `undefined` | Before the first load starts: on the first render and, when `loadOnMount` is `false`, until you call `reload()` or a prop change triggers a new execution. |
| `true` | `undefined` | `undefined` | The visualization is loading or its execution is running. |
| `false` | [`DataViewFacade`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.dataviewfacade/index.md) | `undefined` | The data was loaded. An empty result is returned here, not as a [`NoDataError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.nodataerror/index.md). |
| `false` | `undefined` | [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md) | Loading the visualization, the execution, or the data read failed. |

`reload` is available in every state and starts a new execution.

## [Rendering](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#rendering)

[`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) picks what to render in this order:

| Condition | Renders |
|-----------|---------|
| [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.errorcomponent/index.md) is set and there is an `error` | [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.errorcomponent/index.md) with the `error` prop. |
| [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md) is set and `isLoading` is `true` | [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md). |
| Both [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md) and [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.errorcomponent/index.md) are set and there is no `result` | Nothing (`null`). |
| Otherwise | The `children` function. |

When you set both [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.loadingcomponent/index.md) and [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.errorcomponent/index.md), `children` is called only with a successful result.

## [When it re-runs](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#when-it-re-runs)

- [`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) starts a new execution when `insight`, `filters`, or `window` changes by deep comparison.
- It also starts a new execution when `onError`, `onLoadingChanged`, `onLoadingFinish`, or `onLoadingStart` changes by reference. Memoize these callbacks.
- Changing `sorts`, `dimensions`, or `dateFormat` alone does not start a new execution. Call `reload()` to apply them.
- When a new execution starts before the running one finishes, the running one is canceled. The request itself keeps running unless `enableExecutionCancelling` is `true`; then its signal is aborted.

## [Notes](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#notes)

- `backend` and `workspace` props take precedence over [`BackendProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.backendprovider/index.md) and [`WorkspaceProvider`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.workspaceprovider/index.md). If neither is available, the load fails with an error.
- `filters` are added to the filters saved in the visualization. `sorts`, `dimensions`, and `dateFormat` override the saved ones; each also accepts a function that receives the execution definition and returns the value.
- Set `executeByReference` to run the saved visualization by reference instead of sending its full definition. Use it only when your backend requires executions tied to stored visualizations.
- Set `loadOnMount={false}` to skip the initial run, and call `reload()` to start it.
- Without `window`, [`ExecuteInsight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.executeinsight/index.md) reads all data. Pass `window` with `offset` and `size` arrays to read one page.
- `exportTitle` defaults to `componentName`, which defaults to `"ExecuteInsight"`.

## [Props](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute-insight/#props)

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`children`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropschildren) | `(executionResult:` [`WithLoadingResult`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.withloadingresult/index.md)`) => ReactElement \| null` | Yes | Child component to which rendering is delegated. | — |
| [`insight`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsinsight) | [`ObjRef`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.objref/index.md) | Yes | Reference to the insight for which you want to get the data view. | — |
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsbackend) | [`IAnalyticalBackend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ianalyticalbackend/index.md) | No | Backend to execute against. | — |
| [`componentName`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropscomponentname) | `string` | No | Informative name of the component. | — |
| [`dateFormat`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsdateformat) | `string \| ((def:` [`IExecutionDefinition`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutiondefinition/index.md)`, props:` [`IExecuteInsightProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md)`) => string)` | No | Modify date formatting on prepared insight execution, before it's executed. | — |
| [`dimensions`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsdimensions) | [`IDimension`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idimension/index.md)`[] \| ((def:` [`IExecutionDefinition`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutiondefinition/index.md)`, props:` [`IExecuteInsightProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md)`) =>` [`IDimension`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.idimension/index.md)`[])` | No | Modify dimensions on prepared insight execution, before it's executed. | — |
| [`enableExecutionCancelling`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsenableexecutioncancelling) | `boolean` | No | Optionally enable real execution cancellation. This means that if the execution request is not yet finished and the execution changes, the request will be cancelled and the new execution will be started. Default: false | — |
| [`ErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropserrorcomponent) | [`IExecuteErrorComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteerrorcomponent/index.md) | No | Provide component for rendering of the error state. | — |
| [`executeByReference`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsexecutebyreference) | `boolean` | No | Indicates that the execution to obtain the data for the insight should be an 'execution by reference'. Execution by reference means that the ExecuteInsight will ask analytical backend to compute results for an insight which is stored on the backend by specifying link to the insight, additional filters and description how to organize the data. Otherwise, a freeform execution is done, in which the InsightView will send to backend the full execution definition of what to compute. This distinction is in place because some backends MAY want to prohibit users from doing freeform executions and only allow computing data for set of insights created by admins. Note: the need for execute by reference is rare. You will typically be notified by the solution admin to use this mode. | — |
| [`exportTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsexporttitle) | `string` | No | Name to use for files exported from this component. | — |
| [`filters`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsfilters) | [`INullableFilter`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.inullablefilter/index.md)`[]` | No | Filters to apply on server side. | — |
| [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsloadingcomponent) | [`IExecuteLoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteloadingcomponent/index.md) | No | Provide component for rendering of the loading state. | — |
| [`loadOnMount`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsloadonmount) | `boolean` | No | Specifies whether [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) should trigger execution and loading right after it is mounted. | — |
| [`sorts`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropssorts) | [`ISortItem`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.isortitem/index.md)`[] \| ((def:` [`IExecutionDefinition`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutiondefinition/index.md)`, props:` [`IExecuteInsightProps`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md)`) =>` [`ISortItem`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.isortitem/index.md)`[])` | No | Modify sorts on prepared insight execution, before it's executed. | — |
| [`window`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropswindow) | [`DataViewWindow`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.dataviewwindow/index.md) | No | Specifies whether [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) should load all data from backend or just a particular window - specified by offset and size of the window. | — |
| [`workspace`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteinsightprops/index.md#iexecuteinsightpropsworkspace) | `string` | No | Workspace in whose context to perform the execution. | — |
| [`onError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md#iwithloadingeventsonerror) | `(error:` [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md)`, props: TProps) => void` | No | If specified, this function will be called in case loading runs into an error. | [`IWithLoadingEvents`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md) |
| [`onExportReady`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md#iwithloadingeventsonexportready) | `(exportFunction:` [`IExportFunction`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexportfunction/index.md)`, props: TProps) => void` | No | Called when loading finishes and it is possible to export the underlying data. Function that does the export will be provided on the callback. | [`IWithLoadingEvents`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md) |
| [`onLoadingChanged`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md#iwithloadingeventsonloadingchanged) | `(isLoading: boolean, props: TProps) => void` | No | Called when loading starts and finishes, indicating the current state using the `isLoading` parameter. | [`IWithLoadingEvents`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md) |
| [`onLoadingFinish`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md#iwithloadingeventsonloadingfinish) | `(result:` [`DataViewFacade`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.dataviewfacade/index.md)`, props: TProps) => void` | No | Called when loading finishes. | [`IWithLoadingEvents`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md) |
| [`onLoadingStart`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md#iwithloadingeventsonloadingstart) | `(props: TProps) => void` | No | Called when loading starts. | [`IWithLoadingEvents`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iwithloadingevents/index.md) |