Usa comandos de la extensión de MongoDB para administrar los datos almacenados en la API de Azure Cosmos DB para MongoDB

SE APLICA A: Azure Cosmos DB API para MongoDB

El siguiente documento contiene los comandos de acción personalizada que son específicos de la API de Azure Cosmos DB para MongoDB. Estos comandos se pueden usar para crear y obtener recursos de base de datos específicos del modelo de capacidad de Azure Cosmos DB.

Mediante las API de Azure Cosmos DB para MongoDB, puede disfrutar de las ventajas de Cosmos DB, como distribución global, particionamiento automático, alta disponibilidad, garantías de latencia, cifrado en reposo automático, copias de seguridad, y muchas más, a la vez que conserva su inversión en la aplicación de MongoDB. Puede comunicarse con la API de Azure Cosmos DB para MongoDB con cualquiera de los controladores de cliente de MongoDB de código abierto. La API de Azure Cosmos DB para MongoDB permite usar los controladores de cliente existentes mediante la adhesión al protocolo de conexión de MongoDB.

Compatibilidad de protocolo para MongoDB

La API de Azure Cosmos DB para MongoDB es compatible de manera predeterminada con la versión 4.0, 3.6 y 3.2 del servidor de MongoDB. Consulte la sintaxis y las características admitidas en los artículos 4.0, 3.6 y 3.2 para obtener más detalles.

Los siguientes comandos de extensión proporcionan la capacidad de crear y modificar recursos específicos de Azure Cosmos DB a través de solicitudes de base de datos:

• Crear una base de datos
• Actualizar una base de datos
• Obtener una base de datos
• Crear una colección
• Actualizar una colección
• Obtener una colección

Crear una base de datos

El comando de extensión de creación de base de datos crea una nueva base de datos de MongoDB. El nombre de la base de datos se puede usar desde el contexto de base de datos establecido por el comando use database. En la siguiente tabla se describen los parámetros del comando:

Output

Si el comando se ejecuta correctamente, devolverá la siguiente respuesta:

{ "ok" : 1 }

Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Crear una base de datos

Para crear una base de datos denominada "test" que use todos los valores predeterminados, use el siguiente comando:

use test
db.runCommand({customAction: "CreateDatabase"});

Este comando crea una base de datos sin rendimiento en el nivel de base de datos. Esto significa que las colecciones de esta base de datos tendrán que especificar la cantidad de rendimiento que se debe usar.

Creación de una base de datos con rendimiento

Para crear una base de datos denominada "test" y especificar un rendimiento aprovisionado en el nivel de base de datos de 1000 RU/s, use el siguiente comando:

use test
db.runCommand({customAction: "CreateDatabase", offerThroughput: 1000 });

Se creará una base de datos y se establecerá un rendimiento en ella. Todas las colecciones de esta base de datos compartirán el rendimiento establecido, a menos que las colecciones se creen con un nivel de rendimiento específico.

Creación de una base de datos con rendimiento de escalabilidad automática

Para crear una base de datos denominada "test" y especificar un rendimiento máximo de escalabilidad automática de 20 000 RU/s en el nivel de base de datos, use el siguiente comando:

use test
db.runCommand({customAction: "CreateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Actualizar una base de datos

El comando de extensión de actualización de la base de datos actualiza las propiedades asociadas con la base de datos especificada. Solo se admite en Azure Portal el cambio de la base de datos de rendimiento aprovisionado a la escalabilidad automática, y viceversa. En la siguiente tabla se describen los parámetros del comando:

Este comando usa la base de datos especificada en el contexto de la sesión. Esta es la base de datos usada en el comando use <database>. En este momento, no se puede cambiar el nombre de la base de datos con este comando.

Output

Si el comando se ejecuta correctamente, devolverá la siguiente respuesta:

{ "ok" : 1 }

Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Actualización del rendimiento aprovisionado asociado con una base de datos

Para actualizar el rendimiento aprovisionado de una base de datos con nombre "test" a 1200 RU/s, use el siguiente comando:

use test
db.runCommand({customAction: "UpdateDatabase", offerThroughput: 1200 });

Actualización del rendimiento de escalabilidad automática asociado con una base de datos

Para actualizar el rendimiento aprovisionado de una base de datos con el nombre "test" a 20 000 RU/s, o para transformarla en un nivel de rendimiento de escalabilidad automática, use el siguiente comando:

use test
db.runCommand({customAction: "UpdateDatabase", autoScaleSettings: { maxThroughput: 20000 } });

Obtener una base de datos

El comando de extensión de obtención de una base de datos devuelve el objeto de base de datos. El nombre de la base de datos se usa desde el contexto de la base de datos donde se ejecuta el comando.

{
  customAction: "GetDatabase"
}

En la siguiente tabla se describen los parámetros del comando:

Output

Si el comando se ejecuta correctamente, la respuesta contiene un documento con los siguientes campos:

Si no se puede ejecutar el comando, se devuelve una respuesta de comando personalizado de forma predeterminada. Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Obtención de la base de datos

Con el fin de crear el objeto de base de datos para una base de datos denominada "test", use el comando siguiente:

use test
db.runCommand({customAction: "GetDatabase"});

Si la base de datos no tiene ningún rendimiento asociado, el resultado sería:

{ "database" : "test", "ok" : 1 }

Si la base de datos tiene un rendimiento manual en el nivel de base datos asociado a ella, la salida mostraría los valores de provisionedThroughput:

{ "database" : "test", "provisionedThroughput" : 20000, "ok" : 1 }

Si la base de datos tiene un rendimiento de escalabilidad automática en el nivel de base de datos asociado a ella, la salida mostraría provisionedThroughput, que describe la cantidad mínima de RU/s para la base de datos, y el objeto autoScaleSettings, incluido maxThroughput, que describe el valor de RU/s máximo para la base de datos.

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
                "maxThroughput" : 20000
        },
        "ok" : 1
}

