Använda MongoDB-tilläggskommandon för att hantera data som lagras i Azure Cosmos DB för MongoDB

  • Artikel

GÄLLER FÖR: Mongodb

Följande dokument innehåller de anpassade åtgärdskommandon som är specifika för Azure Cosmos DB för MongoDB. Dessa kommandon kan användas för att skapa och hämta databasresurser som är specifika för Azure Cosmos DB-kapacitetsmodellen.

Genom att använda Azure Cosmos DB för MongoDB kan du dra nytta av de delade fördelarna med Azure Cosmos DB. Dessa fördelar omfattar, men är inte begränsade till:

  • Global distribution
  • Automatisk horisontell partitionering
  • Hög tillgänglighet
  • Svarstidsgarantier
  • Kryptering i vila
  • Säkerhetskopior

Du kan dra nytta av dessa fördelar samtidigt som du bevarar dina investeringar i ditt befintliga MongoDB-program. Du kan kommunicera med Azure Cosmos DB för MongoDB med någon av MongoDB-klientdrivrutinerna med öppen källkod. Med Azure Cosmos DB for MongoDB kan du använda befintliga klientdrivrutiner genom att följa MongoDB-trådprotokollet.

Stöd för MongoDB-protokoll

Azure Cosmos DB for MongoDB är kompatibelt med MongoDB server version 4.0, 3.6 och 3.2. Mer information finns i funktioner och syntax som stöds i versionerna 4.0, 3.6 och 3.2.

Följande tilläggskommandon skapar och ändrar Azure Cosmos DB-specifika resurser via databasbegäranden:

Skapa databas

Kommandot create database extension skapar en ny MongoDB-databas. Databasnamnet kan användas från databaskontexten use database som anges av kommandot . I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Description
customAction string Namnet på det anpassade kommandot. Värdet måste vara CreateDatabase.
offerThroughput int Etablerat dataflöde som du har angett i databasen. Den här parametern är valfri.
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller de inställningar som är associerade med kapacitetsläget Autoskalning. Du kan konfigurera värdet maxThroughput , som beskriver det högsta antalet enheter för programbegäran som samlingen kan öka till dynamiskt.

Utdata

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Skapa en databas

Om du vill skapa en databas med namnet "test" som använder alla standardvärden använder du följande kommando:

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

Det här kommandot skapar en databas utan dataflöde på databasnivå. Den här åtgärden innebär att samlingarna i den här databasen måste ange hur mycket dataflöde du behöver använda.

Exempel: Skapa en databas med dataflöde

Om du vill skapa en databas med namnet "test" och ange ett etablerat dataflöde på databasnivå på 1 000 RU:er använder du följande kommando:

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

Det här kommandot skapar en databas och anger ett dataflöde till den. Alla samlingar i den här databasen delar det angivna dataflödet, såvida inte samlingarna skapas med en specifik dataflödesnivå.

Exempel: Skapa en databas med dataflöde för autoskalning

Om du vill skapa en databas med namnet "test" och ange ett maximalt dataflöde för autoskalning på 20 000 RU/s på databasnivå använder du följande kommando:

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

Uppdatera databas

Kommandot uppdatera databastillägget uppdaterar de egenskaper som är associerade med den angivna databasen. Det går bara att ändra databasen från etablerat dataflöde till autoskalning och vice versa i Azure Portal. I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Description
customAction string Namnet på det anpassade kommandot. Värdet måste vara UpdateDatabase.
offerThroughput int Nytt etablerat dataflöde som du vill ange i databasen om databasen använder dataflöde på databasnivå
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller de inställningar som är associerade med kapacitetsläget Autoskalning. Du kan konfigurera värdet maxThroughput , som beskriver det högsta antalet enheter för programbegäran som databasen kan ökas till dynamiskt.

Det här kommandot använder databasen som anges i kontexten för sessionen. Den här databasen är samma som du använde i use <database> kommandot . För närvarande går det inte att ändra databasnamnet med det här kommandot.

Utdata

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Uppdatera det etablerade dataflödet som är associerat med en databas

Om du vill uppdatera det etablerade dataflödet för en databas med namnet "test" till 1 200 RU:er använder du följande kommando:

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

Exempel: Uppdatera det dataflöde för automatisk skalning som är associerat med en databas

Om du vill uppdatera det etablerade dataflödet för en databas med namnet "test" till 20 000 RU:er eller omvandla den till en dataflödesnivå för autoskalning använder du följande kommando:

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

Hämta databas

Kommandot hämta databastillägg returnerar databasobjektet. Databasnamnet används från databaskontexten som kommandot körs mot.

{
  customAction: "GetDatabase"
}

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Description
customAction string Namnet på det anpassade kommandot. Värdet måste vara GetDatabase.

Utdata

Om kommandot lyckas innehåller svaret ett dokument med följande fält:

Fält Typ Beskrivning
ok int Status för svar. 1 == lyckades. 0 == fel.
database string Namnet på databasen.
provisionedThroughput int Etablerat dataflöde som anges i databasen om databasen använder manuellt dataflöde på databasnivå
autoScaleSettings Object Det här objektet innehåller de kapacitetsparametrar som är associerade med databasen om det använder autoskalningsläget. Värdet maxThroughput beskriver det högsta antalet enheter för programbegäran som databasen kan ökas till dynamiskt.

Om kommandot misslyckas returneras ett standardsvar för anpassade kommandon. Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Hämta databasen

Om du vill hämta databasobjektet för en databas med namnet "test"använder du följande kommando:

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

Om databasen inte har något associerat dataflöde skulle utdata vara:

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

Om databasen har ett associerat manuellt dataflöde på databasnivå visar utdata värdena provisionedThroughput :

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

Om databasen har ett associerat autoskalningsdataflöde på databasnivå skulle utdata visa provisionedThroughput, som beskriver den minsta RU/s för databasen och autoScaleSettings objektet inklusive maxThroughput, som beskriver det maximala ANTALET RU/s för databasen.

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

Skapa samling

Kommandot skapa samlingstillägg skapar en ny MongoDB-samling. Databasnamnet används från databaskontexten use database som anges av kommandot . Formatet för kommandot CreateCollection är följande:

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Obligatorisk Beskrivning
customAction string Krävs Namnet på det anpassade kommandot. Värdet måste vara CreateCollection.
collection string Obligatorisk Namnet på samlingen. Inga specialtecken eller blanksteg tillåts.
offerThroughput int Valfritt Etablerat dataflöde som ska anges i databasen. Om den här parametern inte anges är standardvärdet 400 RU/s. * Om du vill ange dataflöde över 10 000 RU/s krävs parametern shardKey .
shardKey string Krävs för samlingar med stort dataflöde Sökvägen till shardnyckeln för den fragmenterade samlingen. Den här parametern krävs om du anger mer än 10 000 RU/s i offerThroughput. Om den har angetts kräver alla dokument som infogas den här nyckeln och värdet.
autoScaleSettings Object Krävs för autoskalningsläge Det här objektet innehåller de inställningar som är associerade med kapacitetsläget Autoskalning. Du kan konfigurera värdet maxThroughput , som beskriver det högsta antalet enheter för begäranden som samlingen kan ökas till dynamiskt.
indexes Array Du kan också konfigurera index. Den här parametern stöds endast för 3,6+-konton. När det finns ett index på _id krävs. Varje post i matrisen måste innehålla en nyckel för ett eller flera fält, ett namn och kan innehålla indexalternativ. Om du till exempel vill skapa ett sammansatt unikt index för fälten a och b använda den här posten: {key: {a: 1, b: 1}, name:"a_1_b_1", unique: true}.

Utdata

Returnerar ett standardsvar för anpassade kommandon. Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Skapa en samling med minsta möjliga konfiguration

Om du vill skapa en ny samling med namn "testCollection" och standardvärden använder du följande kommando:

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

Den här åtgärden resulterar i en ny fast, ohardad samling med 400RU/s och ett index i fältet _id som skapas automatiskt. Den här typen av konfiguration gäller även när du skapar nya samlingar via insert() funktionen. Exempel:

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

Exempel: Skapa en ohardad samling

Om du vill skapa en ohardad samling med namn "testCollection" och etablerat dataflöde på 1 000 RU:er använder du följande kommando:

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

Du kan skapa en samling med upp till 10 000 RU/s som offerThroughput utan att behöva ange en shardnyckel. För samlingar med större dataflöde kan du titta i nästa avsnitt.

Exempel: Skapa en fragmenterad samling

Om du vill skapa en fragmenterad samling med namn "testCollection" och etablerat dataflöde på 11 000 RU:er och en shardkey egenskap "a.b" använder du följande kommando:

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

Det här kommandot kräver nu parametern shardKey eftersom mer än 10 000 RU/s anges i offerThroughput.

Exempel: Skapa en ohardad autoskalningssamling

Om du vill skapa en ohardad samling med namnet 'testCollection' som använder kapacitet för autoskalning av dataflöde inställd på 4 000 RU/s använder du följande kommando:

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

För värdet autoScaleSettings.maxThroughput kan du ange ett intervall från 4 000 RU/s till 10 000 RU/s utan en shardnyckel. För högre dataflöde för autoskalning måste du ange parametern shardKey .

Exempel: Skapa en shardad autoskalningssamling

Om du vill skapa en shardad samling med namnet 'testCollection' med en shardnyckel med namnet 'a.b', och som använder kapacitet för autoskalning av dataflöde inställt på 20 000 RU/s, använder du följande kommando:

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

Uppdateringssamling

