sh.updateZoneKeyRange() (método mongosh)

Definición

sh.updateZoneKeyRange(namespace, minimum, maximum, zone)

Asocia un rango de valor de la clave de partición con una zona.

Puedes ejecutar el comando de base de datos updateZoneKeyRange y sus asistentes sh.updateZoneKeyRange() y sh.addTagRange() en una colección no particionada o una colección inexistente.

Importante

Método mongosh

Esta página documenta un método mongosh. Esta no es la documentación para los comandos de base de datos ni para los drivers específicos de lenguajes, como Nodo.js.

Para el comando de base de datos, consulta el comando updateZoneKeyRange.

Para los drivers de API de MongoDB, consulte la documentación del driver de MongoDB específica del lenguaje.

sh.updateZoneKeyRange() toma los siguientes argumentos:

Parameter	Tipo	Descripción
`namespace`	string	El namespace de la colección fragmentada asociada con el `zone`. La colección debe estar particionada para que la operación tenga éxito.
`minimum`	Documento	El límite inferior inclusivo del rango de valores de la clave de partición. Especifique cada campo de la clave de partición en la forma de `<fieldname> : <value>`. El valor debe ser del mismo tipo BSON o tipos que la clave de partición. Para usar particionado con hash, el valor del campo debe ser de tipo `NumberLong`.
`maximum`	Documento	El límite superior exclusivo del rango de valores de la clave de partición. Especifique cada campo de la clave de partición en la forma de `<fieldname> : <value>`. El valor debe ser del mismo tipo BSON o tipos que la clave de partición. Para usar particionado con hash, el valor del campo debe ser de tipo `NumberLong`.
`zone`	string	El nombre de la zona con la que asociar el rango de valores de la clave de partición delimitados por `minimum` y `maximum`.

Solo emite sh.updateZoneKeyRange() cuando estés conectado a una instancia mongos.

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Importante

Este comando no es compatible con los clústeres M0 y Flex. Para obtener más información, consulta Comandos no compatibles.

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Comportamiento

No puedes crear un rango de valores de la clave de partición cuyos límites inferior y superior se superpongan con un rango existente para la colección particionada. Por ejemplo, dado un **rango** existente de 1 a 10, no puede crear un nuevo **rango** de 5 a 20, ya que el nuevo **rango** se superpondría con el **rango** existente.

Una zona puede tener múltiples rangos de datos asociados a ella, pero un rango como máximo puede estar asociado con una sola zona.

Consulte la página del manual de zonas para obtener más información sobre las zonas en clústeres particionados.

Distribución inicial de fragmentos para colecciones vacías o inexistentes

Si estás considerando realizar particionado de zonas en una colección vacía o inexistente, utiliza sh.updateZoneKeyRange() para crear las zonas y rangos de zonas antes de dividir la colección (desde la versión 4.0.2). A partir de la versión 4.0.3, crear zonas y rangos de zonas en colecciones vacías o inexistentes permite a MongoDB optimizar el proceso inicial de creación y distribución de fragmentos al particionar la colección. Este proceso optimizado permite una configuración más rápida de particionamiento por zonas con menos sobrecarga del equilibrador que la creación de zonas después del particionamiento. El balanceador realiza toda la gestión de fragmentos después de la optimización inicial de creación y distribución de fragmentos.

Para un ejemplo de cómo definir zonas y rangos de zonas para la distribución inicial de fragmentos, consulta Predefine zonas y rangos de zonas para una colección vacía o inexistente.

Distribución inicial de fragmentos con claves de partición compuestas con hash

MongoDB ofrece soporte al particionado de colecciones en índices compuestos encriptados. MongoDB puede realizar una creación y distribución optimizadas de particiones iniciales al fragmentar la colección vacía o inexistente usando una clave de partición compuesta con hash.

Si el campo encriptada es el prefijo de la clave de partición (es decir, el primer campo en la clave de partición), todo lo siguiente debe ser cierto para que MongoDB realice la creación inicial y la distribución de fragmentos:

La colección tiene un único rango de zona con MinKey para todos los campos límite inferior y MaxKey para todos los campos límite superior.
sh.shardCollection() especifica la opción presplitHashedZones: true.

Si el campo encriptado no es el prefijo de la clave de partición (es decir, la clave de partición tiene uno o más campos iniciales no encriptados), deben cumplirse todas las siguientes condiciones para que MongoDB realice la creación y distribución inicial de fragmentos:

