sh.splitAt.txt

============
sh.splitAt()
============

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: sh.splitAt(namespace, query)

   Splits a chunk at the shard key value specified by the query.

   .. |dbcommand| replace:: :dbcommand:`split` command
   .. include:: /includes/fact-mongosh-shell-method-alt.rst


   The method takes the following arguments:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
   
        - Type
   
        - Description
   
      * - ``namespace``
   
        - string
   
        - The namespace (i.e. ``<database>.<collection>``) of the sharded
          collection that contains the chunk to split.
          
          
   
      * - ``query``
   
        - document
   
        - A query document that specifies the :term:`shard key` value at which
          to split the chunk.
          
Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-no-free.rst

.. include:: /includes/fact-environments-onprem-only.rst

Consideration
-------------

In most circumstances, you should leave chunk splitting to the
automated processes within MongoDB. However, when initially deploying a
:term:`sharded cluster`, it may be beneficial to :term:`pre-split
<pre-splitting>` manually an empty collection using methods such as
:method:`sh.splitAt()`.


Behavior
--------

:method:`sh.splitAt()` splits the original chunk into two chunks. One
chunk has a shard key range that starts with the original lower bound
(inclusive) and ends at the specified shard key value (exclusive). The
other chunk has a shard key range that starts with the specified shard
key value (inclusive) as the lower bound and ends at the original upper
bound (exclusive).

To split a chunk at its median point instead, see
:method:`sh.splitFind()`.

Example
-------

For the sharded collection ``test.foo``, the following example splits a
chunk at the shard key value ``x: 70``.

.. code-block:: javascript

   sh.splitAt( "test.foo", { x: 70 } )