Usar comandos de extensão do MongoDB para gerenciar dados armazenados no Azure Cosmos DB for MongoDB

APLICA-SE AO: MongoDB

O documento a seguir contém os comandos de ação personalizados específicos do Azure Cosmos DB for MongoDB. Esses comandos podem ser usados para criar e obter recursos de banco de dados específicos para o modelo de capacidade do Azure Cosmos DB.

Usando o Azure Cosmos DB for MongoDB, você pode aproveitar os benefícios compartilhados do Azure Cosmos DB. Esses benefícios incluem, mas não estão limitados a:

• Distribuição global
• Fragmentação automática
• Alta disponibilidade
• Garantias de latência
• Criptografia em repouso
• Backups

Você pode aproveitar esses benefícios preservando seus investimentos em seus aplicativos existentes do MongoDB. Você pode usar qualquer um dos drivers para cliente do MongoDB open-source para se comunicar com o Azure Cosmos DB for MongoDB. O Azure Cosmos DB for MongoDB permite o uso de drivers cliente existentes por adotar ao protocolo de transmissão do MongoDB.

Suporte ao Protocolo do MongoDB

O Azure Cosmos DB for MongoDB é compatível com o servidor MongoDB versão 4.0, 3.6 e 3.2. Para obter mais informações, confira os recursos e sintaxe com suporte nas versões 4.0, 3.6 e 3.2.

Os comandos de extensão a seguir criam e modificam recursos específicos do Azure Cosmos DB por meio de solicitações do banco de dados:

• Criar banco de dados
• Atualizar banco de dados
• Obter banco de dados
• Criar coleção
• Atualizar coleção
• Obter coleção

Criar banco de dados

O comando da extensão Criar banco de dados cria um novo banco de dados MongoDB. O nome do banco de dados pode ser usado no contexto do banco de dados definido pelo comando use database. A tabela a seguir descreve os parâmetros no comando:

Saída

Se o comando for bem-sucedido, retornará a seguinte resposta:

{ "ok" : 1 }

Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: criar um banco de dados

Para criar um banco de dados chamado "test" que usa todos os valores padrão, use o seguinte comando:

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

Esse comando cria um banco de dados sem taxa de transferência no nível do banco de dados. Essa operação significa que as coleções nesse banco de dados precisam especificar a quantidade de taxa de transferência necessária.

Exemplo: criar um banco de dados com taxa de transferência

Para criar um banco de dados chamado "test" e especificar uma taxa de transferência provisionada no nível do banco de dados de 1.000 RU/s, use o seguinte comando:

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

Esse comando cria um banco de dados e define uma taxa de transferência para ele. Todas as coleções nesse banco de dados compartilha a taxa de transferência definida, a menos que as coleções sejam criadas com um nível de taxa de transferência específico.

Exemplo: criar um banco de dados com taxa de transferência de dimensionamento automático

Para criar um banco de dados chamado "test" e especificar uma taxa de transferência máxima de 20.000 RU/s em nível do banco de dados para dimensionamento automático, use o seguinte comando:

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

Atualizar banco de dados

O comando da extensão Atualizar do banco de dados atualiza as propriedades associadas ao banco de dados especificado. A alteração do banco de dados de uma taxa de transferência provisionada para de dimensionamento automático, e vice-versa, só tem suporte no portal do Azure. A tabela a seguir descreve os parâmetros no comando:

Esse comando usa o banco de dados especificado no contexto da sessão. Esse é o mesmo banco de dados que você usou no comando use <database>. No momento, o nome do banco de dados não pode ser alterado usando esse comando.

Saída

Se o comando for bem-sucedido, retornará a seguinte resposta:

{ "ok" : 1 }

Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplos: atualizar a taxa de transferência provisionada associada a um banco de dados

Para atualizar a taxa de transferência provisionada de um banco de dados chamado "test" para 1.200 RU/s, use o seguinte comando:

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

Exemplo: atualizar a taxa de transferência de dimensionamento automático associada a um banco de dados

Para atualizar a taxa de transferência provisionada de um banco de dados chamado "test" para 20.000 RU/s, ou para transformá-lo em um nível de taxa de transferência de dimensionamento automático, use o seguinte comando:

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

Obter banco de dados

O comando da extensão Obter do banco de dados retorna o objeto de banco de dados. O nome do banco de dados é usado no contexto do banco de dados no qual o comando é executado.

{
  customAction: "GetDatabase"
}

A tabela a seguir descreve os parâmetros no comando:

Saída

Se o comando for executado com sucesso, a resposta conterá um documento com os seguintes campos:

Se o comando falhar, uma resposta padrão de comando personalizado será retornada. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: obter o banco de dados

Para obter o objeto de banco de dados para um chamado "test", use o seguinte comando:

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

Se o banco de dados não tiver nenhuma taxa de transferência associada, a saída será:

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

Se o banco de dados tiver uma taxa de transferência manual no nível do banco de dados associada a ele, a saída mostraria os valores provisionedThroughput:

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

Se o banco de dados tiver uma taxa de transferência de dimensionamento automático no nível do banco de dados associada a ele, a saída mostrará provisionedThroughput, que descreve os RU/s mínimos e o objeto autoScaleSettings, incluindo maxThroughput, que descreve o máximo de RU/s para o banco de dados.

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

Criar coleção

O comando da extensão Criar coleção cria uma nova coleção do MongoDB. O nome do banco de dados é usado no contexto dos bancos de dados definido pelo comando use database. Este é o formato do comando CreateCollection:

{
  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).
}

A tabela a seguir descreve os parâmetros no comando:

