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

# IExecutionFactory

- Package: [@gooddata/sdk-backend-spi](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/index.md)
- Kind: interface
- Source: https://github.com/gooddata/gooddata-ui-sdk/blob/rel/11.64/libs/sdk-backend-spi/src/workspace/execution/index.ts

Execution factory provides several methods to create a prepared execution from different types of inputs.

**Signature:**

```typescript
export interface IExecutionFactory 
```

## Remarks

Note: the execution factory WILL perform extensive input validation to ensure that the created instance of prepared execution is semantically correct.

## Methods

| Method | Description |
| --- | --- |
| [forBuckets(buckets, filters, options)](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iexecutionfactory/index.md#iexecutionfactoryforbuckets) | Prepares a new execution for a list of buckets. |
| [forDefinition(def, options)](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iexecutionfactory/index.md#iexecutionfactoryfordefinition) | Prepares a new execution for the provided execution definition. |
| [forInsight(insightDefinition, filters, options)](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iexecutionfactory/index.md#iexecutionfactoryforinsight) | Prepares a new execution for the provided insight. |
| [forInsightByRef(insight, filters, options)](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iexecutionfactory/index.md#iexecutionfactoryforinsightbyref) | Prepares new, by-reference execution for an existing insight. |
| [forItems(items, filters, options)](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.iexecutionfactory/index.md#iexecutionfactoryforitems) | Prepares a new execution for a list of attributes and measures, filtered using the provided filters. |

## Method details

### IExecutionFactory.forBuckets()

Prepares a new execution for a list of buckets.

**Signature:**

```typescript
forBuckets(buckets: IBucket[], filters?: INullableFilter[], options?: IPreparedExecutionOptions): IPreparedExecution;
```

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| buckets | [IBucket](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.ibucket/index.md)[] | list of buckets with attributes and measures, must be non empty, must have at least one attr or measure |
| filters | [INullableFilter](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.inullablefilter/index.md)[] | _(Optional)_ optional, may not be provided, may contain null or undefined values which must be ignored |
| options | [IPreparedExecutionOptions](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecutionoptions/index.md) | _(Optional)_ additional options for the prepared execution |

**Returns:**

[IPreparedExecution](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md)

#### Remarks

Attributes and measures WILL be transferred to the execution in natural order:

- Order of items within a bucket is retained in the execution - Items from first bucket appear before items from second bucket

Or more specifically, given two buckets with items as [A1, A2, M1] and [A3, M2, M3], the resulting prepared execution WILL have definition with attributes = [A1, A2, A3] and measures = [M1, M2, M3]

The contract is that prepared executions created by this method MUST be executable and MUST come with pre-filled dimensions created using the [defaultDimensionsGenerator()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.defaultdimensionsgenerator/index.md).

### IExecutionFactory.forDefinition()

Prepares a new execution for the provided execution definition.

**Signature:**

```typescript
forDefinition(def: IExecutionDefinition, options?: IPreparedExecutionOptions): IPreparedExecution;
```

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| def | [IExecutionDefinition](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iexecutiondefinition/index.md) | execution definition |
| options | [IPreparedExecutionOptions](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecutionoptions/index.md) | _(Optional)_ additional options for the prepared execution |

**Returns:**

[IPreparedExecution](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md)

new prepared execution

#### Remarks

The contract is that the definition is taken and used in the prepared execution AS IS. Compared to the other convenience methods, this method MUST NOT create prepared executions with automatically generated dimensions.

### IExecutionFactory.forInsight()

Prepares a new execution for the provided insight.

**Signature:**

```typescript
forInsight(insightDefinition: IInsightDefinition, filters?: INullableFilter[], options?: IPreparedExecutionOptions): IPreparedExecution;
```

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| insightDefinition | [IInsightDefinition](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iinsightdefinition/index.md) | insight definition to create execution for, must have buckets which must have some attributes or measures in them |
| filters | [INullableFilter](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.inullablefilter/index.md)[] | _(Optional)_ optional, may not be provided, may contain null or undefined values which must be ignored |
| options | [IPreparedExecutionOptions](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecutionoptions/index.md) | _(Optional)_ additional options for the prepared execution |

**Returns:**

[IPreparedExecution](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md)

#### Remarks

Buckets with attributes and measures WILL be used to obtain attributes and measures - the behavior WILL be same as in forBuckets() function. Filters, sort by and totals in the insight WILL be included in the prepared execution.

Additionally, an optional list of additional filters WILL be merged with the filters already defined in the insight.

The contract is that prepared executions created by this method MUST be executable and MUST come with pre-filled dimensions greated using the [defaultDimensionsGenerator()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.defaultdimensionsgenerator/index.md).

### IExecutionFactory.forInsightByRef()

Prepares new, by-reference execution for an existing insight.

**Signature:**

```typescript
forInsightByRef(insight: IInsight, filters?: INullableFilter[], options?: IPreparedExecutionOptions): IPreparedExecution;
```

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| insight | [IInsight](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iinsight/index.md) | saved insight |
| filters | [INullableFilter](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.inullablefilter/index.md)[] | _(Optional)_ optional list of filters to merge with filters already defined in the insight, may contain null or undefined values which must be ignored |
| options | [IPreparedExecutionOptions](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecutionoptions/index.md) | _(Optional)_ additional options for the prepared execution |

**Returns:**

[IPreparedExecution](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md)

#### Remarks

Execution prepared using this method MAY be realized using different backend API than the executions where attributes and measures are provided 'freeform'. In return, this different backend API may provide additional authorization guarantees - for instance the backend MAY only allow end user to execute these stored insights and not do any 'freeform' execution.

If the backend does not support execution by reference, then it MUST fall back to freeform execution.

The contract is that prepared executions created by this method MUST be executable and MUST come with pre-filled dimensions created using the [defaultDimensionsGenerator()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.defaultdimensionsgenerator/index.md).

### IExecutionFactory.forItems()

Prepares a new execution for a list of attributes and measures, filtered using the provided filters.

**Signature:**

```typescript
forItems(items: IAttributeOrMeasure[], filters?: INullableFilter[], options?: IPreparedExecutionOptions): IPreparedExecution;
```

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| items | [IAttributeOrMeasure](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.iattributeormeasure/index.md)[] | list of attributes and measures, must not be empty |
| filters | [INullableFilter](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.inullablefilter/index.md)[] | _(Optional)_ list of filters, may not be provided |
| options | [IPreparedExecutionOptions](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecutionoptions/index.md) | _(Optional)_ additional options for the prepared execution |

**Returns:**

[IPreparedExecution](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-backend-spi/sdk-backend-spi.ipreparedexecution/index.md)

#### Remarks

The contract is that prepared executions created by this method MUST be executable and MUST come with pre-filled dimensions created using the [defaultDimensionsGenerator()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.defaultdimensionsgenerator/index.md).