Skip to content

Add API reference documentation for field-update #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abinav2307 merged 1 commit into from
Dec 30, 2025
Merged

Add API reference documentation for field-update #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
200 changes: 200 additions & 0 deletions api-reference/operators/field-update/$currentdate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,200 @@
---
title: $currentDate
description: The $currentDate operator sets the value of a field to the current date, either as a Date or a timestamp.
type: operators
category: field-update
---

# $currentDate

The `$currentDate` operator sets the value of a field to the current date, either as a Date or a timestamp. This operator is useful for tracking when documents were last modified or for setting creation timestamps.

## Syntax

```javascript
{
$currentDate: {
<field1>: <typeSpecification1>,
<field2>: <typeSpecification2>,
...
}
}
```

## Parameters

| Parameter | Description |
| --- | --- |
| **`field`** | The name of the field to set to the current date. |
| **`typeSpecification`** | Optional. Specifies the type of the date value. Can be `true` (for Date type) or `{ $type: "timestamp" }` for timestamp type. Default is `true` (Date). |

## Examples

Consider this sample document from the stores collection.

```json
{
"_id": "7954bd5c-9ac2-4c10-bb7a-2b79bd0963c5",
"name": "Lakeshore Retail | DJ Equipment Stop - Port Cecile",
"location": {
"lat": 60.1441,
"lon": -141.5012
},
"staff": {
"totalStaff": {
"fullTime": 2,
"partTime": 0
}
},
"sales": {
"salesByCategory": [
{
"categoryName": "DJ Headphones",
"totalSales": 35921
}
],
"fullSales": 3700
},
"promotionEvents": [
{
"eventName": "Bargain Blitz Days",
"promotionalDates": {
"startDate": {
"Year": 2024,
"Month": 3,
"Day": 11
},
"endDate": {
"Year": 2024,
"Month": 2,
"Day": 18
}
},
"discounts": [
{
"categoryName": "DJ Turntables",
"discountPercentage": 18
},
{
"categoryName": "DJ Mixers",
"discountPercentage": 15
}
]
}
],
"tag": [
"#ShopLocal",
"#SeasonalSale",
"#FreeShipping",
"#MembershipDeals"
],
"company": "Lakeshore Retail",
"city": "Port Cecile",
"lastUpdated": {
"$date": "2024-12-11T10:21:58.274Z"
}
}
```

### Example 1: Setting current date

To add a `lastUpdated` field with the current date to a store document, use the $currentDate operator to create the field with the current date as a Date object.

```javascript
db.stores.updateOne(
{ "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f" },
{
$currentDate: {
"lastUpdated": true
}
}
)
```

This operation returns the following the result.

```json
{
acknowledged: true,
insertedId: null,
matchedCount: 1,
modifiedCount: 1,
upsertedCount: 0
}

```

### Example 2: Setting current timestamp

To add both a date field and a timestamp field to track modifications, use the $currentDate operator with a value of true and with a typestamp value.

```javascript
db.stores.updateOne(
{ "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f" },
{
$currentDate: {
"lastModified": true,
"lastModifiedTimestamp": { $type: "timestamp" }
}
}
)
```

This operation returns the following result

```json
{
acknowledged: true,
insertedId: null,
matchedCount: Long("1"),
modifiedCount: Long("1"),
upsertedCount: 0
}
```

### Example 3: Updating nested fields

Set current date for nested fields in the document structure.

```javascript
db.stores.updateOne(
{ "_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f" },
{
$currentDate: {
"sales.lastSalesUpdate": true,
"staff.lastStaffUpdate": { $type: "timestamp" }
}
}
)
```

This operation returns the following result.

```json
[
{
"_id": "2cf3f885-9962-4b67-a172-aa9039e9ae2f",
"name": "First Up Consultants | Bed and Bath Center - South Amir",
"lastUpdated": ISODate("2025-02-12T10:30:45.123Z"),
"lastModified": ISODate("2025-02-12T10:30:45.123Z"),
"lastModifiedTimestamp": Timestamp(1739450445, 1),
"sales": {
"totalSales": 37701,
"lastSalesUpdate": ISODate("2025-02-12T10:30:45.123Z"),
"salesByCategory": [
{
"categoryName": "Mattress Toppers",
"totalSales": 37701
}
]
},
"staff": {
"totalStaff": {
"fullTime": 18,
"partTime": 17
},
"lastStaffUpdate": Timestamp(1739450445, 1)
}
}
]
```
156 changes: 156 additions & 0 deletions api-reference/operators/field-update/$inc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
---
title: $inc
description: The $inc operator increments the value of a field by a specified amount.
type: operators
category: field-update
---

# $inc

The `$inc` operator increments the value of a field by a specified amount. If the field doesn't exist, `$inc` creates the field and sets it to the specified value. The operator accepts positive and negative values for incrementing and decrementing respectively.

## Syntax

The syntax for the `$inc` operator is as follows:

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

## Parameters

| Parameter | Description |
| --- | --- |
| **`field`** | The name of the field to increment. |
| **`amount`** | The increment value. Must be a number (positive for increment, negative for decrement). |

## Examples

Consider this sample document from the stores collection.

```json
{
"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
"name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury",
"staff": {
"totalStaff": {
"fullTime": 19,
"partTime": 20
}
},
"sales": {
"totalSales": 151864,
"salesByCategory": [
{
"categoryName": "Sound Bars",
"totalSales": 2120
},
{
"categoryName": "Home Theater Projectors",
"totalSales": 45004
}
]
}
}
```

### Example 1: Incrementing staff count

To increase the full-time staff count by 3, use the $inc operator on the fullTime staff field with a value of 3.

```javascript
db.stores.updateOne(
{ "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" },
{
$inc: {
"staff.totalStaff.fullTime": 3
}
}
)
```

### Example 2: Decreasing and increasing values

To decrease the part-time staff by 2 and increase total sales by 5000, use the $inc operator on both fields with values of -2 and 5000 respectively.

```javascript
db.stores.updateOne(
{ "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" },
{
$inc: {
"staff.totalStaff.partTime": -2,
"sales.totalSales": 5000
}
}
)
```

### Example 3: Creating New Fields

If a field doesn't exist, `$inc` creates it with the specified value.

```javascript
db.stores.updateOne(
{ "_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74" },
{
$inc: {
"staff.contractorCount": 5,
"sales.monthlyTarget": 200000
}
}
)
```

### Example 4: Incrementing array element values

Update specific sales figures within the salesByCategory array using positional operators.

```javascript
db.stores.updateOne(
{
"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
"sales.salesByCategory.categoryName": "Sound Bars"
},
{
$inc: {
"sales.salesByCategory.$.totalSales": 500
}
}
)
```

After these operations, the document is updated as follows:

```json
{
"_id": "40d6f4d7-50cd-4929-9a07-0a7a133c2e74",
"name": "Proseware, Inc. | Home Entertainment Hub - East Linwoodbury",
"staff": {
"totalStaff": {
"fullTime": 22,
"partTime": 18
},
"contractorCount": 5
},
"sales": {
"totalSales": 156864,
"monthlyTarget": 200000,
"salesByCategory": [
{
"categoryName": "Sound Bars",
"totalSales": 2620
},
{
"categoryName": "Home Theater Projectors",
"totalSales": 45004
}
]
}
}
```
Loading