$setOnInsert

  • Gilt für:: ✅ Azure DocumentDB

Der $setOnInsert Operator wird verwendet, um Feldwerte nur festzulegen, wenn ein Upsert-Vorgang zum Einfügen eines neuen Dokuments führt. Wenn das Dokument bereits vorhanden ist und aktualisiert wird, hat der $setOnInsert Operator keine Auswirkung. Dieser Operator eignet sich besonders zum Festlegen von Standardwerten oder Initialisierungsdaten, die nur beim Erstellen neuer Dokumente angewendet werden sollen.

Syntax

{
  $setOnInsert: {
    <field1>: <value1>,
    <field2>: <value2>,
    ...
  }
}

Die Parameter

Parameter Description
field Der Name des Felds, das nur beim Einfügen festgelegt werden soll. Dies kann ein Feld auf oberster Ebene sein oder die Punktnotation für geschachtelte Felder verwenden.
value Der Wert, der dem Feld nur beim Einfügen eines neuen Dokuments zugewiesen werden soll. Kann ein beliebiger gültiger BSON-Typ sein.

Examples

Betrachten Sie dieses Beispieldokument aus der Stores-Sammlung.

{
    "_id": "0fcc0bf0-ed18-4ab8-b558-9848e18058f4",
    "name": "First Up Consultants | Beverage Shop - Satterfieldmouth",
    "location": {
        "lat": -89.2384,
        "lon": -46.4012
    },
    "staff": {
        "totalStaff": {
            "fullTime": 8,
            "partTime": 20
        }
    },
    "sales": {
        "totalSales": 75670,
        "salesByCategory": [
            {
                "categoryName": "Wine Accessories",
                "totalSales": 34440
            },
            {
                "categoryName": "Bitters",
                "totalSales": 39496
            },
            {
                "categoryName": "Rum",
                "totalSales": 1734
            }
        ]
    },
    "promotionEvents": [
        {
            "eventName": "Unbeatable Bargain Bash",
            "promotionalDates": {
                "startDate": {
                    "Year": 2024,
                    "Month": 6,
                    "Day": 23
                },
                "endDate": {
                    "Year": 2024,
                    "Month": 7,
                    "Day": 2
                }
            },
            "discounts": [
                {
                    "categoryName": "Whiskey",
                    "discountPercentage": 7
                },
                {
                    "categoryName": "Bitters",
                    "discountPercentage": 15
                },
                {
                    "categoryName": "Brandy",
                    "discountPercentage": 8
                },
                {
                    "categoryName": "Sports Drinks",
                    "discountPercentage": 22
                },
                {
                    "categoryName": "Vodka",
                    "discountPercentage": 19
                }
            ]
        },
        {
            "eventName": "Steal of a Deal Days",
            "promotionalDates": {
                "startDate": {
                    "Year": 2024,
                    "Month": 9,
                    "Day": 21
                },
                "endDate": {
                    "Year": 2024,
                    "Month": 9,
                    "Day": 29
                }
            },
            "discounts": [
                {
                    "categoryName": "Organic Wine",
                    "discountPercentage": 19
                },
                {
                    "categoryName": "White Wine",
                    "discountPercentage": 20
                },
                {
                    "categoryName": "Sparkling Wine",
                    "discountPercentage": 19
                },
                {
                    "categoryName": "Whiskey",
                    "discountPercentage": 17
                },
                {
                    "categoryName": "Vodka",
                    "discountPercentage": 23
                }
            ]
        }
    ]
}

Beispiel 1: Grundlegende $setOnInsert Verwendung

Zum Erstellen oder Aktualisieren eines Speicherdatensatzes legen Sie beim Erstellen eines neuen Speichers jedoch nur bestimmte Initialisierungsfelder fest.

db.stores.updateOne(
  { "_id": "new-store-001" },
  {
    $set: {
      "name": "Trey Research Electronics - Downtown",
      "sales.totalSales": 0
    },
    $setOnInsert: {
      "createdDate": new Date(),
      "status": "new",
      "staff.totalStaff.fullTime": 0,
      "staff.totalStaff.partTime": 0,
      "version": 1
    }
  },
  { upsert: true }
)

Dieser Vorgang gibt das folgende Ergebnis zurück.

