/ /

particionado

Docs Home

/ /

Métodos mongosh

particionado

Docs Home

Manual de base de datos

Referencia

Métodos mongosh

particionado

sh.updateZoneKeyRange() (método mongosh)

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 6.0, consulte Procedimientos de actualización de MongoDB.7.0

Definición

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

Asocia un rango de valores de clave de fragmento con un zona.

Puede ejecutar el comando de base de datosupdateZoneKeyRangey sus ayudantessh.updateZoneKeyRange()ysh.addTagRange()en una colección no fragmentada o en 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 espacio de nombres de la colección fragmentada asociada `zone` con. La colección debe estar fragmentada para que la operación tenga éxito.
`minimum`	Documento	El límite inferior inclusivo del rango de valores de clave de fragmento. Especifique cada campo de la clave de fragmento con el formato `<fieldname> : <value>`. El valor debe ser del mismo tipo o tipos BSON que la clave de fragmento. Para utilizar la fragmentación hash, el valor del campo debe ser del `NumberLong` tipo.
`maximum`	Documento	El límite superior exclusivo del rango de valores de clave de fragmento. Especifique cada campo de la clave de fragmento con el formato `<fieldname> : <value>`. El valor debe ser del mismo tipo o tipos BSON que la clave de fragmento. Para utilizar la fragmentación hash, el valor del campo debe ser del `NumberLong` tipo.
`zone`	string	El nombre de la zona que se asociará con el rango de valores de clave de fragmento delimitado 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 se puede crear un rango de valores de clave de fragmento cuyos límites inferior y superior se superpongan con un rango existente para la colección fragmentada. Por ejemplo, dado un rango existente de 1 a 10, no se puede crear un nuevo rango de 5 a 20, ya que este se superpondría con el rango existente.

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

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

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

Si está considerando realizar la fragmentación de zonas en una colección vacía o inexistente, use sh.updateZoneKeyRange() para crear las zonas y los rangos de zonas antes de fragmentar la colección (desde). A 4.0.2partir 4 0de3 la versión, y, la creación de 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 fragmentar la colección. Este proceso optimizado permite una configuración más rápida de la fragmentación por zonas con menos sobrecarga del balanceador que la creación de zonas después de la fragmentación.El balanceador realiza toda la gestión de fragmentos después de la creación y distribución inicial optimizada de fragmentos.

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

Distribución inicial de fragmentos con claves de fragmentos con hash compuesto

MongoDB admite la fragmentación de colecciones en índices con hash compuesto. Al fragmentar la colección vacía o inexistente en una clave de fragmento con hash compuesto, MongoDB optimiza la creación y distribución inicial de fragmentos.

Si el campo hash es el prefijo de la clave de fragmento (es decir, el primer campo en la clave de fragmento), todo lo siguiente debe ser verdadero para que MongoDB realice la creación y distribución del fragmento inicial:

La colección tiene 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.
sh.shardCollection() especifica la opción presplitHashedZones: true.

Si el campo con hash no es el prefijo de la clave de fragmento (es decir, la clave de fragmento tiene uno o más campos principales no con hash), todo lo siguiente debe ser verdadero para que MongoDB realice la creación y distribución del fragmento inicial:

La colección tiene un rango de zona para cada combinación de valores de campo de prefijo distintos (es decir, todos los campos que preceden al campo hash).
Para el límite inferior de cada rango de zona, especifique MinKey para el campo con hash y todos los campos subsiguientes.
Para cada rango de zona, al menos un campo de prefijo de límite superior debe ser diferente de su contraparte de límite inferior.
sh.shardCollection() especifica la opción presplitHashedZones: true.

Para obtener un ejemplo más completo de cómo definir zonas y rangos de zonas para la distribución inicial de fragmentos en una clave de fragmento con hash compuesto, consulte Predefinir zonas y rangos de zonas para una colección vacía o inexistente.

Tip

sh.balancerCollectionStatus()

Balanceador

Tras asociar un rango a una zona, el balanceador debe ejecutarse primero para migrar los fragmentos cuyos rangos estén cubiertos por la zona a fragmentos dentro de ella. Hasta que se complete el balanceo, algunos fragmentos podrían residir en el fragmento incorrecto según las zonas configuradas para el clúster fragmentado.Consulte Balanceador para obtener más información.

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

Límites

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

Colecciones abandonadas

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 fragmentados que se ejecutan con autenticación, debe autenticarse como:

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

Los roles clusterAdmin integrados o clusterManager tienen los permisos adecuados para sh.updateZoneKeyRange() emitir. Consulte la página de documentación sobre el control de acceso basado en roles para obtener más información.

Ejemplos

Dada una colección fragmentada exampledb.collection con una clave de fragmento de { 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 previamente pasando null al campo zone.

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

Los valores min y max deben coincidir exactamente con los límites del rango objetivo. La siguiente operación intenta eliminar 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 de fragmento compuesto

Dada una colección fragmentada exampledb.collection con una clave de fragmento de { a : 1, b : 1 }, la siguiente operación crea un rango que cubre 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"
)

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

