Use aliases to swap datasets with no migrations or code changes

Dataset Hot Swapping allows a codebase to reference a single, named entity, which can then point to different datasets depending on the need of the project.

By utilizing a Dataset Alias in a codebase, the underlying dataset referenced can be swapped without having to copy or migrate data. When preparing a large content change or a new feature, the data can be prepared in a staging or feature dataset and then Hot Swapped behind the "production" Alias with no code or data changes when ready and approved.

Using Dataset Hot Swapping

This enterprise feature is included in the Sanity CLI. By running a series of commands, an alias can be created, linked, unlinked, or deleted.

Creating a new alias

Before a dataset can be swapped, a new alias must be created and referenced by code. To create a new alias for use as a production alias run the following code:

Anywhere the code references the productionDataset it can now be swapped for ~production.

In order to identify incoming alias requests from a client, an alias should be prefixed with the special character ~. In this example, even though the create command was given an alias name of production, when referencing it in requests, the string ~production should be used.

Hot-swapping the dataset behind an alias

Once an alias is created, the dataset behind it can be hot-swapped at any time. In this example, the codebase references the ~production alias. When a new release is ready, a dataset of featureDataset can be created via Cloud Clone from the current dataset behind the production alias. Any data changes can be made, then the production alias can be Hot Swapped to the new featureDataset.

Unlink an alias

When an alias is not currently being used, but should be included in the alias list, it can be unlinked from a dataset.

Delete an alias

When an alias is no longer needed, it can be deleted from the alias list. The delete command only deletes the alias and not any datasets associated with it.

List all aliases and datasets on a project

The list command provides a list of all Datasets and aliases associated with the current project and shows the linked dataset for each alias.