Partiell dokumentuppdatering i Azure Cosmos DB

Artikel
06/08/2023

GÄLLER FÖR: NoSQL

Funktionen Partiell dokumentuppdatering i Azure Cosmos DB (även kallat Patch API) är ett praktiskt sätt att ändra ett dokument i en container. För närvarande, för att uppdatera ett dokument som klienten behöver läsa det, kör optimistisk samtidighetskontroll kontroller (om det behövs), uppdatera dokumentet lokalt och sedan skicka det över tråden som ett helt dokument Ersätt API-anrop.

Funktionen för partiell dokumentuppdatering förbättrar den här upplevelsen avsevärt. Klienten kan bara skicka de ändrade egenskaperna/fälten i ett dokument utan att utföra en fullständig dokumenterbytningsåtgärd. Viktiga fördelar med den här funktionen är:

Förbättrad produktivitet för utvecklare: Ger ett bekvämt API för enkel användning och möjlighet att villkorligt uppdatera dokumentet.
Prestandaförbättringar: Undviker extra CPU-cykler på klientsidan, minskar svarstiden från slutpunkt till slutpunkt och nätverksbandbredd.
Skrivningar i flera regioner: Stöder automatisk och transparent konfliktlösning med partiella uppdateringar av diskreta sökvägar i samma dokument.

Anteckning

Åtgärden Partiell dokumentuppdatering baseras på JSON Patch RFC. Egenskapsnamn i sökvägar måste undvika ~ tecknen och / som ~0 respektive ~1.

Ett exempel på ett JSON-måldokument:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 455.95,
  "inventory": {
    "quantity": 15
  },
  "used": false,
  "categoryId": "road-bikes",
  "tags": ["r-series"]
}

Ett JSON-korrigeringsdokument:

[
  { "op": "add", "path": "/color", "value": "silver" },
  { "op": "remove", "path": "/used" },
  { "op": "set", "path": "/price", "value": 355.45 }
  { "op": "incr", "path": "/inventory/quantity", "value": 10 },
  { "op": "add", "path": "/tags/-", "value": "featured-bikes" },
  { "op": "move", "from": "/color", "path": "/inventory/color" }
]

Det resulterande JSON-dokumentet:

{
  "id": "e379aea5-63f5-4623-9a9b-4cd9b33b91d5",
  "name": "R-410 Road Bicycle",
  "price": 355.45,
  "inventory": {
    "quantity": 25,
    "color": "silver"
  },
  "categoryId": "road-bikes",
  "tags": ["r-series", "featured-bikes"]
}

Åtgärder som stöds

Den här tabellen sammanfattar de åtgärder som stöds av den här funktionen.

Anteckning

målsökväg refererar till en plats i JSON-dokumentet

Åtgärdstyp	Beskrivning
Lägg till	`Add` utför något av följande beroende på målsökvägen: • Om målsökvägen anger ett element som inte finns läggs det till. • Om målsökvägen anger ett element som redan finns ersätts dess värde. • Om målsökvägen är ett giltigt matrisindex infogas ett nytt element i matrisen vid det angivna indexet. Detta flyttar befintliga element efter det nya elementet. • Om det angivna indexet är lika med matrisens längd lägger det till ett element i matrisen. I stället för att ange ett index kan du också använda `-` tecknet. Det resulterar också i att elementet läggs till i matrisen. Obs! Om du anger ett index som är större än matrislängden uppstår ett fel.
Ange	`Set` -åtgärden liknar `Add` förutom matrisdatatypen. Om målsökvägen är ett giltigt matrisindex uppdateras det befintliga elementet i det indexet.
Ersätt	`Replace` -åtgärden liknar förutom att `Set` den endast följer strikt ersätta semantik. Om målsökvägen anger ett element eller en matris som inte finns resulterar det i ett fel.
Ta bort	`Remove` utför något av följande beroende på målsökvägen: • Om målsökvägen anger ett element som inte finns resulterar det i ett fel. • Om målsökvägen anger ett element som redan finns tas det bort. • Om målsökvägen är ett matrisindex tas den bort och alla element ovanför det angivna indexet flyttas tillbaka en position. Obs! Om du anger ett index som är lika med eller större än matrislängden skulle det resultera i ett fel.
Ökning	Den här operatorn ökar ett fält med det angivna värdet. Den kan acceptera både positiva och negativa värden. Om fältet inte finns skapar det fältet och anger det till det angivna värdet.
Flytta	Den här operatorn tar bort värdet på en angiven plats och lägger till det på målplatsen. Åtgärdsobjektet MÅSTE innehålla en "från"-medlem, som är en sträng som innehåller ett JSON-pekarvärde som refererar till platsen i måldokumentet att flytta värdet från. Platsen "från" MÅSTE finnas för att åtgärden ska lyckas. Om sökvägsplatsen föreslår ett objekt som inte finns skapar det objektet och anger värdet lika med värdet på "från"-platsen •Om sökvägsplatsen föreslår ett objekt som redan finns ersätter det värdet på sökvägens plats med värdet "från" plats Attributet Path kan inte vara ett JSON-underordnat till JSON-platsen från

Lägen som stöds

Funktionen partiell dokumentuppdatering stöder följande driftslägen. I dokumentet Komma igång finns kodexempel.