Crear una colección

El comando de extensión de creación de colección crea una nueva colección de MongoDB. El nombre de la base de datos se usa desde el contexto de base de datos establecido por el comando use database. El formato del comando CreateCollection es el siguiente:

{
  customAction: "CreateCollection",
  collection: "<Collection Name>",
  shardKey: "<Shard key path>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" to use Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

En la siguiente tabla se describen los parámetros del comando:

Output

Devuelve una respuesta predeterminada del comando personalizado. Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Creación de una colección con la configuración mínima

Para crear una colección con el nombre "testCollection" y los valores predeterminados, use el siguiente comando:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection"});

Se generará una colección fija, sin particiones, con 400 RU/s y un índice en el campo _id creado automáticamente. Este tipo de configuración también se aplicará al crear colecciones a través de la función insert(). Por ejemplo:

use test
db.newCollection.insert({});

Creación de una colección sin particiones

Para crear una colección sin particiones con el nombre "testCollection" y el rendimiento aprovisionado de 1000 RU/s, use el siguiente comando:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 1000});

Puede crear una colección de hasta 10 000 RU/s como offerThroughput sin necesidad de especificar una clave de partición. En el caso de colecciones con mayor rendimiento, consulte la sección siguiente.

Creación de una colección con particiones

Para crear una colección con particiones con el nombre "testCollection" y el rendimiento aprovisionado de 11 000 RU/s, y una propiedad shardkey "a.b", use el siguiente comando:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", offerThroughput: 11000, shardKey: "a.b" });

Este comando requiere ahora el parámetro shardKey, ya que se han especificado más de 10 000 RU/s en offerThroughput.

Creación de una colección de escalabilidad automática sin particiones

Para crear una colección sin particiones denominada 'testCollection' que use la capacidad de rendimiento de escalabilidad automática establecida en 4000 RU/s, use el siguiente comando:

use test
db.runCommand({ 
    customAction: "CreateCollection", collection: "testCollection", 
    autoScaleSettings:{
      maxThroughput: 4000
    } 
});

En el valor de autoScaleSettings.maxThroughput puede especificar un intervalo de 4000 RU/s a 10 000 RU/s sin una clave de partición. Para un mayor rendimiento de escalabilidad automática, debe especificar el parámetro shardKey.

Creación de una colección de escalabilidad automática con particiones

Para crear una colección con particiones denominada 'testCollection' con una clave de partición denominada 'a.b' y que use la capacidad de rendimiento de escalabilidad automática establecida en 20 000 RU/s, use el siguiente comando:

use test
db.runCommand({customAction: "CreateCollection", collection: "testCollection", shardKey: "a.b", autoScaleSettings: { maxThroughput: 20000 }});

Actualizar una colección

El comando de extensión de actualización de la colección actualiza las propiedades asociadas con la colección especificada. Solo se admite en Azure Portal el cambio de la colección de rendimiento aprovisionado a la escalabilidad automática, y viceversa.

{
  customAction: "UpdateCollection",
  collection: "<Name of the collection that you want to update>",
  // Replace the line below with "autoScaleSettings: { maxThroughput: (int) }" if using Autoscale instead of Provisioned Throughput. Fill the required Autoscale max throughput setting. Changing between Autoscale and Provisioned throughput is only supported in the Azure Portal.
  offerThroughput: (int) // Provisioned Throughput enabled with required throughput amount set.
  indexes: [{key: {_id: 1}, name: "_id_1"}, ... ] // Optional indexes (3.6+ accounts only).
}

En la siguiente tabla se describen los parámetros del comando:

Output

Devuelve una respuesta predeterminada del comando personalizado. Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Actualización del rendimiento aprovisionado asociado con una colección

Para actualizar el rendimiento aprovisionado de una colección con nombre "testCollection" a 1200 RU/s, use el siguiente comando:

use test
db.runCommand({customAction: "UpdateCollection", collection: "testCollection", offerThroughput: 1200 });

Obtener una colección

El comando personalizado de obtención de una colección devuelve el objeto de colección.

{
  customAction: "GetCollection",
  collection: "<Name of the collection>"
}

En la siguiente tabla se describen los parámetros del comando:

Output

Si el comando se ejecuta correctamente, la respuesta contiene un documento con los siguientes campos:

