---
title: "Swap report data sources"
method: POST
path: "/v2/reports/{reportId}/swapSources"
tags: ["Reports"]
---

# Swap report data sources

`POST /v2/reports/{reportId}/swapSources`

## Request

- Base URL: `https://api.sigmacomputing.com`
- URL: `https://api.sigmacomputing.com/v2/reports/{reportId}/swapSources`
- Auth: HTTP bearer

Swap each data source used by a report. You can swap from one table, dataset (deprecated), data model element, or custom SQL element to another for each data source.

### Usage notes
- Retrieve the **reportId** by calling the [/v2/reports](https://help.sigmacomputing.com/reference/list-reports) endpoint.
- Retrieve report sources by calling the [/v2/reports/{reportId}/sources](https://help.sigmacomputing.com/reference/list-report-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 sources. For each source in the source mapping, provide the current source in use in the **from** object, and provide the source that you want 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, pass either `customSqlId` or `customSqlSourceId`, not both. Set `customSqlId` to the element ID returned by the [/v2/reports/{reportId}/sources](https://help.sigmacomputing.com/reference/list-report-sources) endpoint, or set `customSqlSourceId` to the custom SQL source ID returned by that 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.
- `unswappedSources` lists the `from` object for each requested source that could not be swapped.

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

## Path parameters

- `reportId` string, required

## Request body

- object
  - `sourceMapping` V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItems[], required
    - `from` union, required: Source to swap from.
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom0
        - `type` 'table', required
        - `tableId` string, required
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom3
        - `type` 'custom-sql', required
        - `customSqlId` string, required: ID of the element associated with the custom SQL element.
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsFrom4
        - `type` 'custom-sql', required
        - `customSqlSourceId` string, required: ID of the custom SQL source.
    - `to` union, required: Source to swap to.
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo0
        - `type` 'table', required
        - `tableId` string, required
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsTo3
        - `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` V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsMetricMappingItems[]
      - `fromMetricId` string, required: Identifier of the metric in the data source
      - `toMetricId` string, required: Identifier of the metric in the data source
    - `columnMapping` V2ReportsReportIdSwapSourcesPostRequestBodyContentApplicationJsonSchemaSourceMappingItemsColumnMappingItems[]
      - `fromColumn` union, required
        - string[]
        - string[]
        - string[]
      - `toColumn` union, required
        - string[]
        - string[]
        - string[]

## Response `200`

The response body.

- ReportsSourceSwapReportResponse200
  - `unswappedSources` V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems[], required: Requested from sources that were not swapped. Each entry is the from object from the request.
    - union
      - V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems0
        - `type` 'table', required
        - `tableId` string, required
      - V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems1
        - `type` 'dataset', required
        - `datasetId` string, required
      - V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems2
        - `type` 'data-model', required
        - `dataModelId` string, required
        - `elementId` string, required: ID of the element in the data model
        - `versionTagId` string
      - V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems3
        - `type` 'custom-sql', required
        - `customSqlId` string, required: ID of the element associated with the custom SQL element.
      - V2ReportsReportIdSwapSourcesPostResponsesContentApplicationJsonSchemaUnswappedSourcesItems4
        - `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)