Skip to main content

Data operators

Data objects in a datastore can be manipulated in any update operation. To manipulate one or many data object(s) a range of special operators can be applied using the updateOne(...) or updateMany(...) API.

Operators quick overview

$inc operator​

Increase or decrease a field value on an existing datastore object.

Syntax: { $inc: { <field1>: <amount1>, <field2>: <amount2>, ... } }

Example:

// before
{..., "followers": 42}

const operator = {$inc: {"followers": 1}}
// Call update API, e.g. updateMany or updateOne
await conn.updateMany('mycollection', operator, {filter: {"status": "ACTIVE"}})

// after
{..., "followers": 43}

👉 Use negative values to decrement field.

$push operator​

Append an element to a sub array on an existing datastore object.

Syntax: { $push: { <field1>: <value1>, ... } }

Example:

// before
{"followers": 42, "comments": ["one", "three"]}

const operator = {$push: {"comments": "two"}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{"followers": 42, "comments": ["one", "three", "two"]}

$pull operator​

Remove an element from a sub array on an existing datastore object.

Pulls all matches from array.

Syntax: { $pull: { <field1>: <value>|<query>, <field2>: <value>|<query>, ... } }

Example:

// before
{"followers": 42, "comments": ["one", "two", "three"]}

const operator = {$pull: {"comments": "two"}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{"followers": 42, "comments": ["one", "three"]}

$pop operator​

Removes last element of a sub array on an existing datastore object.

Syntax: { $pop: { <field>: -1 | 1, ... } }

-1 pop first item of array, 1 pop last item of array.

Example:

// before
{"followers": 42, "comments": ["one", "three", "two"]}

const operator = {$pop: {"comments": 1}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{"followers": 42, "comments": ["one", "three"]}

$addToSet operator​

Insert an unique element to a sub array on an existing datastore object. Nothing is inserted if item already exists in set.

Syntax: { $addToSet: { <field1>: <value1>, ... } }

Example:

// before
{"followers": 42, "comments": ["one", "two", "three"]}

const operator = {$addToSet: {"items": {"name": "one", "price": 1}}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{
    "followers": 42, "comments": ["one", "two", "three"], 
    "items": [{"name": "one", "price": 1}]
}

$set operator​

Set any object value.

Syntax: { $set: { <field1>: <value1>, ... } }

Example:

// before
{"followers": 42, "comments": ["one", "two", "three"]}

const operator = {$set: {"address": {"street": "Main street", "ZIP": 1123}}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{
    "followers": 42, "comments": ["one", "two", "three"], 
    "address": {"street": "Main street", "ZIP": 1123}
}

$unset operator​

Delete an object property.

Syntax: { $unset: { <field1>: "", ... } }

// before
{"followers": 42, "comments": ["one", "two", "three"]}

const operator = {$unset: {"comments": ""}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{
    "followers": 42
}

$rename operator​

Rename an object property.

Syntax: {$rename: { <field1>: <newName1>, <field2>: <newName2>, ... } }

// before
{"followers": 42, "comments": ["one", "two", "three"]}

const operator = {$rename: {"comments": "claps"}}
// E.g.: await conn.updateOne('customer', ID, operator);

// after
{
    "followers": 42, "claps": ["one", "two", "three"]
}