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

# Execute

> Fetch and render backend data with the Execute component using series, slices, filters, and a render-prop child.

API reference: [Execute()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) (function), [IExecuteProps](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md) (interface)

The [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) component builds an execution from measures and attributes, runs it, and passes the result to its `children` render function as data series (built from measures, optionally scoped by attribute elements) sliced by additional attributes. Either `seriesBy` or `slicesBy` must contain at least one item.

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

```tsx
import { Execute } from "@gooddata/sdk-ui";
import * as Md from "./catalog.js";

export const Example = () => (
    <Execute
        seriesBy={[Md.Amount, Md.Won]}
        slicesBy={[Md.Product.Name]}
        filters={[]}
    >
        {({ result, error, isLoading }) => {
            if (isLoading) {
                return <div>Loading...</div>;
            }
            if (error) {
                return <div>Error: {error.message}</div>;
            }
            const data = result?.data();
            return <pre>{JSON.stringify(data?.series().toArray(), null, 2)}</pre>;
        }}
    </Execute>
);
```

## [States](https://www.gooddata.ai/docs/gooddata-ui/latest/data-layer/execute/#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 execution is running. If a previous load succeeded, also on the render right after a prop change that triggers a new execution, so `children` never receives a stale result. |
| `false` | [`DataViewFacade`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.dataviewfacade/index.md) | `undefined` | The data was loaded. A no-data result that includes a data view is returned here, not as an error. |
| `false` | `undefined` | [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md) | The execution or data read failed. The error is converted to a [`GoodDataSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.gooddatasdkerror/index.md) subtype. |

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

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

[`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/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/#when-it-re-runs)

- [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) starts a new execution when any of `seriesBy`, `slicesBy`, `totals`, `filters`, `sortBy`, `window`, or `workspace` changes by deep comparison. Placeholders are resolved before the comparison, so a change of a placeholder value also triggers a new execution.
- It also starts a new execution when `onError`, `onLoadingChanged`, `onLoadingFinish`, or `onLoadingStart` changes by reference. If you pass inline functions, each render of the parent starts a new execution.
- Changing `backend` alone does not start a new execution.
- Calling `reload()` starts a new execution at any time.
- When a new execution starts or the component unmounts before the running one finishes, the running one is canceled and `onError` is called with a [`CancelledSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.cancelledsdkerror/index.md). 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/#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, [`Execute`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.execute/index.md) does not throw during render: the load fails and the error is passed in `error` and to `onError`.
- If both `seriesBy` and `slicesBy` are empty, the load fails with an [`UnexpectedSdkError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.unexpectedsdkerror/index.md): "In the Execute component, either seriesBy or slicesBy must be defined and must contain at least one item".
- `seriesBy`, `slicesBy`, `totals`, `filters`, and `sortBy` can contain placeholders. Pass `placeholdersResolutionContext` for composed placeholders.
- An empty result is not a [`NoDataError`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.nodataerror/index.md). Handle the zero-row case in `children`.
- After each load, `onExportReady` is called with an export function, or, after a failure, with a function that rejects with the error. `exportTitle` defaults to `componentName`, which defaults to `"Execute"`.

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

| Prop | Type | Required | Description | Inherited from |
|------|------|----------|-------------|----------------|
| [`children`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropschildren) | `(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. | — |
| [`backend`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsbackend) | [`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.iexecuteprops/index.md#iexecutepropscomponentname) | `string` | No | Informative name of the component. | — |
| [`enableExecutionCancelling`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsenableexecutioncancelling) | `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.iexecuteprops/index.md#iexecutepropserrorcomponent) | [`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. | — |
| [`exportTitle`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsexporttitle) | `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.iexecuteprops/index.md#iexecutepropsfilters) | [`NullableFiltersOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.nullablefiltersorplaceholders/index.md) | No | Filters to apply on server side. | — |
| [`LoadingComponent`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsloadingcomponent) | [`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.iexecuteprops/index.md#iexecutepropsloadonmount) | `boolean` | No | Specifies whether Execute should trigger execution and loading right after it is mounted. | — |
| [`placeholdersResolutionContext`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsplaceholdersresolutioncontext) | `any` | No | Resolution context for composed placeholders. | — |
| [`seriesBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsseriesby) | [`AttributesMeasuresOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributesmeasuresorplaceholders/index.md) | No | Data series will be built using the provided measures that are further scoped for elements of the specified attributes. | — |
| [`slicesBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropsslicesby) | [`AttributesOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.attributesorplaceholders/index.md) | No | Slice all data series by elements of these attributes. | — |
| [`sortBy`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropssortby) | [`SortsOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.sortsorplaceholders/index.md) | No | Sorting to apply on server side. | — |
| [`totals`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropstotals) | [`TotalsOrPlaceholders`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.totalsorplaceholders/index.md) | No | Include these totals among the data slices. | — |
| [`window`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.iexecuteprops/index.md#iexecutepropswindow) | [`DataViewWindow`](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-ui/sdk-ui.dataviewwindow/index.md) | No | Specifies whether Execute 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.iexecuteprops/index.md#iexecutepropsworkspace) | `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) |