Update operators for collections

Use update operators to update documents in a collection.

All operators are case-sensitive.

Operator type Name Purpose

Operator type	Name	Purpose
Property update	`$currentDate`	Used in an update operation to set a property to the current date and time.
	`$inc`	Increments the value of the property by the specified amount.
	`$min`	Updates the property only if the specified value is less than the existing property value.
	`$max`	Updates the property only if the specified value is greater than the existing property value.
	`$mul`	Multiply the value of a property in the document.
	`$rename`	Renames the specified property in each matching document.
	`$set`	Sets the value of a property in each matching document.
	`$setOnInsert`	Set the value of a property in the document if an upsert is performed.
	`$unset`	Removes the specified property from each matching document.
Array update	`$addToSet`	Adds elements to the array only if they do not already exist in the set. You can use `$each` to append multiple items.
	`$pop`	Removes the first or last item of the array, depending on the value of the operator. Use `-1` to remove the first item. Use `1` to remove the last item.
	`$push`	Adds or appends data to the end of the property value. If the value is not yet an array and the property has no value, this operator creates a one-element array that contains the given item. If the value is not yet an array and the property has a non-array value, this operator creates a two-element array that has the existing value as the first entry and the given item as the second entry. You can use `$each` and `$position` to modify where and how the data is added to the array.
	`$each`	Modify the `$push` or `$addToSet` operators to append multiple items in array updates.
	`$position`	Modify the `$push` operator to specify the position in the array to add elements. Use `$position` to add an element to a specific position in an array. `$position` is only valid with `$push`, and `$each` is required, even if you want to insert a single item at the specified position.

Property update

$currentDate

Used in an update operation to set a property to the current date and time.

$inc

Increments the value of the property by the specified amount.

$min

Updates the property only if the specified value is less than the existing property value.

$max

Updates the property only if the specified value is greater than the existing property value.

$mul

Multiply the value of a property in the document.

$rename

Renames the specified property in each matching document.

$set

Sets the value of a property in each matching document.

$setOnInsert

Set the value of a property in the document if an upsert is performed.

$unset

Removes the specified property from each matching document.

Array update

$addToSet

Adds elements to the array only if they do not already exist in the set.

You can use $each to append multiple items.

$pop

Removes the first or last item of the array, depending on the value of the operator. Use -1 to remove the first item. Use 1 to remove the last item.

$push

Adds or appends data to the end of the property value. If the value is not yet an array and the property has no value, this operator creates a one-element array that contains the given item. If the value is not yet an array and the property has a non-array value, this operator creates a two-element array that has the existing value as the first entry and the given item as the second entry.

You can use $each and $position to modify where and how the data is added to the array.

$each

Modify the $push or $addToSet operators to append multiple items in array updates.

$position

Modify the $push operator to specify the position in the array to add elements.

Use $position to add an element to a specific position in an array. $position is only valid with $push, and $each is required, even if you want to insert a single item at the specified position.

Examples

If an upsert occurs, use the $setOnInsert operator to set additional document properties only for the new document:

json

"findOneAndUpdate": {
  "filter": {
    "_id": "27"
  },
  "update": {
    "$currentDate": {
      "field": true
    },
    "$setOnInsert": {
      "customer.name": "James B."
    }
  },
  "options": {
    "returnDocument": "after",
    "upsert": true
  }
}

Rename a field:

json

"findOneAndUpdate": {
  "filter": {
    "_id": "12"
  },
  "update": {
    "$rename": {
      "old_field": "new_field",
      "other_old_field": "other_new_field"
    }
  },
  "options": { "returnDocument": "after" }
}

json

"findOneAndUpdate": {
  "filter": {
    "_id": "12"
  },
  "update": {
    "$push": {
      "tags": {
        "$each": [ "new1", "new2" ],
        "$position": 0
      }
    }
  },
  "options": { "returnDocument": "after" }
}

Increment a value:

json

"findOneAndUpdate": {
  "filter": {
    "_id": "12"
  },
  "update": { "$inc": { "counter": 1 } },
  "options": { "returnDocument": "after" }
}

Uses $currentDate to set a property to the current date:

curl

curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": { "_id": "doc1" },
    "update": {
      "$currentDate": {
        "createdAt": true
        }
      }
    }
}' | jq

For more examples, see the references for commands that use these operators, such as:

Update operators for collections

Examples

Was this helpful?

Give Feedback