Swap data model source elements (Beta)

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

Usage notes

• Retrieve the dataModelId by calling the /v2/dataModels endpoint.
• Retrieve data model sources by calling the /v2/dataModels/{dataModelId}/sources 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 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 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.