La colección tiene un rango de zona para cada combinación de valores de campo de prefijo distintos (es decir, todos los campos anteriores al campo encriptado).
Para el límite inferior de cada rango de zona, especifica MinKey para el campo encriptada y todos los campos posteriores.
Para cada rango de zona, al menos un campo de prefijo de límite superior debe diferir de su equivalente en el límite inferior.
sh.shardCollection() especifica la opción presplitHashedZones: true.

Para un ejemplo más completo de cómo definir zonas y rangos de zonas para la distribución inicial de fragmentos en una claves de partición compuestas con hash, consulte Predefine zonas y rangos de zonas para una colección vacía o inexistente.

Tip

sh.balancerCollectionStatus()

Balanceador

Después de asociar un rango a una zona, el balanceador debe ejecutarse primero para migrar cualquier fragmento cuyos rangos estén cubiertos por la zona a las particiones en el interior de dicha zona. Hasta que se complete el equilibrio, algunos fragmentos pueden residir en la partición incorrecta dada la zonas configuradas para el clúster. Consulte balanceador para obtener más información.

Consulta la página del manual de balanceador de clúster para obtener más información sobre cómo funcionan las migraciones en un clúster.

Límites

Los rangos de zona siempre incluyen el límite inferior y excluyen el límite superior.

Colecciones descartadas

Al descartar una colección, se borran sus rangos de zona/etiqueta asociados.

En versiones anteriores, MongoDB no remueve las asociaciones de etiquetas de una colección descartada y, si luego creas una nueva colección con el mismo nombre, las asociaciones de etiquetas antiguas se aplicarán a la nueva colección.

Seguridad

Para los clústeres particionados que se ejecutan con autenticación, debes autenticarte como:

un usuario cuyos privilegios incluyen las acciones especificadas en varias colecciones de la base de datos config:
- find en la colección config.shards
- find y update en la colección config.tags;
o, alternativamente,
un usuario cuyos privilegios incluyan enableSharding sobre el recurso clúster.

Las clusterAdmin o clusterManager roles integradas tienen los permisos adecuados para emitir sh.updateZoneKeyRange(). Consulta la página de documentación sobre Control de Acceso Basado en Roles para obtener más información.

Ejemplos

Dada una colección particionada exampledb.collection con una clave de partición { a : 1 }, la siguiente operación crea un rango con un límite inferior de 1 y un límite superior de 10 en la zona alpha:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   "alpha"
)

La siguiente operación elimina el rango creado anteriormente al pasar null al campo zone.

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   null
)

El min y el max deben coincidir exactamente con los límites del rango objetivo. La siguiente operación intenta remover el rango creado previamente, pero especifica { a : 0 } como el límite min:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 0 },
   { a : 10 },
   null
)

Aunque el rango de { a : 0 } y { a : 10 } abarca el rango existente, no es una coincidencia exacta y, por lo tanto, updateZoneKeyRange no remueve nada.

Clave compuesta de fragmento

Dada una colección particionada exampledb.collection con una clave de partición de { a : 1, b : 1 }, la siguiente operación crea un rango que abarca el límite inferior de { a: 1, b : 1 } y un límite superior de { a : 10, b : 10}, y lo asocia con la zona alpha:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1, b : 1 },
   { a : 10, b : 10 },
   "alpha"
)

Predecir zonas y rangos de zonas para una colección vacía o inexistente

Si creas zonas y rangos de zonas en colecciones vacías o inexistentes, MongoDB podría optimizar el proceso inicial de creación y distribución de fragmentos al fragmentar la colección. Este proceso optimizado permite una configuración más rápida de particionamiento zonificado con menos sobrecarga de balanceador que la creación de zonas después del particionamiento. El balanceador realiza toda la gestión de fragmentos después de la creación y distribución inicial optimizada de fragmentos. Para obtener más información, consulta Distribución Inicial de fragmentos con claves de partición compuestas con hash para obtener más información.

Las secciones siguientes contienen ejemplos de tres tipos diferentes de claves de partición.

Considera los siguientes ejemplos, que exploran la predefinición de zonas o rangos de zonas para tres tipos diferentes de clave de partición:

Claves de partición únicas o compuestas
Clave de partición compuesta con hash con prefijo hash
Clave de partición compuesta encriptada con campo encriptado sin prefijo