Korrigering av enkla dokument: Du kan korrigera ett enskilt dokument baserat på dess ID och partitionsnyckeln. Det går att köra flera korrigeringsåtgärder i ett enda dokument. Den maximala gränsen är 10 åtgärder.
Korrigering av flera dokument: Flera dokument inom samma partitionsnyckel kan korrigeras som en del av en transaktion. Den här transaktionen med flera dokument checkas bara in om alla åtgärder lyckas i den ordning de beskrivs. Om en åtgärd misslyckas återställs hela transaktionen.
Villkorsstyrd uppdatering: För ovan nämnda lägen är det också möjligt att lägga till ett SQL-liknande filterpredikat (till exempel from c where c.taskNum = 3) så att åtgärden misslyckas om villkoret som anges i predikatet inte uppfylls.
Du kan också använda mass-API:er för SDK:er som stöds för att köra en eller flera korrigeringsåtgärder på flera dokument.

Likheter och skillnader

Nu ska vi jämföra likheterna och skillnaderna mellan de lägen som stöds.

Lägg till vs set

SetAdd liknar för alla datatyper utom Array. En Add åtgärd vid valfritt (giltigt) index resulterar i att ett element läggs till i det angivna indexet och att befintliga element i matrisen flyttas efter det befintliga elementet. Det här beteendet står i kontrast till Set den åtgärd som uppdaterar det befintliga elementet i det angivna indexet.

Lägg till jämfört med Ersätt

Add lägger till en egenskap om den inte redan finns (inklusive Array datatyp). Replace åtgärden misslyckas om egenskapen inte finns (gäller även för Array datatypen).

Ange vs Ersätt

Set -åtgärden lägger till en egenskap om den inte redan finns (förutom om det fanns en Array). Replace åtgärden misslyckas om egenskapen inte finns (gäller även för Array datatypen).

Anteckning

Replace är en bra kandidat där användaren förväntar sig att vissa av egenskaperna alltid ska finnas och gör att du kan hävda/framtvinga det.

REST API-referens för partiell dokumentuppdatering

Rest-API:et för Azure Cosmos DB ger programmatisk åtkomst till Azure Cosmos DB-resurser för att skapa, fråga och ta bort databaser, dokumentsamlingar och dokument. Förutom att köra åtgärderna insert, replace, delete, read, enumerate och query på JSON-dokument i en samling kan du använda PATCH HTTP-metoden för partiell dokumentuppdatering. Mer information finns i REST API-referensen för Azure Cosmos DB .

Så här ser begäran till exempel ut för en set åtgärd med hjälp av partiell dokumentuppdatering.

PATCH https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1 HTTP/1.1
x-ms-documentdb-partitionkey: ["Andersen"]
x-ms-date: Tue, 29 Mar 2016 02:28:29 GMT
Authorization: type%3dmaster%26ver%3d1.0%26sig%3d92WMAkQv0Zu35zpKZD%2bcGSH%2b2SXd8HGxHIvJgxhO6%2fs%3d
Content-Type:application/json_patch+json
Cache-Control: no-cache
User-Agent: Microsoft.Azure.DocumentDB/2.16.12
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Cookie: x-ms-session-token#0=602; x-ms-session-token=602
Content-Length: calculated when request is sent
Connection: keep-alive

{
  "operations": [
    {
      "op": "set",
      "path": "/Parents/0/FamilyName",
      "value": "Bob"
    }
  ]
}

Konfliktlösning på dokumentnivå kontra sökvägsnivå

Om ditt Azure Cosmos DB-konto har konfigurerats med flera skrivregioner gäller konflikter och konfliktlösningsprinciper på dokumentnivå, där senaste skrivningsvinster (LWW) är standardprincipen för konfliktlösning. För partiella dokumentuppdateringar identifierar och löser korrigeringsåtgärder i flera regioner konflikter på en mer detaljerad sökvägsnivå.

Konfliktlösning kan bättre tolkas med ett exempel.

Anta att du har följande dokument i Azure Cosmos DB:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345", "67890"],
  "level": "gold"
}

Olika klienter utfärdar korrigeringsåtgärder samtidigt i olika regioner:

Set attribut /level till platina
Remove 67890 från /phone

Eftersom korrigeringsbegäranden gjordes till icke-konfigurationssökvägar i dokumentet löses dessa begäranden automatiskt och transparent (i motsats till Senaste skrivningsvinster på dokumentnivå).

Klienten ser följande dokument efter konfliktlösning:

{
  "id": 1,
  "name": "John Doe",
  "email": "jdoe@contoso.com",
  "phone": ["12345"],
  "level": "platinum"
}

Anteckning

Om samma egenskap för ett dokument samtidigt korrigeras i flera regioner gäller de vanliga konfliktlösningsprinciperna .

Ändringsfeed

Ändringsflödet i Azure Cosmos DB lyssnar på en container efter ändringar och matar sedan ut dokument som har ändrats. Med hjälp av ändringsflöde ser du alla uppdateringar av dokument, inklusive både partiella och fullständiga dokumentuppdateringar. När du bearbetar objekt från ändringsflödet returneras det fullständiga dokumentet även om uppdateringen var resultatet av en korrigeringsåtgärd.

Mer information om ändringsflödet i Azure Cosmos DB finns i Ändringsflöde i Azure Cosmos DB.

Nästa steg

Lär dig hur du kommer igång med partiell dokumentuppdatering med hjälp av .NET, Java och Node
Vanliga frågor och svar om partiell dokumentuppdatering

Partiell dokumentuppdatering i Azure Cosmos DB

Åtgärder som stöds

Lägen som stöds

Likheter och skillnader

Lägg till vs set

Lägg till jämfört med Ersätt

Ange vs Ersätt

REST API-referens för partiell dokumentuppdatering

Konfliktlösning på dokumentnivå kontra sökvägsnivå

Ändringsfeed

Nästa steg

Ytterligare resurser