{"id":12463,"date":"2026-06-02T12:15:41","date_gmt":"2026-06-02T19:15:41","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=12463"},"modified":"2026-06-02T02:57:45","modified_gmt":"2026-06-02T09:57:45","slug":"change-partition-keys-in-azure-cosmos-db-is-now-generally-available","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/change-partition-keys-in-azure-cosmos-db-is-now-generally-available\/","title":{"rendered":"Change Partition Keys in Azure Cosmos DB is Now Generally Available"},"content":{"rendered":"<p>We&#8217;re excited to announce the general availability of <strong>Change Partition Key<\/strong> in Azure Cosmos DB for NoSQL, now with online copy support. You can repartition containers directly in the Azure portal with near-zero downtime and without stopping writes to the source container.<\/p>\n<h2>Why Partition Key Choice Matters<\/h2>\n<p>In Azure Cosmos DB, the partition key is one of the most important design choices you make. It affects how data is distributed across physical partitions, how queries are routed, and how well your application performs at scale.<\/p>\n<p>But applications change over time. A partition key that worked well at launch can become a bottleneck as access patterns shift, data grows, or new features are introduced. Common examples include:<\/p>\n<ul>\n<li><strong>Hot partitions<\/strong> &#8211; A partition key that once distributed traffic evenly now drives most requests to a small number of logical partitions.<\/li>\n<li><strong>Cross-partition queries<\/strong> &#8211; New query patterns may fan out across partitions, increasing RU consumption and latency.<\/li>\n<li><strong>Logical partition size limits<\/strong> &#8211; Unexpected growth can push a logical partition toward the 20-GB limit.<\/li>\n<li><strong>Schema evolution<\/strong> &#8211; A new data model may require different access patterns and a different partitioning strategy.<\/li>\n<\/ul>\n<p>Until now, changing a partition key required a manual migration at the application level: create a new container, write custom migration code, manage cutover, and plan for downtime. For many teams, that complexity meant living with a partition key that no longer fit their workload.<\/p>\n<h2>How it works<\/h2>\n<p>The Change Partition Key feature uses Azure Cosmos DB&#8217;s <a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/container-copy\">intra-account container copy<\/a> infrastructure. The process has three main steps:<\/p>\n<ol>\n<li><strong>Start the change partition key job<\/strong> &#8211; Select the source container and the destination container with the new partition key, then start the job.<\/li>\n<li><strong>Monitor progress<\/strong> &#8211; Track job status in the Azure portal. In online mode, ongoing writes to the source container are continuously replicated to the destination.<\/li>\n<li><strong>Cut over<\/strong> &#8211; After the destination catches up, switch your application to the new container. You can optionally delete the source container.<\/li>\n<\/ol>\n<h2>Getting Started<\/h2>\n<h3>Prerequisites<\/h3>\n<ul>\n<li>An Azure Cosmos DB for NoSQL account<\/li>\n<li>The source container you want to repartition<\/li>\n<li>Access to the Azure portal<\/li>\n<\/ul>\n<h3>Step-by-Step Walkthrough<\/h3>\n<ol>\n<li>In the Azure portal, open your Azure Cosmos DB account and go to <strong>Data Explorer<\/strong>. Select the container whose partition key you want to change, then open the <strong>Partition Keys<\/strong> tab under <strong>Scale &amp; Settings<\/strong>.<\/li>\n<li>Select <strong>Change<\/strong> to create the partition key job.\n<a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016.png\"><img decoding=\"async\" class=\"aligncenter wp-image-12464 size-full\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016.png\" alt=\"Screenshot from the Azure portal showing the Change Partition Key experience for Azure Cosmos DB. The interface displays options to configure a partition key migration job, including selecting source and destination containers, choosing online or offline copy mode, and monitoring migration progress. The UI highlights the ability to repartition containers with near-zero downtime while continuing writes to the source container. The screenshot uses the Azure portal\u2019s dark theme with configuration panels, progress indicators, and Azure Cosmos DB navigation menus visible.\" width=\"2374\" height=\"1004\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016.png 2374w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016-300x127.png 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016-1024x433.png 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016-768x325.png 768w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016-1536x650.png 1536w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150016-2048x866.png 2048w\" sizes=\"(max-width: 2374px) 100vw, 2374px\" \/><\/a><\/li>\n<li>Choose either online or offline mode to copy data from the source container to the destination container.<\/li>\n<li>Create a new container with the desired partition key, or select an existing container in the same database, and then start the job.<\/li>\n<li>Track job progress directly in the portal, including the number of documents copied.<\/li>\n<li>For an online copy job, complete these additional steps:\n<ol>\n<li>Stop writes to the source container when the processed document count is close to the total number of documents.<\/li>\n<li>Select <strong>Complete<\/strong> to finish the job and flush any remaining changes.<a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531.png\"><img decoding=\"async\" class=\"wp-image-12467 alignnone\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531.png\" alt=\"Screenshot from the Azure portal showing the Change Partition Key experience for Azure Cosmos DB. The interface displays options to configure a partition key migration job, including selecting source and destination containers, choosing online or offline copy mode, and monitoring migration progress. The UI highlights the ability to repartition containers with near-zero downtime while continuing writes to the source container. The screenshot uses the Azure portal\u2019s dark theme with configuration panels, progress indicators, and Azure Cosmos DB navigation menus visible.\" width=\"530\" height=\"302\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531.png 1254w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531-300x171.png 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531-1024x584.png 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-145531-768x438.png 768w\" sizes=\"(max-width: 530px) 100vw, 530px\" \/><\/a><\/li>\n<\/ol>\n<\/li>\n<li>After the copy job finishes, update your application to connect to the new container.<\/li>\n<\/ol>\n<h2>Best Practices and Considerations<\/h2>\n<ol>\n<li>Test in a non-production environment first to confirm that the new partition key distributes data evenly.<\/li>\n<li>Monitor RU consumption during the copy because it uses your provisioned throughput. If needed, temporarily scale up capacity.<\/li>\n<li>In online mode, plan a brief downtime window to flush remaining changes before switching applications to the destination container.<\/li>\n<li>After cutover, verify that key queries now run as point reads or single-partition queries.<\/li>\n<li>You can also use container copy jobs for cross-account partition key changes by selecting another account from the container copy tab in the Azure portal.<img decoding=\"async\" class=\"aligncenter wp-image-12465 size-full\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452.png\" alt=\"Screenshot 2026 05 29 150452 image\" width=\"2374\" height=\"1127\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452.png 2374w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452-300x142.png 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452-1024x486.png 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452-768x365.png 768w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452-1536x729.png 1536w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2026\/06\/Screenshot-2026-05-29-150452-2048x972.png 2048w\" sizes=\"(max-width: 2374px) 100vw, 2374px\" \/><\/li>\n<\/ol>\n<h2>Resources<\/h2>\n<ul>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/change-partition-key\">Documentation: Change partition key<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/container-copy\">Documentation: Container copy jobs<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/hierarchical-partition-keys\">Documentation: Hierarchical partition keys<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/azure\/cosmos-db\/partitioning-overview#choose-partitionkey\">Best practices: Choosing a partition key<\/a><\/li>\n<li><a href=\"https:\/\/aka.ms\/cosmosdbfeedback\">Feedback: Azure Cosmos DB Ideas<\/a><\/li>\n<\/ul>\n<h2><span class=\"TextRun SCXW50913107 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW50913107 BCX8\" data-ccp-charstyle=\"normaltextrun\" data-ccp-charstyle-defn=\"{&quot;ObjectId&quot;:&quot;ac0262f4-8a9e-5820-b908-2d943c5f7113|1&quot;,&quot;ClassId&quot;:1073872969,&quot;Properties&quot;:[201342446,&quot;1&quot;,201342447,&quot;5&quot;,201342448,&quot;1&quot;,201342449,&quot;1&quot;,469777841,&quot;Aptos&quot;,469777842,&quot;Arial&quot;,469777843,&quot;Aptos&quot;,469777844,&quot;Aptos&quot;,201341986,&quot;1&quot;,469769226,&quot;Aptos,Arial&quot;,268442635,&quot;24&quot;,469775450,&quot;normaltextrun&quot;,201340122,&quot;1&quot;,134233614,&quot;true&quot;,469778129,&quot;normaltextrun&quot;,335572020,&quot;1&quot;,469778324,&quot;Default Paragraph Font&quot;]}\">About Azure Cosmos DB<\/span><\/span><span class=\"TextRun SCXW50913107 BCX8\" lang=\"EN-US\" xml:lang=\"EN-US\" data-contrast=\"none\"><span class=\"NormalTextRun SCXW50913107 BCX8\" data-ccp-charstyle=\"eop\" data-ccp-charstyle-defn=\"{&quot;ObjectId&quot;:&quot;920dbcde-2834-5e15-a5fa-062170b236ba|1&quot;,&quot;ClassId&quot;:1073872969,&quot;Properties&quot;:[201342446,&quot;1&quot;,201342447,&quot;5&quot;,201342448,&quot;1&quot;,201342449,&quot;1&quot;,469777841,&quot;Aptos&quot;,469777842,&quot;Arial&quot;,469777843,&quot;Aptos&quot;,469777844,&quot;Aptos&quot;,201341986,&quot;1&quot;,469769226,&quot;Aptos,Arial&quot;,268442635,&quot;24&quot;,469775450,&quot;eop&quot;,201340122,&quot;1&quot;,134233614,&quot;true&quot;,469778129,&quot;eop&quot;,335572020,&quot;1&quot;,469778324,&quot;Default Paragraph Font&quot;]}\">\u202f<\/span><\/span><span class=\"EOP Selected SCXW50913107 BCX8\" data-ccp-props=\"{&quot;134233117&quot;:false,&quot;134233118&quot;:false,&quot;201341983&quot;:0,&quot;335559738&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/h2>\n<p><span data-contrast=\"none\">Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and distributed computing over massive volumes of NoSQL and vector data.<\/span><span data-ccp-props=\"{&quot;134233117&quot;:false,&quot;134233118&quot;:false,&quot;201341983&quot;:0,&quot;335559738&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><span data-ccp-props=\"{&quot;134233117&quot;:false,&quot;134233118&quot;:false,&quot;201341983&quot;:0,&quot;335559738&quot;:0,&quot;335559739&quot;:0,&quot;335559740&quot;:240}\">\u00a0<\/span><\/p>\n<p>To stay in the loop on Azure Cosmos DB updates, follow us on\u00a0<a href=\"https:\/\/twitter.com\/AzureCosmosDB\" target=\"_blank\" rel=\"noopener\">X<\/a>,\u00a0<a href=\"https:\/\/aka.ms\/AzureCosmosDBYouTube\" target=\"_blank\" rel=\"noopener\">YouTube<\/a>, and\u00a0<a href=\"https:\/\/www.linkedin.com\/company\/azure-cosmos-db\/\" target=\"_blank\" rel=\"noopener\">LinkedIn<\/a>.\u00a0 Join the discussion with other developers on the\u00a0<a href=\"https:\/\/discord.gg\/pczdC2SU\" target=\"_blank\" rel=\"noopener\">#nosql channel on the Microsoft Open Source Discord<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>We&#8217;re excited to announce the general availability of Change Partition Key in Azure Cosmos DB for NoSQL, now with online copy support. You can repartition containers directly in the Azure portal with near-zero downtime and without stopping writes to the source container. Why Partition Key Choice Matters In Azure Cosmos DB, the partition key is [&hellip;]<\/p>\n","protected":false},"author":90111,"featured_media":12475,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[14,2017,1828,19],"tags":[],"class_list":["post-12463","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-core-sql-api","category-azure-cosmos-db-tools","category-data-modeling","category-tips-and-tricks"],"acf":[],"blog_post_summary":"<p>We&#8217;re excited to announce the general availability of Change Partition Key in Azure Cosmos DB for NoSQL, now with online copy support. You can repartition containers directly in the Azure portal with near-zero downtime and without stopping writes to the source container. Why Partition Key Choice Matters In Azure Cosmos DB, the partition key is [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12463","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/90111"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=12463"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/12463\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/12475"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=12463"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=12463"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=12463"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}