Claves de partición únicas o compuestas

Nota

Este ejemplo solo se aplica a claves de partición de un solo campo o compuestas sin un campo encriptada.

Por ejemplo, { "zip" : 1 } o { "zip" : 1, "account" : 1}

Crear las zonas

Utilice sh.addShardToZone() para crear las zonas:

sh.addShardToZone("shardA", "DC1")
sh.addShardToZone("shardB", "DC2")

Crear los rangos de zonas

Utiliza sh.updateZoneKeyRange() para crear los rangos para la colección vacía contacts en la base de datos exampledb:

sh.updateZoneKeyRange(
    "exampledb.contacts",
    { zip: 10001 },
    { zip: 10090 },
    "DC1"
);
sh.updateZoneKeyRange(
    "exampledb.contacts",
    { zip: 90001 },
    { zip: 96054 },
    "DC2"
);

Fragmenta la colección

Nota

Si la colección no existe, la operación de particionado crea la colección.

Si la colección está vacía y no existe un índice que admita la clave de partición, la operación de particionado crea el índice.

Utiliza sh.shardCollection() para fragmentar la colección contacts:

sh.shardCollection("exampledb.contacts",  { zip: 1 } );

Revisa los fragmentos creados y su distribución

Para ver los fragmentos creados y su distribución, ejecuta la operación sh.status():

sh.status()

El método devuelve:

--- Sharding Status ---
  sharding version: {
    "_id" : 1,
    "minCompatibleVersion" : 5,
    "currentVersion" : 6,
    "clusterId" : ObjectId("5b80c06d35a961fd0ae1986d")
  }
  shards:
        {  "_id" : "shardA",  "host" : "shardA/mongodb0.example.net:27018,mongodb1.example.net:27018,mongodb2.example.net:27018",  "state" : 1,  "tags" : [ "DC1" ] }
        {  "_id" : "shardB",  "host" : "shardB/mongodb3.example.net:27018,mongodb4.example.net:27018,mongodb5.example.net:27018",  "state" : 1,  "tags" : [ "DC2" ] }
  active mongoses:
        "4.2.0" : 2
  autosplit:
        Currently enabled: yes
  balancer:
        Currently enabled:  yes
        Currently running:  no
        Failed balancer rounds in last 5 attempts:  0
        Migration Results for the last 24 hours:
                No recent migrations
  databases:
        { "_id" : "config", "primary" : "config" }
        { "_id" : "exampledb", "primary" : "shardA", "version" : { "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"), "lastMod" : 1 } }
                exampledb.contacts
                        shard key: { "zip" : 1 }
                        unique: false
                        balancing: true
                        chunks:
                                shardA   3
                                shardB   2
                        { "zip" : { "$minKey" : 1 } } -->> { "zip" : 10001 } on : shardA Timestamp(1, 0)
                        { "zip" : 10001 } -->> { "zip" : 10090 } on : shardA Timestamp(1, 1)
                        { "zip" : 10090 } -->> { "zip" : 90001 } on : shardB Timestamp(1, 2)
                        { "zip" : 90001 } -->> { "zip" : 96054 } on : shardB Timestamp(1, 3)
                        { "zip" : 96054 } -->> { "zip" : { "$maxKey" : 1 } } on : shardA Timestamp(1, 4)
                          tag: DC1  { "zip" : 10001 } -->> { "zip" : 10090 }
                          tag: DC2  { "zip" : 90001 } -->> { "zip" : 96054 }

Para la colección, la operación de particionado creó 5 fragmentos (dos fragmentos que corresponden a los rangos de zonas y los otros tres para cubrir todos los demás valores) en shardA y shardB.

Clave de partición compuesta con hash con prefijo hash

Nota

Este ejemplo solo se aplica a claves de partición compuestas con hash donde el campo con hash es el prefijo de la clave de partición (es decir, el primer campo de la clave de partición se divide en hash).

Por ejemplo, { "_id" : "hashed", "facility" : 1 }

MongoDB admite el particionado sobre índices encriptada compuestos. Al particionar en claves de partición compuestas con hash, MongoDB puede realizar una creación y distribución inicial optimizada de fragmentos sobre la colección vacía o inexistente solo si los rangos de zona definidos cumplen requisitos adicionales.

Considera una colección vacía examples.metrics que almacenará análisis de una de las dos instalaciones de fabricación. La clave de partición prevista es { "_id" : "hashed", "facility" : 1}, donde el campo encriptada es el prefijo de la clave de partición.

