Skip to main content

Update Documents

The Update API is used to update existing documents that match the filters. Fields that need to be updated are specified when calling the API.

Request Specification

HTTP APIHTTP MethodURL ParamsResource
UPDATEPUT
  • Database Name
  • Collection Name
  • /databases/{db}/collections/{collection}/documents/update

    Request Payload

    {
    "fields": {
    "$set": {
    <field1>: <new-value>
    }
    },
    "filter": {
    <field1>: number|string|boolean,
    <field2>: {<$lt|$lte|$gt|$gte>: number},
    <$and|$or>: [<field3>: number|string|boolean, expr1, expr2...]
    }
    }

    Understanding the request payload:

    • The fields has $set operator that allows you to set fields to new values.
    • The filter syntax is similar as documented in the Query section.

    Response Payload

    The response has modified_count that returns number of documents updated as part of the request. An update doesn't return an error if no documents is modified. The modified_count will not be returned in the response in that case.

    Example collection

    The first step is to set up the collection object. All the operations on the collection is performed through this collection object.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/createOrUpdate' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{
    "schema":{
    "title":"catalog",
    "properties":{
    "id":{
    "type":"integer",
    "format":"int32",
    "autoGenerate":true
    },
    "name":{
    "type":"string"
    },
    "price":{
    "type":"number"
    },
    "brand":{
    "type":"string"
    },
    "labels":{
    "type":"string"
    },
    "popularity":{
    "type":"integer"
    },
    "reviews":{
    "type":"object",
    "properties":{
    "author":{
    "type":"string"
    },
    "rating":{
    "type":"number"
    }
    }
    }
    },
    "primary_key":[
    "id"
    ]
    }
    }'

    Now let's assume an e-commerce website that has the above collection catalog and has 5 products(documents) present in it.

    idnamepricebrandlabelspopularityreviews
    1fiona handbag99.9michael korspurses8{"author": "alice", "rating": 7}
    2tote bag49coachhandbags9{"author": "olivia", "rating": 8.3}
    3sling bag75coachpurses9{"author": "alice", "rating": 9.2}
    4sneakers shoes40adidasshoes10{"author": "olivia", "rating": 9}
    5running shoes89nikeshoes10{"author": "olivia", "rating": 8.5}

    Simple Update

    A simple update is by updating a document that matches the id which is the primary key of this collection. In the above collection, let's say there is a need to modify the price of a product that has an id assigned as 1.

    # Note the modified_count in the response. It should 1 if there was a document with an id 1 exists
    # in the database and is modified as part of this request.
    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/update' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "fields": {
    "$set": {"price": 65}
    },
    "filter": {
    "id": 1
    }
    }'

    Updates using logical OR

    A single update is shown in the above example but there could be a need to update multiple products by their primary key. A logical OR filter is one of the ways of updating multiple documents. The example below is updating the popularity score for two documents that have id 1 or 4.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/update' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "fields": {
    "$set": {
    "popularity": 9
    }
    },
    "filter": {
    "$or": [{
    "id": 1
    }, {
    "id": 4
    }]
    }
    }'

    Range update

    Extending the example, what if there is a need to reset the popularity score of a few products but these product ids are continuous? In this case, a range update can be performed on this field. The following example is applying range update on the id field.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/update' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "fields": {
    "$set": {
    "popularity": 9
    }
    },
    "filter": {
    "$and": [{
    "id": {"$gte": 2}
    }, {
    "id": {"$lte": 4}
    }]
    }
    }'
    note

    More filters can be used to narrow down the results further.

    Filtering on multiple fields

    There may be cases when you don't know the primary key value and instead wants to update a document by applying a condition on the non-primary key field. The following example is increasing the price of a product when the name and brand match with the documents present in the collection.

    curl 'http://localhost:8081/v1/databases/catalogdb/collections/catalog/documents/update' \
    -X PUT \
    -H "Content-Type: application/json" \
    -d '{
    "fields": {
    "$set": {"price": 85}
    },
    "filter": {
    "name": "sneakers shoes",
    "brand": "adidas"
    }
    }'