---
title: "Swap workbook source elements (Beta)"
method: POST
path: "/v2/workbooks/{workbookId}/swapSourceElements"
tags: ["Workbooks"]
---

# Swap workbook source elements (Beta)

`POST /v2/workbooks/{workbookId}/swapSourceElements`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/workbooks/{workbookId}/swapSourceElements`
- Auth: HTTP bearer

Swap individual source elements in a workbook. You can swap from one table, dataset (deprecated), data model element, or custom SQL element to another.

**Beta**: This documentation describes a public beta feature and is subject to the [Beta features](/docs/sigma-product-releases#beta-features) disclaimer.

### Usage notes
- Retrieve the **workbookId** by calling the [/v2/workbooks](https://help.sigmacomputing.com/reference/list-workbooks) endpoint.
- Retrieve workbook sources by calling the [/v2/workbooks/{workbookId}/sources](https://help.sigmacomputing.com/reference/get-workbook-sources) endpoint.
- Retrieve the **dataModelId** by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint.
- Retrieve the **datasetId** by calling the [/v2/datasets](https://help.sigmacomputing.com/reference/list-datasets) endpoint. (Deprecated)
- Retrieve the **tableId** by calling the [/v2/connection](https://help.sigmacomputing.com/reference/lookup-connection) endpoint.
- Retrieve the **connectionId** for a new custom SQL element by calling the [/v2/connections](https://help.sigmacomputing.com/reference/list-connections) endpoint.
- Use the `sourceMapping` options in the request body to swap specific source elements. For each source element, provide the current source in the **from** object and the source to use instead in the **to** object.
- If your source is a data model with one or more tagged versions, you can also provide a `versionTagId` to swap to or from a tagged version of the data model. The data model version must already be tagged.
- When swapping **from** a custom SQL source, set `customSqlSourceId` to the value returned by the [/v2/workbooks/{workbookId}/sources](https://help.sigmacomputing.com/reference/get-workbook-sources) endpoint. When swapping **to** a custom SQL element, supply the `connectionId` of the connection to run against and the SQL query in the `definition` field.
- If your source is a data model or a dataset (deprecated), you can use the `metricMapping` option to map metrics that rely on column names from the old source to the new one so that they continue to work.
- If the source that you swap from uses column names, links, or relationships different from the source that you are swapping to, use the `columnMapping` option to map each column in the original source to a corresponding column in the new source.
- When `columnMapping` is omitted, columns are automatically matched by display name, ignoring differences in case and punctuation. For example, a custom SQL output column named `DOCK_COUNT` automatically maps to a column with display name `Dock Count` in the target source. Provide `columnMapping` explicitly to override the automatic match for a column.
- `unswappedSources` lists the `from` object for each requested source element that could not be swapped.

### Usage scenarios
- **Workbook development**: Use a test data source during development, then swap to a production source when ready to share the workbook.
- **Dataset migration**: Update references to deprecated dataset sources with data model sources by mapping dataset IDs to their new data model equivalents.

## Path parameters

- `workbookId` string, required

## Request body

- object
  - `sourceMapping` V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItems[], required
    - `from` union, required: Source to swap from.
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom0
        - `type` 'table', required
        - `tableId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom3
        - `type` 'custom-sql', required
        - `customSqlSourceId` string, required: ID of the custom SQL source.
    - `to` union, required: Source to swap to.
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo0
        - `type` 'table', required
        - `tableId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo3
        - `type` 'custom-sql', required
        - `connectionId` string, required: ID of the connection that the new custom SQL element will run against.
        - `definition` string, required: SQL query that defines the new custom SQL element.
    - `metricMapping` V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsMetricMappingItems[]
      - `fromMetricId` string, required: Identifier of the metric in the data source
      - `toMetricId` string, required: Identifier of the metric in the data source
    - `columnMapping` V2WorkbooksWorkbookIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsColumnMappingItems[]
      - `fromColumn` union, required
        - string[]
        - string[]
        - string[]
      - `toColumn` union, required
        - string[]
        - string[]
        - string[]

## Response `200`

The response body.

- WorkbooksSwapWorkbookSourceElementsResponse200
  - `unswappedSources` V2WorkbooksWorkbookIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems[], required: Sources from the request that were not swapped.
    - union
      - V2WorkbooksWorkbookIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems0
        - `type` 'table', required
        - `tableId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2WorkbooksWorkbookIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2WorkbooksWorkbookIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems3
        - `type` 'custom-sql', required
        - `customSqlSourceId` string, required: ID of the custom SQL source.

---

[API](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api.md) - [All operations](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sigmacomputing/apis/sigma-rest-api/revisions/fb6036208c49?raw)