{
  acknowledged: true,
  insertedId: 'new-store-001',
  matchedCount: 0,
  modifiedCount: Long("0"),
  upsertedCount: 1
}

Da das Dokument _id: "new-store-001" nicht vorhanden ist, erstellt dieser Vorgang das folgende neue Dokument:

{
  "_id": "new-store-001",
  "name": "Trey Research Electronics - Downtown",
  "sales": {
    "totalSales": 0
  },
  "createdDate": ISODate("2025-06-05T10:30:00.000Z"),
  "status": "new",
  "staff": {
    "totalStaff": {
      "fullTime": 0,
      "partTime": 0
    }
  },
  "version": 1
}

Beispiel 2: $setOnInsert mit vorhandenem Dokument

Jetzt versuchen wir, dasselbe Dokument erneut mit unterschiedlichen Werten zu erweitern:

db.stores.updateOne(
  { "_id": "new-store-001" },
  {
    $set: {
      "name": "Trey Research Electronics - Downtown Branch",
      "sales.totalSales": 5000
    },
    $setOnInsert: {
      "createdDate": new Date(),
      "status": "updated",
      "staff.totalStaff.fullTime": 10,
      "staff.totalStaff.partTime": 5,
      "version": 2
    }
  },
  { upsert: true }
)

Da das Dokument bereits vorhanden ist, werden nur die $set Vorgänge angewendet und $setOnInsert ignoriert:

{
  "_id": "new-store-001",
  "name": "Trey Research Electronics - Downtown Branch",
  "sales": {
    "totalSales": 5000
  },
  "createdDate": ISODate("2025-06-05T10:30:00.000Z"),
  "status": "new",
  "staff": {
    "totalStaff": {
      "fullTime": 0,
      "partTime": 0
    }
  },
  "version": 1
}

Beispiel 3: Komplexe $setOnInsert mit geschachtelten Objekten

Sie können verwenden $setOnInsert , um komplexe geschachtelte Strukturen zu initialisieren:

db.stores.updateOne(
  { "name": "Adatum Gaming Paradise - Mall Location" },
  {
    $set: {
      "location.lat": 35.6762,
      "location.lon": 139.6503
    },
    $setOnInsert: {
      "_id": "gaming-store-mall-001",
      "createdDate": new Date(),
      "status": "active",
      "staff": {
        "totalStaff": {
          "fullTime": 8,
          "partTime": 12
        },
        "manager": "Alex Johnson",
        "departments": ["gaming", "accessories", "repairs"]
      },
      "sales": {
        "totalSales": 0,
        "salesByCategory": []
      },
      "operatingHours": {
        "weekdays": "10:00-22:00",
        "weekends": "09:00-23:00"
      },
      "metadata": {
        "version": 1,
        "source": "store-management-system"
      }
    }
  },
  { upsert: true }
)

Beispiel 4: Verwenden von $setOnInsert mit Arrays

Sie können Arrays und komplexe Datenstrukturen initialisieren:

db.stores.updateOne(
  { "address.city": "New Tech City" },
  {
    $set: {
      "name": "Future Electronics Hub",
      "sales.totalSales": 25000
    },
    $setOnInsert: {
      "_id": "future-electronics-001",
      "establishedDate": new Date(),
      "categories": ["electronics", "gadgets", "smart-home"],
      "promotionEvents": [],
      "ratings": {
        average: 0,
        count: 0,
        reviews: []
      },
      "inventory": {
        lastUpdated: new Date(),
        totalItems: 0,
        lowStockAlerts: []
      }
    }
  },
  { upsert: true }
)

Von Bedeutung

Der $setOnInsert Operator wird nur während upsert-Vorgängen ({ upsert: true }) wirksam.

Wenn das Dokument vorhanden ist, $setOnInsert werden Felder vollständig ignoriert.

$setOnInsert wird häufig verwendet $set , um Sowohl Update- als auch Einfügeszenarien in einem einzigen Vorgang zu behandeln.

Sie können mit anderen Updateoperatoren wie $setOnInsert, $incusw. kombinieren$push.

Der $setOnInsert Operator eignet sich ideal zum Festlegen von Zeitstempeln, Standardwerten und Initialisierungsdaten.

  • Last updated on