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

  • Artigo

APLICA-SE A: 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

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:

Campo Type Descrição
customAction string Nome do comando personalizado. O valor deve ser CreateDatabase.
offerThroughput int Taxa de transferência provisionada definida no banco de dados. Esse parâmetro é opcional.
autoScaleSettings Object Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade de dimensionamento automático. Você pode configurar o valor maxThroughput, que descreve o maior número de Unidades de Solicitação para a qual a coleção pode aumentar dinamicamente.

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:

Campo Type Descrição
customAction string Nome do comando personalizado. O valor deve ser UpdateDatabase.
offerThroughput int Nova taxa de transferência provisionada que você deseja definir no banco de dados se o esse usar a taxa de transferência no nível do banco de dados
autoScaleSettings Object Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade de dimensionamento automático. Você pode configurar o valor maxThroughput, que descreve o maior número de Unidades de Solicitação para a qual o banco de dados pode ser aumentado dinamicamente.

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:

Campo Type Descrição
customAction string Nome do comando personalizado. O valor deve ser GetDatabase.

Saída

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

Campo Type Descrição
ok int Status da resposta. 1 == êxito. 0 == falha.
database string Nome do banco de dados.
provisionedThroughput int A taxa de transferência provisionada que é definida no banco de dados se esse estiver usando a taxa de transferência manual no nível do banco de dados
autoScaleSettings Object Esse objeto contém os parâmetros de capacidade associados ao banco de dados, se ele estiver usando o modo de dimensionamento automático. O valor maxThroughput descreve o número mais alto de Unidades de Solicitação para a qual o banco de dados pode ser aumentado dinamicamente.

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:

Campo Type Obrigatório Descrição
customAction string Obrigatório Nome do comando personalizado. O valor deve ser CreateCollection.
collection string Obrigatório Nome da coleção. Caracteres especiais não são permitidos.
offerThroughput int Opcional A taxa de transferência provisionada a ser definida no banco de dados. Se esse parâmetro não for fornecido, o padrão será o mínimo: 400 RU/s. * Para especificar a taxa de transferência além de 10.000 RU/s, o parâmetro shardKey é obrigatório.
shardKey string Necessário para coleções com alta taxa de transferência O caminho para a Chave de fragmento da coleção fragmentada. Esse parâmetro será necessário se você definir mais de 10.000 RU/s em offerThroughput. Se for especificado, todos os documentos inseridos requerem essa chave e valor.
autoScaleSettings Object Necessário para o modo de dimensionamento automático Este objeto contém as configurações associadas ao modo de capacidade de dimensionamento automático. Você pode configurar o valor maxThroughput, que descreve o maior número de Unidades de Solicitação para a qual a coleção pode ser aumentada dinamicamente.
indexes Array Se desejar, configure índices. Esse parâmetro tem suporte apenas nas contas a partir da versão 3.6. É necessário um índice em _id, caso esteja presente. Cada entrada na matriz deve incluir uma chave de um ou mais campos, um nome, e pode conter opções de índice. Por exemplo, para criar um índice exclusivo composto nos campos a e b, use esta entrada: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

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:

Campo Type Descrição
customAction string Nome do comando personalizado. O valor deve ser UpdateCollection.
collection string Nome da coleção.
offerThroughput int A taxa de transferência provisionada a ser definida na coleção.
autoScaleSettings Object Necessário para o modo de dimensionamento automático. Este objeto contém as configurações associadas ao modo de capacidade de dimensionamento automático. O valor maxThroughput descreve o número mais alto de Unidades de Solicitação para a qual a coleção pode ser aumentada dinamicamente.
indexes Array Se desejar, configure índices. Esse parâmetro tem suporte apenas nas contas a partir da versão 3.6. Quando presente, o conjunto de índices especificado (incluindo a remoção de índices) substitui os índices existentes da coleção. Um índice em _id é necessário. Cada entrada na matriz deve incluir uma chave de um ou mais campos, um nome, e pode conter opções de índice. Por exemplo, para criar um índice exclusivo nos campos a e b, use esta entrada: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

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:

Campo Type Descrição
customAction string Nome do comando personalizado. O valor deve ser GetCollection.
collection string Nome da coleção.

Saída

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

Campo Type Descrição
ok int Status da resposta. 1 == êxito. 0 == falha.
database string Nome do banco de dados.
collection string Nome da coleção.
shardKeyDefinition document Documento de especificação de índice usado como chave de fragmentação. Esse campo é um parâmetro de resposta opcional.
provisionedThroughput int A taxa de transferência provisionada a ser definida na coleção. Esse campo é um parâmetro de resposta opcional.
autoScaleSettings Object Esse objeto contém os parâmetros de capacidade associados ao banco de dados, se ele estiver usando o modo de dimensionamento automático. O valor maxThroughput descreve o número mais alto de Unidades de Solicitação para a qual a coleção pode ser aumentada dinamicamente.

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:

Campo Type Descrição
ok int Status da resposta. 1 == êxito. 0 == falha.
code int Retornado somente quando o comando falhou (ou seja, ok == 0). Contém o código de erro do MongoDB. Esse campo é um parâmetro de resposta opcional.
errMsg string Retornado somente quando o comando falhou (ou seja, ok == 0). Contém uma mensagem de erro amigável. Esse campo é um parâmetro de resposta opcional.

Por exemplo:

{ "ok" : 1 }

Próximas etapas

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