Swap report data sources

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 endpoint.

• Retrieve report sources by calling the /v2/reports/{reportId}/sources endpoint.

• Retrieve the dataModelId by calling the /v2/dataModels endpoint.

• Retrieve the datasetId by calling the /v2/datasets endpoint. (Deprecated)

• Retrieve the tableId by calling the /v2/connection endpoint.

• Retrieve the connectionId for a new custom SQL element by calling the /v2/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 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.