Migrate data to Azure Cosmos DB using the desktop data migration tool

The Azure Cosmos DB desktop data migration tool is an open-source command-line application to import or export data from Azure Cosmos DB. The tool can migrate data to and from many sources and sinks including, but not limited to:

• Azure Cosmos DB for NoSQL
• Azure Cosmos DB for MongoDB
• Azure Cosmos DB for Table
• Azure Table storage
• JSON
• MongoDB
• SQL Server

For this guide, you will perform a data migration from JSON to Azure Cosmos DB for NoSQL.

Prerequisites

• An existing Azure Cosmos DB for NoSQL account.
  • If you have an Azure subscription, create a new account.
  • If you don't have an Azure subscription, create a free account before you begin.
  • Alternatively, you can try Azure Cosmos DB free before you commit.

  Install the desktop data migration tool

  First, install the latest version of the desktop data migration tool from the GitHub repository.

  The desktop data migration tool requires .NET 6.0 or later on your local machine.

  1. In your browser, navigate to the Releases section of the repository: azurecosmosdb/data-migration-desktop-tool/releases.
  2. Download the latest compressed folder for your platform. There are compressed folders for the win-x64, mac-x64, and linux-x64 platforms.
  3. Extract the files to an install location on your local machine.
  4. (Optional) Add the desktop data migration tool to the PATH environment variable of your local machine.

  Prepare your migration target

  Next, create a target database and container on the Azure Cosmos DB for NoSQL account.

  • Azure CLI
  • Azure PowerShell

  # Variable for Azure Cosmos DB account name accountName="" # Variable for resource group name resourceGroupName="" 

  az cosmosdb sql database create \ --resource-group $resourceGroupName \ --account-name $accountName \ --name cosmicworks \ --throughput 400 

  az cosmosdb sql container create \ --resource-group $resourceGroupName \ --account-name $accountName \ --database-name cosmicworks \ --name products \ --partition-key-path "/category" 

  az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type connection-strings 

  # Variable for Azure Cosmos DB account name $ACCOUNT_NAME = "" # Variable for resource group name $RESOURCE_GROUP_NAME = "" 

  $parameters = @ < ResourceGroupName = $RESOURCE_GROUP_NAME AccountName = $ACCOUNT_NAME Name = "cosmicworks" Throughput = 400 >New-AzCosmosDBSqlDatabase @parameters 

  $parameters = @ < ResourceGroupName = $RESOURCE_GROUP_NAME AccountName = $ACCOUNT_NAME DatabaseName = "cosmicworks" Name = "products" PartitionKeyPath = "/category" PartitionKeyKind = "Hash" >New-AzCosmosDBSqlContainer @parameters 

  $parameters = @ < ResourceGroupName = $RESOURCE_GROUP_NAME Name = $ACCOUNT_NAME Type = "ConnectionStrings" >Get-AzCosmosDBAccountKey @parameters 

  Perform a migration operation

  Now, migrate data from a JSON array to the newly created Azure Cosmos DB for NoSQL container.

  1. Navigate to an empty directory on your local machine. Within that directory, create a new file named migrationsettings.json.
  2. Within the JSON file, create a new empty JSON object:

  < "Source": "json", "SourceSettings": < "FilePath": "https://raw.githubusercontent.com/azure-samples/cosmos-db-migration-sample-data/main/nosql-data.json" >, "Sink": "cosmos-nosql", "SinkSettings": < >> 

  < "Source": "json", "SourceSettings": < "FilePath": "https://raw.githubusercontent.com/azure-samples/cosmos-db-migration-sample-data/main/nosql-data.json" >, "Sink": "cosmos-nosql", "SinkSettings": < "ConnectionString": "" > > 

  < "Source": "json", "SourceSettings": < "FilePath": "https://raw.githubusercontent.com/azure-samples/cosmos-db-migration-sample-data/main/nosql-data.json" >, "Sink": "cosmos-nosql", "SinkSettings": < "ConnectionString": "", "Database": "cosmicworks", "Container": "products", "PartitionKeyPath": "/category" > > 

  Note If you did not add the installation path to your PATH environment variable, you may need to specify the full path to the dmt executable.

  Using JSON Source Using Cosmos-nosql Sink