<section>
 <h1 class="contains-headerlink leafygreen-ui-41fr9s" weight="medium">
  Change a Document's Shard Key Value
  <a class="headerlink leafygreen-ui-1kepx47" href="#change-a-document-s-shard-key-value" title="Permalink to this heading">
   <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
    <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
    </path>
    <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
    </path>
   </svg>
   <div class="css-1btu0w3 evvkmar0" id="change-a-document-s-shard-key-value">
   </div>
  </a>
 </h1>
 <div class="leafygreen-ui-a5yxub">
  <p class="css-1cmx2d4 ef7gu8j0">
   On this page
  </p>
  <ul class="css-1qb0mst ef7gu8j1">
   <li class="leafygreen-ui-1e7a0ei">
    <a class="lg-ui-0001 leafygreen-ui-e98ikf" href="#example" target="_self">
     <span>
      Example
     </span>
    </a>
   </li>
  </ul>
 </div>
 <p class="leafygreen-ui-1kp3ins">
  You can update a document's shard key value unless the shard key field is the
immutable
  <code class="leafygreen-ui-1l06pbn">
   _id
  </code>
  field.
 </p>
 <div class="leafygreen-ui-85da11" role="note">
  <h2 class="leafygreen-ui-1ac4g5h">
   Important
  </h2>
  <h3 class="leafygreen-ui-144d5kf">
   <strong>
    When updating the shard key value
   </strong>
  </h3>
  <div class="leafygreen-ui-9mycqc">
   <ul class="leafygreen-ui-rioki0">
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      You
      <strong>
       must
      </strong>
      be on a
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/program/mongos/#mongodb-binary-bin.mongos">
       <code class="leafygreen-ui-1l06pbn">
        mongos
       </code>
      </a>
      . Do
      <strong>
       not
      </strong>
      issue the
operation directly on the shard.
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      You
      <strong>
       must
      </strong>
      run either in a
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/transactions/">
       transaction
      </a>
      or as a
      <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/retryable-writes/">
       retryable write
       <!-- -->
       .
      </a>
     </p>
    </li>
    <li class="leafygreen-ui-d7p7b6">
     <p class="leafygreen-ui-1kp3ins">
      You
      <strong>
       must
      </strong>
      include an equality condition on the full shard
key in the query filter. For example, consider a
      <code class="leafygreen-ui-1l06pbn">
       messages
      </code>
      collection that uses
      <code class="leafygreen-ui-1l06pbn">
       { activityid: 1, userid : 1 }
      </code>
      as the
shard key. To update the shard key value for a document, you must
include
      <code class="leafygreen-ui-1l06pbn">
       activityid: &lt;value&gt;, userid: &lt;value&gt;
      </code>
      in the query
filter. You can include additional fields in the query as
appropriate.
     </p>
    </li>
   </ul>
   <p class="leafygreen-ui-1kp3ins">
    See also the specific write command/methods for additional
operation-specific requirements when run against a sharded
collection.
   </p>
  </div>
 </div>
 <p class="leafygreen-ui-1kp3ins">
  To update a shard key value, use the following operations:
 </p>
 <div class="leafygreen-ui-skkc39" tabindex="0">
  <table class="leafygreen-ui-hr8lsv">
   <colgroup>
    <col style="width:40%"/>
    <col style="width:60%"/>
   </colgroup>
   <thead class="leafygreen-ui-a9ho40">
    <tr data-testid="leafygreen-ui-header-row">
     <th class="leafygreen-ui-1trtg6r" role="columnheader" scope="col">
      <div class="leafygreen-ui-ui0te9">
       <div>
        Command
       </div>
      </div>
     </th>
     <th class="leafygreen-ui-13uteka" role="columnheader" scope="col">
      <div class="leafygreen-ui-ui0te9">
       <div>
        Method
       </div>
      </div>
     </th>
    </tr>
   </thead>
   <tbody>
    <tr class="">
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
        <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/update/#std-label-command-update-shard-key-modification">
         update
        </a>
        with
        <code class="leafygreen-ui-1l06pbn">
         multi: false
        </code>
       </div>
      </div>
     </td>
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
        <div class="line-block">
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.replaceOne/#std-label-replaceOne-shard-key-modification">
           db.collection.replaceOne()
          </a>
         </div>
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.updateOne/#std-label-updateOne-shard-key-modification">
           db.collection.updateOne()
          </a>
         </div>
        </div>
        <p class="leafygreen-ui-1kp3ins">
         To set to a non-
         <code class="leafygreen-ui-1l06pbn">
          null
         </code>
         value, the update
         <strong class="css-4dei7l">
          must
         </strong>
         be
