---
title: "Swap data model source elements (Beta)"
method: POST
path: "/v2/dataModels/{dataModelId}/swapSourceElements"
tags: ["Data models"]
---

# Swap data model source elements (Beta)

`POST /v2/dataModels/{dataModelId}/swapSourceElements`

## Request

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

Swap individual source elements in a data model. 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 **dataModelId** by calling the [/v2/dataModels](https://help.sigmacomputing.com/reference/list-data-models) endpoint.
- Retrieve data model sources by calling the [/v2/dataModels/{dataModelId}/sources](https://help.sigmacomputing.com/reference/list-data-model-sources) 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/dataModels/{dataModelId}/sources](https://help.sigmacomputing.com/reference/list-data-model-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
- **Data model development**: Use a test data source during development, then swap to a production source when ready.
- **Dataset migration**: Update references to legacy dataset sources with data model sources by mapping dataset IDs to their new data model equivalents.

## Path parameters

- `dataModelId` string, required

## Request body

- object
  - `sourceMapping` V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItems[], required
    - `from` union, required: Source to swap from.
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom0
        - `type` 'table', required
        - `tableId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom3
        - `type` 'custom-sql', required
        - `customSqlSourceId` string, required: ID of the custom SQL source.
    - `to` union, required: Source to swap to.
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo0
        - `type` 'table', required
        - `tableId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo3
        - `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` V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsMetricMappingItems[]
      - `fromMetricId` string, required: Identifier of the metric in the data source
      - `toMetricId` string, required: Identifier of the metric in the data source
    - `columnMapping` V2DataModelsDataModelIdSwapSourceElementsPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsColumnMappingItems[]
      - `fromColumn` union, required
        - string[]
        - string[]
        - string[]
      - `toColumn` union, required
        - string[]
        - string[]
        - string[]

## Response `200`

The response body.

- DataModelsSwapDataModelSourceElementsResponse200
  - `unswappedSources` V2DataModelsDataModelIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems[], required: Sources from the request that were not swapped.
    - union
      - V2DataModelsDataModelIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems0
        - `type` 'table', required
        - `tableId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2DataModelsDataModelIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2DataModelsDataModelIdSwapSourceElementsPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems3
        - `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)