Crear las zonas

La clave de partición planificada es { "_id" : "hashed", "facility" : 1 }. Dado que el campo encriptada es el prefijo (es decir, el primer campo en la clave de partición), cree una zona única usando sh.addShardToZone():

sh.addShardToZone("shardA", "FacilityAlpha")
sh.addShardToZone("shardB", "FacilityAlpha")

Crear los rangos de zonas

La distribución inicial de fragmentos en una clave de fragmentación con hash compuesta con un prefijo de hash requiere un rango de zona único con MinKey para todos los campos de límite inferior y MaxKey para todos los campos de límite superior.

Usa sh.updateZoneKeyRange() para crear un solo rango:

sh.updateZoneKeyRange(
   "examples.metrics",
   { "_id" : MinKey, "facility" : MinKey },
   { "_id" : MaxKey, "facility" : MaxKey },
   "FacilityAlpha"
);

Fragmenta la colección

Nota

Si la colección no existe, la operación de particionado crea la colección.

Si la colección está vacía y no existe un índice que admita la clave de partición, la operación de particionado crea el índice.

Usar sh.shardCollection() con presplitHashedZones: true para particionar la colección y realizar la creación y distribución inicial de fragmentos:

sh.shardCollection(
  "examples.metrics",
  { "_id" : "hashed", "facility" : 1 },
  false,
  { presplitHashedZones: true }
)

Revisa los fragmentos creados y su distribución

Para ver los fragmentos creados y su distribución, ejecuta la operación sh.status():

sh.status()

La salida se asemeja a lo siguiente (contenido omitido por legibilidad):

--- Sharding Status ---
databases:
  { "_id" : "config", "primary" : "config" }
  { "_id" : "examples", "primary" : "shardA", "version" : { "uuid" : UUID("245f8abf-a363-48b0-8208-2a5b577bbb4e"), "lastMod" : 1 } }
    examples.metrics
      shard key: { "_id" : "hashed", "facility" : 1 }
      unique: false
      balancing: true
      chunks:
        shardA  2
        shardB  2
      { "_id" : { "$minKey" : 1 }, "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong("-4611686018427387902"), "facility" : { "$minKey" : 1 } } on : shardA Timestamp(1, 0)
      { "_id" : NumberLong("-4611686018427387902"), "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong(0), "facility" : { "$minKey" : 1 } } on : shardA Timestamp(1, 1)
      { "_id" : NumberLong(0), "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong("4611686018427387902"), "facility" : { "$minKey" : 1 } } on : shardB Timestamp(1, 2)
      { "_id" : NumberLong("4611686018427387902"), "facility" : { "$minKey" : 1 } } -->> { "_id" : { "$maxKey" : 1 }, "facility" : { "$maxKey" : 1 } } on : shardB Timestamp(1, 3)
        tag: FacilityAlpha  { "_id" : { "$minKey" : 1 }, "facility" : { "$minKey" : 1 } } -->> { "_id" : { "$maxKey" : 1 }, "facility" : { "$maxKey" : 1 } }

La operación de particionado generó un total de 4 fragmentos. Dos fragmentos corresponden a los límites inferiores y superiores absolutos. Se creó una zona en shardA y shardB correspondiente a FacilityAlpha. La zona se subdividió en 2 fragmentos utilizando el campo encriptada.

Clave de partición compuesta encriptada con campo encriptado sin prefijo

Nota

Este ejemplo sólo se aplica a claves de partición compuestas con hash donde el campo con hash no es el prefijo de la clave de partición (es decir, el primer campo en la clave de partición no está hasheado).

Por ejemplo, { "facility" : 1, "_id" : "hashed" }

Considere una colección vacía examples.metrics que almacenará análisis de una de las dos instalaciones de fabricación. La clave de partición planificada es { "facility" : 1, "_id" : "hashed" }, donde el campo encriptada NO es el prefijo clave de partición.

El campo facility almacena el nombre del establecimiento: "FacilityAlpha" o "FacilityBaker". La colección requiere rangos de zonas en facility para ayudar a aislar los datos de cada instalación a particiones específicos.
El campo _id compensa la baja cardinalidad del campo facility. El hash compensa la naturaleza monótonamente creciente del campo _id.

Crear las zonas

Use el comando sh.addShardToZone() para crear las zonas.

sh.addShardToZone("shardA", "FacilityAlpha")
sh.addShardToZone("shardB", "FacilityBaker")

Crear los rangos de zonas

La clave de partición planificada es {"facility" : 1, "_id" : "hashed"}. El campo facility tiene dos valores posibles: FacilityAlpha y FacilityBaker.

La distribución inicial de fragmentos en claves de partición compuestas con hash donde el campo con hash no es el prefijo requiere un rango de zona para cada combinación de valores de campo de prefijo distintos (es decir, todos los campos que preceden al campo encriptada). Dado que facility tiene dos valores de prefijo distintos, la colección requiere exactamente dos rangos de zonas que cubran esos valores.

El rango de límite inferior especifica MinKey para todos los campos que no son prefijos.
El rango superior tiene al menos un campo de prefijo que difiere de su contraparte inferior.

Utiliza sh.updateZoneKeyRange() para crear el rango para "facility": "FacilityAlpha":

sh.updateZoneKeyRange(
   "examples.metrics",
   { "facility": "FacilityAlpha", "_id" : MinKey },
   { "facility": "FacilityBaker", "_id" : MinKey },
   "FacilityAlpha"
);

Dado que los límites superiores del rango de zonas son exclusivos, este rango sólo cubre documentos con el valor del prefijo de clave de partición distinto "facilty" : "FacilityAlpha" y todos los valores posibles de _id.

Utiliza sh.updateZoneKeyRange() para crear el rango para "facility": "FacilityBaker":

sh.updateZoneKeyRange(
   "examples.metrics",
   { "facility": "FacilityBaker", "_id" : MinKey },
   { "facility": MaxKey, "_id" : MinKey },
   "FacilityBaker"
);

Aunque el límite superior de este rango puede captar técnicamente otros valores de facility, la lógica inicial de distribución de fragmentos se basa en la suposición de que no existen otros valores distintos para facility. Dado que la colección solo contiene documentos donde facility es FacilityAlpha o FacilityBaker, este rango solo cubre documentos con el valor de prefijo único de clave de partición "facility" : "FacilityBaker" y todos los posibles valores de _id.

Fragmenta la colección

Nota

Si la colección no existe, la operación de particionado crea la colección.

Si la colección está vacía y no existe un índice que admita la clave de partición, la operación de particionado crea el índice.

Usar sh.shardCollection() con presplitHashedZones: true para particionar la colección y realizar la creación y distribución inicial de fragmentos:

sh.shardCollection(
  "examples.metrics",
  { "facility" : 1, "_id" : "hashed"},
  false,
  { presplitHashedZones: true }
)

Revisa los fragmentos creados y su distribución

Para ver los fragmentos creados y su distribución, ejecuta la operación sh.status():

sh.status()

La salida se asemeja a lo siguiente (contenido omitido por legibilidad):

--- Sharding Status ---
  databases:
    { "_id" : "config", "primary" : "config" }
    { "_id" : "examples", "primary" : "shardA", "version" : { "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"), "lastMod" : 1 } }
      examples.metrics
        shard key: { "facility" : 1, "_id" : "hashed" }
        unique: false
        balancing: true
        chunks:
          shardA  3
          shardB  3
        { "facility" : { "$minKey" : 1 }, "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } on : shard1 Timestamp(1, 0)
        { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityAlpha", "_id" : NumberLong(0) } on : shard1 Timestamp(1, 1)
        { "facility" : "FacilityAlpha", "_id" : NumberLong(0) } -->> { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } on : shard1 Timestamp(1, 2)
        { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityBaker", "_id" : NumberLong(0) } on : shard2 Timestamp(1, 3)
        { "facility" : "FacilityBaker", "_id" : NumberLong(0) } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } } on : shard2 Timestamp(1, 4)
        { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$maxKey" : 1 } } on : shard2 Timestamp(1, 5)
          tag: FacilityAlpha  { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } }
          tag: FacilityBaker  { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } }

La operación de particionado produjo un total de 6 fragmentos. Dos fragmentos corresponden a los límites absolutos inferior y superior. Se crearon dos zonas, una en shardA y otra en shardB, correspondientes a FacilityAlpha y FacilityBaker. Cada una de estas zonas se ha subdividido aún más en 2 fragmentos utilizando el campo encriptada.

Tip

Volver

sh.unshardCollection

sh.waitForBalancer