Si no se puede ejecutar el comando, se devuelve una respuesta de comando personalizado de forma predeterminada. Consulte la salida predeterminada del comando personalizado para los parámetros en la salida.

Ejemplos

Obtención de la colección

Para obtener el objeto de colección para una colección denominada "testCollection", use el comando siguiente:

use test
db.runCommand({customAction: "GetCollection", collection: "testCollection"});

Si la colección tiene una capacidad de rendimiento asociada, incluirá el valor de provisionedThroughput y el resultado sería:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 400,
        "ok" : 1
}

Si la colección tiene un rendimiento de escalabilidad automática asociado, incluirá el objeto autoScaleSettings con el parámetro maxThroughput, que define el rendimiento máximo al que se aumentará la colección de forma dinámica. Además, incluirá el valor de provisionedThroughput, que define el rendimiento mínimo que al que se reducirá la colección de forma dinámica si no hay solicitudes en la colección:

{
        "database" : "test",
        "collection" : "testCollection",
        "provisionedThroughput" : 1000,
        "autoScaleSettings" : {
            "maxThroughput" : 10000
        },
        "ok" : 1
}

Si la colección está compartiendo rendimiento en el nivel de base de datos, ya sea en el modo de escalabilidad automática o manual, el resultado sería:

{ "database" : "test", "collection" : "testCollection", "ok" : 1 }

{
        "database" : "test",
        "provisionedThroughput" : 2000,
        "autoScaleSettings" : {
            "maxThroughput" : 20000
        },
        "ok" : 1
}

Paralelización de flujos de cambios

Cuando se usan flujos de cambios a escala, es mejor propagar uniformemente la carga. El comando siguiente devolverá uno o varios tokens de reanudación de flujo de cambios, cada uno correspondiente a los datos de una sola extensión o partición física (pueden existir varias extensiones o particiones lógicas en una partición física). Cada token de reanudación hará que watch() solo devuelva datos de esa extensión o partición física.

Al llamar a db.collection.watch() en cada token de reanudación (un subproceso por token), se escalarán los flujos de cambios de forma eficaz.

{
        customAction: "GetChangeStreamTokens", 
        collection: "<Name of the collection>", 
        startAtOperationTime: "<BSON Timestamp>" // Optional. Defaults to the time the command is run.
} 

Ejemplo

Ejecute el comando personalizado para obtener un token de reanudación para cada extensión o partición física.

use test
db.runCommand({customAction: "GetChangeStreamTokens", collection: "<Name of the collection>"})

Ejecute un subproceso o proceso watch() para cada token de reanudación devuelto desde el comando personalizado GetChangeStreamTokens. Debajo se muestra un ejemplo para un subproceso.

db.test_coll.watch([{ $match: { "operationType": { $in: ["insert", "update", "replace"] } } }, { $project: { "_id": 1, "fullDocument": 1, "ns": 1, "documentKey": 1 } }], 
{fullDocument: "updateLookup", 
resumeAfter: { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDb250aW51YXRpb24iOlt7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbndkFLbiIsInZhbHVlIjoiXCIxODQ0XCIifX1dfQ=="), "_kind" : NumberInt(1)}})

El documento (valor) del campo resumeAfter representa el token de reanudación. watch() devolverá un cursor para todos los documentos que se han insertado, actualizado o reemplazado de esa partición física desde la ejecución del comando personalizado GetChangeStreamTokens. Debajo se muestra un ejemplo de los datos devueltos.

{ "_id" : { "_data" : BinData(0,"eyJWIjoyLCJSaWQiOiJQeFVhQUxuMFNLRT0iLCJDfdsfdsfdsft7IkZlZWRSYW5nZSI6eyJ0eXBlIjoiRWZmZWN0aXZlIFBhcnRpdGlvbiBLZXkgUmFuZ2UiLCJ2YWx1ZSI6eyJtaW4iOiIiLCJtYXgiOiJGRiJ9fSwiU3RhdGUiOnsidHlwZSI6ImNvbnRpbnVhdGlvbiIsInZhbHVlIjoiXCIxOTgwXCIifX1dfQ=="), "_kind" : 1 },
 "fullDocument" : { "_id" : ObjectId("60da41ec9d1065b9f3b238fc"), "name" : John, "age" : 6 }, "ns" : { "db" : "test-db", "coll" : "test_coll" }, "documentKey" : { "_id" : ObjectId("60da41ec9d1065b9f3b238fc") }}

Tenga en cuenta que cada documento devuelto incluye un token de reanudación (todos son iguales para cada página). Este token de reanudación se debe almacenar y reutilizar si el subproceso o proceso termina. Este token de reanudación continuará desde donde lo dejó y recibirá datos solo de esa partición física.

Salida predeterminada de un comando personalizado

Si no se especifica, la respuesta personalizada contiene un documento con los siguientes campos:

Por ejemplo:

{ "ok" : 1 }

Pasos siguientes

Luego, puede obtener información sobre los siguientes conceptos de Azure Cosmos DB:

• Indexación en Azure Cosmos DB
• Expiración automática de los datos de Azure Cosmos DB con período de vida