performed either inside a transaction or as a retryable write.
        </p>
       </div>
      </div>
     </td>
    </tr>
    <tr class="">
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
        <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/command/findAndModify/#std-label-cmd-findAndModify-sharded-collection">
         findAndModify
        </a>
       </div>
      </div>
     </td>
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
        <div class="line-block">
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.findOneAndReplace/#std-label-findOneAndReplace-shard-key-modification">
           db.collection.findOneAndReplace()
          </a>
         </div>
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.findOneAndUpdate/#std-label-findOneAndUpdate-shard-key-modification">
           db.collection.findOneAndUpdate()
          </a>
         </div>
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.findAndModify/#std-label-method-findAndModify-sharded-collection">
           db.collection.findAndModify()
          </a>
         </div>
        </div>
        <p class="leafygreen-ui-1kp3ins">
         To set to a non-
         <code class="leafygreen-ui-1l06pbn">
          null
         </code>
         value, the update
         <strong class="css-4dei7l">
          must
         </strong>
         be
performed either inside a transaction or as a retryable write.
        </p>
       </div>
      </div>
     </td>
    </tr>
    <tr class="">
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
       </div>
      </div>
     </td>
     <td class="leafygreen-ui-1drjk7h">
      <div class="leafygreen-ui-1n4j8xf">
       <div>
        <div class="line-block">
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/db.collection.bulkWrite/#mongodb-method-db.collection.bulkWrite">
           <code class="leafygreen-ui-1l06pbn">
            db.collection.bulkWrite()
           </code>
          </a>
         </div>
         <div class="line">
          <a class="leafygreen-ui-tqgtui" href="/docs/manual/reference/method/Bulk.find.updateOne/#mongodb-method-Bulk.find.updateOne">
           <code class="leafygreen-ui-1l06pbn">
            Bulk.find.updateOne()
           </code>
          </a>
         </div>
        </div>
        <p class="leafygreen-ui-1kp3ins">
         If the shard key modification results in moving the document to
another shard, you cannot specify more than one shard key
modification in the bulk operation; the batch size has to be 1.
        </p>
        <p class="leafygreen-ui-1kp3ins">
         If the shard key modification does not result in moving the
document to another shard, you can specify multiple shard
key modification in the bulk operation.
        </p>
        <p class="leafygreen-ui-1kp3ins">
         To set to a non-
         <code class="leafygreen-ui-1l06pbn">
          null
         </code>
         value, the operation
         <strong class="css-4dei7l">
          must
         </strong>
         be
performed either inside a transaction or as a retryable write.
        </p>
       </div>
      </div>
     </td>
    </tr>
   </tbody>
  </table>
 </div>
 <div class="leafygreen-ui-1sjx7ru" role="note">
  <h2 class="leafygreen-ui-29m78u">
   Warning
  </h2>
  <div class="leafygreen-ui-9mycqc">
   <p class="leafygreen-ui-1kp3ins">
    Documents in sharded collections can be missing the shard key fields.
Take precaution to avoid accidentally removing the shard key when changing
a document's shard key value.
   </p>
  </div>
 </div>
 <section>
  <h2 class="contains-headerlink leafygreen-ui-19f71ei" weight="medium">
   Example
   <a class="headerlink leafygreen-ui-1kepx47" href="#example" title="Permalink to this heading">
    <svg aria-label="Link Icon" class="leafygreen-ui-a30zj9" fill="none" height="12" role="img" viewbox="0 0 16 16" width="12" xmlns="http://www.w3.org/2000/svg">
     <path d="M6.039 9.953a3.596 3.596 0 0 1-.327-.38l1.45-1.445a1.553 1.553 0 0 0 2.496.423l2.885-2.87a1.57 1.57 0 0 0 .01-2.213 1.553 1.553 0 0 0-2.203-.01l-.379.377A.995.995 0 0 1 8.56 3.83a1.005 1.005 0 0 1 .006-1.418l.38-.377a3.542 3.542 0 0 1 5.024.023 3.58 3.58 0 0 1-.022 5.047l-2.884 2.871a3.542 3.542 0 0 1-5.025-.022Z" fill="currentColor">
     </path>
     <path d="M9.961 6.047c.12.12.228.248.327.38l-1.45 1.445a1.553 1.553 0 0 0-2.496-.423l-2.885 2.87a1.57 1.57 0 0 0-.01 2.213 1.553 1.553 0 0 0 2.203.01l.379-.377a.995.995 0 0 1 1.411.006 1.005 1.005 0 0 1-.006 1.418l-.38.377a3.542 3.542 0 0 1-5.024-.023 3.58 3.58 0 0 1 .022-5.047l2.884-2.871a3.542 3.542 0 0 1 5.025.022Z" fill="currentColor">
     </path>
    </svg>
    <div class="css-1btu0w3 evvkmar0" id="example">
    </div>
   </a>
  </h2>
  <p class="leafygreen-ui-1kp3ins">
   Consider a
   <code class="leafygreen-ui-1l06pbn">
    sales
   </code>
   collection which is sharded on the
   <code class="leafygreen-ui-1l06pbn">
    location
   </code>
   field. The collection contains a document with the
   <code class="leafygreen-ui-1l06pbn">
    _id
   </code>
   <code class="leafygreen-ui-1l06pbn">
    12345
   </code>
   and the
   <code class="leafygreen-ui-1l06pbn">
    location
   </code>
   <code class="leafygreen-ui-1l06pbn">
    ""
   </code>
   . To update the field value for
