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

Beta: This documentation describes a private beta feature and is subject to the Beta features disclaimer.

Usage notes

• Retrieve the workbookId by calling the /v2/workbooks endpoint.

• Retrieve workbook sources by calling the /v2/workbooks/{workbookId}/sources endpoint.

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

• Retrieve the datasetId by calling the /v2/datasets endpoint.

• 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 element, identify it by its element ID using the customSqlId field. 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, 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 data model column with display name Dock Count. Provide columnMapping explicitly to override the automatic match for a column.

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.