Saída

Retorna uma resposta de comando personalizado padrão. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: criar uma coleção com a configuração mínima

Para criar uma nova coleção chamada "testCollection" e os valores padrão, use o seguinte comando:

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

Essa operação resulta em uma nova coleção fixa, não fragmentada, com 400 RU/s e um índice no campo _id criado automaticamente. Esse tipo de configuração também se aplica ao criar novas coleções por meio da função insert(). Por exemplo:

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

Exemplo: criar uma coleção não fragmentada

Para criar uma coleção não fragmentada chamada "testCollection" e taxa de transferência provisionada de 1000 RU/s, use o seguinte comando:

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

Você pode criar uma coleção com até 10.000 RU/s como offerThroughput sem precisar especificar uma chave de fragmentação. Para coleções com maior taxa de transferência, confira a próxima seção.

Exemplo: criar uma coleção fragmentada

Para criar uma coleção fragmentada chamada "testCollection", taxa de transferência provisionada de 11.000 RU/s e uma propriedade "a.b" shardkey, use o seguinte comando:

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

Este comando agora requer o parâmetro shardKey, pois mais de 10.000 RU/s especificados em offerThroughput.

Exemplo: criar uma coleção de dimensionamento automático não fragmentada

Para criar uma coleção não fragmentada chamada 'testCollection' que usa a capacidade de taxa de transferência de dimensionamento automático definida como 4.000 RU/s, use o seguinte comando:

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

Para o valor autoScaleSettings.maxThroughput, você pode especificar um intervalo de 4.000 RU/s a 10.000 RU/s sem uma chave de fragmentação. Para taxas de transferência de dimensionamento automático maiores, você precisa especificar o parâmetro shardKey.

Exemplo: criar uma coleção de dimensionamento automático fragmentada

Para criar uma coleção fragmentada chamada 'testCollection' com uma chave de fragmento chamada 'a.b' e que usa a capacidade de taxa de transferência de dimensionamento automático definida como 20.000 RU/s, use o seguinte comando:

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

Atualizar coleção

O comando da extensão Atualizar coleção atualiza as propriedades associadas à coleção especificada. A alteração da coleção de uma taxa de transferência provisionada para de dimensionamento automático, e vice-versa, só tem suporte no portal do Azure.

{
  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).
}

A tabela a seguir descreve os parâmetros no comando:

Saída

Retorna uma resposta de comando personalizado padrão. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: atualizar a taxa de transferência provisionada associada a uma coleção

Para atualizar a taxa de transferência provisionada de uma coleção chamada "testCollection" para 1200 RU/s, use o seguinte comando:

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

Obter coleção

O comando personalizado Obter coleção retorna o objeto da coleção.

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

A tabela a seguir descreve os parâmetros no comando:

Saída

Se o comando for executado com sucesso, a resposta conterá um documento com os seguintes campos

Se o comando falhar, uma resposta padrão de comando personalizado será retornada. Consulte a saída padrão do comando personalizado para os parâmetros na saída.

Exemplo: obter a coleção

Para obter o objeto de coleção para uma coleção chamada "testCollection", use o seguinte comando:

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

Se a coleção tiver uma capacidade de taxa de transferência associada a ela, incluirá o valor provisionedThroughput e a saída será:

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

Se a coleção tiver uma taxa de transferência de dimensionamento automático associada, ela inclui o objeto autoScaleSettings com o parâmetro maxThroughput, que define a taxa de transferência máxima para qual a coleção aumenta dinamicamente. Além disso, ela também inclui o valor provisionedThroughput, que define a taxa de transferência mínima que essa coleção reduz se não houver nenhuma solicitação na coleção:

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

Se a coleção estiver compartilhando a taxa de transferência no nível do banco de dados, seja no modo de dimensionamento automático ou manual, a saída será:

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

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

Paralelizando fluxos de alteração

Ao usar fluxos de alteração em escala, é melhor difundir a carga uniformemente. O comando a seguir retorna um ou mais tokens de retomada de fluxo de alterações. Cada um corresponde aos dados de um único fragmento físico/partição (vários fragmentos lógicos/partições podem existir em uma partição física). Cada token de retomada faz com que watch() retorne apenas dados desse fragmento/partição física.

Use db.collection.watch() em cada token de retomada (um thread por token) para escalar fluxos de alteração com eficiência.

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

Exemplo: obter o token de fluxo

Execute o comando personalizado para obter um token de retomada para cada fragmento/partição física.

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

Execute um thread/processo watch() para cada token de retomada retornado do comando personalizado GetChangeStreamTokens. Aqui está um exemplo para um thread.

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)}})

O documento (valor) no campo resumeAfter representa o token de retomada. O comando watch() retorna um cursor para todos os documentos que foram inseridos, atualizados ou substituídos dessa partição física desde que o comando personalizado GetChangeStreamTokens tenha sido executado. Um exemplo dos dados retornados está incluído aqui.

{
  "_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")
  }
}

Cada documento retornado contém um token de retomada (eles são todos iguais para cada página). Esse token de retomada deverá ser armazenado e reutilizado se o thread/processo for reutilizado. Esse token de retomada retoma de onde você saiu e recebe dados somente dessa partição física.

Saída padrão de um comando personalizado

Se não for especificada, uma resposta personalizada conterá um documento com os seguintes campos:

Por exemplo:

{ "ok" : 1 }

Próximas etapas

Em seguida, leia mais sobre os seguintes conceitos de Azure Cosmos DB:

• Indexação no Azure Cosmos DB
• Expirar os dados no Azure Cosmos DB automaticamente com a vida útil