this document, you can run the following command:
  </p>
  <script class="structured_data" type="application/ld+json">
   {"@context":"https://schema.org","@type":"SoftwareSourceCode","codeSampleType":"code snippet","text":"db.sales.updateOne(\n  { _id: 12345, location: \"\" },\n  { $set: { location: \"New York\"} }\n)","programmingLanguage":"JavaScript"}
  </script>
  <div class="css-16lmvu9">
   <div class="leafygreen-ui-196mwvg">
    <div class="leafygreen-ui-yzcs8i">
     <pre class="leafygreen-ui-11itue3" tabindex="-1"><code class="lg-highlight-hljs-light javascript leafygreen-ui-9ybzas"><table class="leafygreen-ui-1tr4g10"><tbody><tr class=""><td class="leafygreen-ui-7razhx">db.<span class="lg-highlight-property">sales</span>.<span class="lg-highlight-title lg-highlight-function">updateOne</span>(</td></tr><tr class=""><td class="leafygreen-ui-7razhx">  <!-- -->{ <span class="lg-highlight-attr">_id</span>: <span class="lg-highlight-number">12345</span>, <span class="lg-highlight-attr">location</span>: <span class="lg-highlight-string">""</span> }<!-- -->,</td></tr><tr class=""><td class="leafygreen-ui-7razhx">  <!-- -->{ <span class="lg-highlight-attr">$set</span>: <!-- -->{ <span class="lg-highlight-attr">location</span>: <span class="lg-highlight-string">"New York"</span>} }</td></tr><tr class=""><td class="leafygreen-ui-7razhx">)</td></tr></tbody></table></code></pre>
     <div class="leafygreen-ui-1bqcprk" data-testid="leafygreen-code-panel">
      <button aria-disabled="false" aria-label="Copy" class="leafygreen-ui-1c6zwke" data-testid="code_copy-button" tabindex="0">
       <div class="leafygreen-ui-xhlipt">
        <svg aria-label="Copy Icon" class="leafygreen-ui-1st74h4" height="16" role="img" viewbox="0 0 16 16" width="16">
         <path clip-rule="evenodd" d="M1 5.71428V10.2857C1 11.2325 1.76751 12 2.71429 12H5.75V7.10957C5.75 6.54414 5.97724 6.00244 6.38065 5.60623L8.67403 3.35381C8.77447 3.25516 8.88376 3.16757 9 3.09182V2.71429C9 1.76751 8.23249 1 7.28571 1H5.8V4.42857C5.8 5.13865 5.22437 5.71428 4.51429 5.71428H1ZM9 4.78571L7.25654 6.49804C7.24689 6.50752 7.23749 6.5172 7.22834 6.52708C7.22208 6.53383 7.21594 6.54068 7.20991 6.54762C7.07504 6.70295 7 6.90234 7 7.10957V7.79762H9H10.0095C10.4829 7.79762 10.8667 7.41386 10.8667 6.94047V4H10.1505C9.92587 4 9.7102 4.0882 9.54992 4.24562L9 4.78571ZM4.86667 1H4.15053C3.92587 1 3.7102 1.0882 3.54992 1.24562L1.25654 3.49804C1.09244 3.65921 1 3.87957 1 4.10957V4.79762H4.00952C4.48291 4.79762 4.86667 4.41386 4.86667 3.94047V1ZM7 12V8.71428H9H10.5143C11.2244 8.71428 11.8 8.13865 11.8 7.42857V4H13.2857C14.2325 4 15 4.76751 15 5.71429V13.2857C15 14.2325 14.2325 15 13.2857 15H8.71429C7.76751 15 7 14.2325 7 13.2857V12Z" fill="currentColor" fill-rule="evenodd">
         </path>
        </svg>
       </div>
      </button>
     </div>
    </div>
   </div>
  </div>
  <div class="leafygreen-ui-13vw3ie" role="note">
   <h2 class="leafygreen-ui-1fn4p2b">
    Tip
   </h2>
   <h3 class="leafygreen-ui-144d5kf">
    <strong>
     See also:
    </strong>
   </h3>
   <div class="leafygreen-ui-9mycqc">
    <p class="leafygreen-ui-1kp3ins">
     <a class="leafygreen-ui-tqgtui" href="/docs/manual/core/sharding-set-missing-shard-key-fields/#std-label-shard-key-missing-set">
      Set Missing Shard Key Fields
     </a>
    </p>
   </div>
  </div>
 </section>
</section>
