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

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-serverversion 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
• Uppdatera databas
• Hämta databas
• Skapa samling
• Uppdatera samling
• Hämta samling

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	Type	Beskrivning
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 begäranden som samlingen kan öka till dynamiskt.

Output

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för anpassat kommando 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 autoskalningsdataflöde

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	Type	Beskrivning
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 begäranden 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.

Output

Om kommandot lyckas returneras följande svar:

{ "ok" : 1 }

Se standardutdata för anpassat kommando 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 autoskalningsdataflödet 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 för att 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	Type	Beskrivning
customAction	string	Namnet på det anpassade kommandot. Värdet måste vara GetDatabase.

Output

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

Fält	Type	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 begäranden som databasen kan ökas till dynamiskt.

Om kommandot misslyckas returneras ett standardsvar för anpassade kommandon. Se standardutdata för anpassat kommando 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 manuellt dataflöde på databasnivå associerat med den, visar provisionedThroughput utdata värdena:

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

Om databasen har ett autoskalningsdataflöde på databasnivå associerat med den, visar provisionedThroughpututdata , 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	Obligatoriskt	Beskrivning
customAction	string	Obligatoriskt	Namnet på det anpassade kommandot. Värdet måste vara CreateCollection.
collection	string	Obligatoriskt	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 den som standard minst 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 Shard-nyckeln för den fragmenterade samlingen. Den här parametern krävs om du anger fler ä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.	I nuläget krävs ett index på _id. 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}.

Output

Returnerar ett standardsvar för anpassade kommandon. Se standardutdata för anpassat kommando 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. Till 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 autoskalningsdataflöde inställt 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 fragmenterad autoskalningssamling

Om du vill skapa en fragmenterad 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 }});

Uppdatera samling

Kommandot för uppdateringssamlingstillägget uppdaterar egenskaperna som är associerade med den angivna samlingen. Det går bara att ändra samlingen 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	Type	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 för 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 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. I nuläget ersätter den angivna uppsättningen index (inklusive avsläppningsindex) 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}.

Output

Returnerar ett standardsvar för anpassade kommandon. Se standardutdata för anpassat kommando 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	Type	Beskrivning
customAction	string	Namnet på det anpassade kommandot. Värdet måste vara GetCollection.
collection	string	Namnet på samlingen.

Output

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

Fält	Type	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 för 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 begäranden som samlingen kan ökas till dynamiskt.

Om kommandot misslyckas returneras ett standardsvar för anpassade kommandon. Se standardutdata för anpassat kommando 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 autoskalningsdataflöde 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öm – var och en motsvarar data från en enda fysisk shard/partition (flera logiska shards/partitioner kan finnas på en fysisk partition). Varje återställningstoken gör att watch() endast returnerar data från den fysiska fragmentet/partitionen.

Använd db.collection.watch() på varje meritförteckningstoken (en tråd per token) för att skala ä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 meritförteckningstoken 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 återställningstoken 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 återställningstoken. 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 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	Type	Beskrivning
ok	int	Status för svar. 1 == lyckades. 0 == fel.
code	int	Returnerades endast när kommandot misslyckades (d.v.s. ok == 0). Innehåller MongoDB-felkoden. Det här fältet är en valfri svarsparameter.
errMsg	string	Returnerades endast när kommandot misslyckades (d.v.s. ok == 0). Innehåller ett användarvänligt felmeddelande. Det här fältet är en valfri svarsparameter.

Till exempel:

{ "ok" : 1 }

Nästa steg

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

• Indexering i Azure Cosmos DB
• Ta bort data från Azure Cosmos DB automatiskt med hjälp av förfallodatum