Si crea zonas y rangos de zonas en colecciones vacías o inexistentes, MongoDB puede 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 la fragmentación por zonas con menos sobrecarga del balanceador que la creación de zonas después de la fragmentación. El balanceador realiza toda la gestión de fragmentos tras la creación y distribución inicial optimizada de fragmentos. Para más información, consulte "Distribución inicial de fragmentos con claves de fragmento con hash compuesto".

Las secciones siguientes contienen ejemplos de tres tipos de claves de fragmento diferentes.

Considere los siguientes ejemplos, que exploran la predefinición de zonas o rangos de zonas para tres tipos de claves de fragmento diferentes:

Claves de fragmentos simples o compuestos
Clave de fragmento con hash compuesto y prefijo con hash
Clave de fragmento con hash compuesto y campo con hash sin prefijo

Claves de fragmentos simples o compuestos

Nota

Este ejemplo solo se aplica a claves de fragmentos compuestos o de un solo campo sin un campo hash.

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

Crear las zonas

Utilice para crear las sh.addShardToZone() zonas:

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

Crear los rangos de zonas

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

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

Fragmentar la colección

Nota

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

Si la colección está vacía y no existe ningún índice que admita la clave de fragmentación, la operación de fragmentación crea el índice.

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

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

Revisar los fragmentos creados y la distribución

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

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",  "partitioned" : true }
        {  "_id" : "exampledb",  "primary" : "shardA",  "partitioned" : true,  "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 fragmentación creó 5 fragmentos (dos fragmentos que corresponden a los rangos de zona y los otros tres para cubrir todos los demás valores) en el fragmento A y el fragmento B.

Clave de fragmento con hash compuesto y prefijo con hash

Nota

Este ejemplo solo se aplica a claves de fragmento compuestas con hash donde el campo con hash es el prefijo de la clave de fragmento (es decir, el primer campo de la clave de fragmento está con 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.

Considere una colección vacía examples.metrics que almacenará análisis de una de dos plantas de fabricación. La clave de fragmento planificada { "_id" : "hashed", "facility" : 1} es, donde el campo con hash es el prefijo de la clave de fragmento.

Crear las zonas

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

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

Crear los rangos de zonas

La distribución inicial de fragmentos en una clave de fragmento con hash compuesto y un prefijo con 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.

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

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

Fragmentar la colección

Nota

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

Si la colección está vacía y no existe ningún índice que admita la clave de fragmentación, la operación de fragmentación 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 }
)

Revisar los fragmentos creados y la distribución

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

sh.status()

El resultado se parece al siguiente (contenidoomitido para facilitar la lectura):

--- Sharding Status ---
databases:
  {  "_id" : "config",  "primary" : "config",  "partitioned" : true }
  {  "_id" : "examples",  "primary" : "shardA",  "partitioned" : true,  "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 fragmentación generó 4 fragmentos en total. Dos fragmentos corresponden a los límites inferior y superior absolutos. Se creó una zona en shardA y shardB, correspondiente a FacilityAlpha. La zona se subdividió en 2 fragmentos mediante el campo hash.

Clave de fragmento con hash compuesto y campo con hash sin prefijo

Nota

Este ejemplo solo se aplica a claves de fragmento con hash compuesto donde el campo con hash no es el prefijo de la clave de fragmento (es decir, el primer campo en la clave de fragmento no está con hash).

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

Considere una colección vacía examples.metrics que almacenará análisis de una de dos plantas de fabricación. La clave de fragmento planificada { "facility" : 1, "_id" : "hashed" } es, donde el campo con hash no es el prefijo de la clave de fragmento.

El campo facility almacena el nombre de la instalación: "FacilityAlpha" o "FacilityBaker". La colección requiere rangos de zona en facility para aislar los datos de cada instalación en fragmentos 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

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

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

Crear los rangos de zonas

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

La distribución inicial de fragmentos en una clave de fragmento con hash compuesto, 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 con hash). Dado que facility tiene dos valores de prefijo distintos, la colección requiere exactamente dos rangos de zona que cubran esos valores.

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

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

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

Dado que los límites superiores del rango de zona son exclusivos, este rango solo cubre documentos con el valor de prefijo de clave de fragmento distinto "facilty" : "FacilityAlpha" y todos los valores posibles _id de.

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

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

Si bien el límite superior de este rango técnicamente puede capturar 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 los documentos con el valor de prefijo de clave de fragmento distinto "facility" : "FacilityBaker" y todos los valores posibles de _id.

Fragmentar la colección

Nota

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

Si la colección está vacía y no existe ningún índice que admita la clave de fragmentación, la operación de fragmentación 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 }
)

Revisar los fragmentos creados y la distribución

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

sh.status()

El resultado se parece al siguiente (contenidoomitido para facilitar la lectura):

--- Sharding Status ---
  databases:
    {  "_id" : "config",  "primary" : "config",  "partitioned" : true }
    {  "_id" : "examples",  "primary" : "shardA",  "partitioned" : true,  "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 fragmentación generó 6 fragmentos en total. 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 subdividió en 2 fragmentos mediante el campo hash.

Tip

Volver

sh.stopBalancer

sh.esperaAlEquilibrador