Patch Document

Azure Cosmos DB is a globally distributed multi-model database with support for multiple APIs. This article covers the SQL API for Azure Cosmos DB.

The Patch Document operation does path-level updates to specific files/properties in a single document.

Request

Method	Request URI	Description
PATCH	https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs/{id}	The {databaseaccount} is the name of the Azure Cosmos DB account created under your subscription. The {db-id} value is the user-generated name/ID of the database, not the system-generated ID (rid). The {coll-id} value is the name of the collection that contains the document. The id is the value of the {id} in the document

Headers

See Common Azure Cosmos DB REST request headers for headers that are used by all Azure Cosmos DB requests.

Header	Required	Type	Description
x-ms-documentdb-partitionkey	Optional	Array	The partition key value for the document to be patched. Must be included if and only if the collection is created with a partitionKey definition.

Body

Property	Required	Type	Description
operations	Required	Array	Patch supports either a single, or multiple, operations that should be passed as an array

Single operation

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

Multiple operations

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

Conditional Patch operation

{
   "condition":"from c where c.Address.ZipCode ='98101' ",
   "operations":[
      {
         "op":"replace",
         "path":"/Address/ZipCode",
         "value":98107
      }
   ]
}

Response

Returns the body of the patched document.

Headers

See Common Azure Cosmos DB REST response headers for headers that are returned by all Azure Cosmos DB responses.

Property	Type	Description
x-ms-request-charge	Number	The number of request units consumed by the operation.
x-ms-session-token	String	A string token used with session level consistency. Clients must save this value and set it for subsequent read requests for session consistency.
Content-Location	String	URL of the patch content being passed.

Status codes

The following table lists common status codes returned by this operation. For a full list of status codes, see HTTP Status Codes.

HTTP status code	Description
200 OK	The operation was successful.
400 Bad Request	The JSON body is invalid.
412 Precondition Failed	The specified pre-condition isn't met

Body

Property	Description
_rid	It is a system-generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the document resource.
_ts	It is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp.
_self	It is a system-generated property that has URI for the resource.
_etag	It is a system-generated property that specifies the resource etag required for optimistic concurrency control.
_attachments	It is a system-generated property that specifies the addressable path for the attachments resource.

{
    "id": "Andersen.1",
    "LastName": "Andersen",
    "Parents": [
        {
            "FamilyName": "Bob",
            "FirstName": "Thomas"
        },
        {
            "FamilyName": null,
            "FirstName": "Mary Kay"
        }
    ],
    "Children": [
        {
            "FamilyName": null,
            "FirstName": "Henriette Thaulow",
            "Gender": "female",
            "Grade": 5,
            "Pets": [
                {
                    "GivenName": "Fluffy"
                }
            ]
        }
    ],
    "Address": {
        "State": "WA",
        "County": "King",
        "City": "Seattle"
    },
    "IsRegistered": false,
    "_rid": "2pFqAMMTYY8BAAAAAAAAAA==",
    "_self": "dbs/2pFqAA==/colls/2pFqAMMTYY8=/docs/2pFqAMMTYY8BAAAAAAAAAA==/",
    "_etag": "\"00000000-0000-0000-d40e-691edfa901d7\"",
    "_attachments": "attachments/",
    "_ts": 1636313638
}

Example

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" }]}

HTTP/1.1 200 OK  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Transfer-Encoding: chunked  
Content-Type: application/json 
Content-Location : https://querydemo.documents.azure.com/dbs/FamilyDatabase/colls/FamilyContainer/docs/Andersen.1
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:39:02.501 GMT  
etag: "00003200-0000-0000-0000-56f9e84d0000"  
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;  
x-ms-resource-usage: documentSize=0;documentsSize=1;collectionSize=1;  
x-ms-schemaversion: 1.1  
x-ms-alt-content-path: dbs/testdb/colls/testcoll  
x-ms-quorum-acked-lsn: 602  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 12.38  
x-ms-serviceversion: version=1.6.52.5  
x-ms-activity-id: 856acd38-320d-47df-ab6f-9761bb987668  
x-ms-session-token: 0:603  
Set-Cookie: x-ms-session-token#0=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
Set-Cookie: x-ms-session-token=603; Domain=querydemo.documents.azure.com; Path=/dbs/1KtjAA==/colls/1KtjAImkcgw=  
x-ms-gatewayversion: version=1.6.52.5  
Date: Tue, 29 Mar 2016 02:28:30 GMT  
  
{
    "id": "Andersen.1",
    "LastName": "Andersen",
    "Parents": [
        {
            "FamilyName": "Bob",
            "FirstName": "Thomas"
        },
        {
            "FamilyName": null,
            "FirstName": "Mary Kay"
        }
    ],
    "Children": [
        {
            "FamilyName": null,
            "FirstName": "Henriette Thaulow",
            "Gender": "female",
            "Grade": 5,
            "Pets": [
                {
                    "GivenName": "Fluffy"
                }
            ]
        }
    ],
    "Address": {
        "State": "WA",
        "County": "King",
        "City": "Seattle"
    },
    "IsRegistered": false,
    "_rid": "2pFqAMMTYY8BAAAAAAAAAA==",
    "_self": "dbs/2pFqAA==/colls/2pFqAMMTYY8=/docs/2pFqAMMTYY8BAAAAAAAAAA==/",
    "_etag": "\"00000000-0000-0000-d464-a585d94d01d7\"",
    "_attachments": "attachments/",
    "_ts": 1636350676
}

Del via

Patch Document

Request

Headers

Body

Single operation

Multiple operations

Conditional Patch operation

Response

Headers

Status codes

Body

Example

See Also

Yderligere ressourcer