Kommandot för uppdateringssamlingstillägget uppdaterar de egenskaper som är associerade med den angivna samlingen. Det går bara att ändra din samling från etablerat dataflöde till autoskalning och vice versa i Azure Portal.

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Värdet måste vara UpdateCollection.
collection string Namnet på samlingen.
offerThroughput int Etablerat dataflöde som ska anges i samlingen.
autoScaleSettings Object Krävs för autoskalningsläge. Det här objektet innehåller de inställningar som är associerade med kapacitetsläget Autoskalning. Värdet maxThroughput beskriver det högsta antalet enheter för programbegäran som samlingen kan ökas till dynamiskt.
indexes Array Du kan också konfigurera index. Den här parametern stöds endast för 3,6+-konton. I förekommande fall ersätter den angivna uppsättningen index (inklusive släppa index) de befintliga indexen i samlingen. Ett index på _id krävs. Varje post i matrisen måste innehålla en nyckel för ett eller flera fält, ett namn och kan innehålla indexalternativ. Om du till exempel vill skapa ett sammansatt unikt index för fälten a och b använder du den här posten: {key: {a: 1, b: 1}, name: "a_1_b_1", unique: true}.

Utdata

Returnerar ett standardsvar för anpassade kommandon. Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Uppdatera det etablerade dataflödet som är associerat med en samling

Om du vill uppdatera det etablerade dataflödet för en samling med namnet "testCollection" till 1 200 RU:er använder du följande kommando:

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

Hämta samling

Det anpassade kommandot hämta samling returnerar samlingsobjektet.

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

I följande tabell beskrivs parametrarna i kommandot:

Fält Typ Beskrivning
customAction string Namnet på det anpassade kommandot. Värdet måste vara GetCollection.
collection string Namnet på samlingen.

Utdata

Om kommandot lyckas innehåller svaret ett dokument med följande fält

Fält Typ Beskrivning
ok int Status för svar. 1 == lyckades. 0 == fel.
database string Namnet på databasen.
collection string Namnet på samlingen.
shardKeyDefinition document Indexspecifikationsdokument som används som en shardnyckel. Det här fältet är en valfri svarsparameter.
provisionedThroughput int Etablerat dataflöde som ska anges i samlingen. Det här fältet är en valfri svarsparameter.
autoScaleSettings Object Det här objektet innehåller de kapacitetsparametrar som är associerade med databasen om det använder autoskalningsläget. Värdet maxThroughput beskriver det högsta antalet enheter för programbegäran som samlingen kan ökas till dynamiskt.

Om kommandot misslyckas returneras ett standardsvar för anpassade kommandon. Se standardutdata för det anpassade kommandot för parametrarna i utdata.

Exempel: Hämta samlingen

Om du vill hämta samlingsobjektet för en samling med namnet "testCollection"använder du följande kommando:

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

Om samlingen har en associerad dataflödeskapacitet innehåller den provisionedThroughput värdet och utdata blir:

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

Om samlingen har ett associerat dataflöde för autoskalning innehåller den autoScaleSettings objektet med parametern maxThroughput , som definierar det maximala dataflöde som samlingen ökar till dynamiskt. Dessutom innehåller provisionedThroughput det även värdet, som definierar det minsta dataflöde som den här samlingen minskar till om det inte finns några begäranden i samlingen:

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

Om samlingen delar dataflöde på databasnivå, antingen i autoskalningsläge eller manuellt, skulle utdata vara:

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

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

Parallellisera ändringsströmmar

När du använder ändringsströmmar i stor skala är det bäst att fördela belastningen jämnt. Följande kommando returnerar en eller flera återställningstoken för ändringsströmmen – var och en motsvarar data från en enda fysisk shard/partition (flera logiska shards/partitioner kan finnas på en fysisk partition). Varje cv-token gör att watch() endast returnerar data från den fysiska sharden/partitionen.

Använd db.collection.watch() på varje cv-token (en tråd per token) för att skala om ändringsströmmar effektivt.

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

Exempel: Hämta strömtoken

Kör det anpassade kommandot för att hämta en cv-token för varje fysisk shard/partition.

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

Kör en watch() tråd/process för varje cv-token som returneras från det anpassade kommandot GetChangeStreamTokens. Här är ett exempel på en tråd.

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

Dokumentet (värdet) i fältet resumeAfter representerar meritförteckningstoken. Kommandot watch() returnerar en förbannelse för alla dokument som har infogats, uppdaterats eller ersatts från den fysiska partitionen sedan det anpassade kommandot GetChangeStreamTokens kördes. Ett exempel på de data som returneras ingår här.

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

Varje dokument som returneras innehåller en meritförteckningstoken (de är alla likadana för varje sida). Denna meritförteckningstoken ska lagras och återanvändas om tråden/processen dör. Den här meritförteckningstoken tar vid där du slutade och tar endast emot data från den fysiska partitionen.

Standardutdata för ett anpassat kommando

Om inget anges innehåller ett anpassat svar ett dokument med följande fält:

Fält Typ Description
ok int Status för svar. 1 == lyckades. 0 == fel.
code int Returnerades endast när kommandot misslyckades (det vill sa ok == 0). Innehåller MongoDB-felkoden. Det här fältet är en valfri svarsparameter.
errMsg string Returnerades endast när kommandot misslyckades (det vill sa ok == 0). Innehåller ett användarvänligt felmeddelande. Det här fältet är en valfri svarsparameter.

Exempel:

{ "ok" : 1 }

Nästa steg

Härnäst kan du gå vidare och lära dig följande Azure Cosmos DB-begrepp: