From 625f7af31aa5a907d95d1b00295f25c400d3a72d Mon Sep 17 00:00:00 2001
From: kay <kay.kim@10gen.com>
Date: Mon, 25 Feb 2013 14:54:02 -0500
Subject: [PATCH] DOCS-875  operator

---
 source/reference/operator/setOnInsert.txt | 80 +++++++++++++++++++++++
 source/release-notes/2.4.txt              | 39 +++++++++++
 2 files changed, 119 insertions(+)
 create mode 100644 source/reference/operator/setOnInsert.txt

diff --git a/source/reference/operator/setOnInsert.txt b/source/reference/operator/setOnInsert.txt
new file mode 100644
index 00000000000..a7e089b775f
--- /dev/null
+++ b/source/reference/operator/setOnInsert.txt
@@ -0,0 +1,80 @@
+============
+$setOnInsert
+============
+
+.. default-domain:: mongodb
+
+.. operator:: $setOnInsert
+
+   .. versionadded:: 2.4
+
+   The :operator:`$setOnInsert` operator assigns values to fields
+   during an :method:`upsert <db.collection.update()>` **only** when
+   the :method:`upsert <db.collection.update()>` performs an insert.
+
+   .. code-block:: javascript
+
+      db.collection.update( <query>,
+                            { $setOnInsert: { <field1>: <value1>, ... } },
+                            { upsert: true }
+                          )
+   .. example::
+
+      A collection named ``products`` contains no documents.
+
+      Then, the following :method:`upsert <db.collection.update()>`
+      operation performs an insert and applies the
+      :operator:`$setOnInsert` to set the field ``defaultQty`` to
+      ``100``:
+
+      .. code-block:: javascript
+
+         db.products.update(
+                             { _id: 1 },
+                             { $setOnInsert: { defaultQty: 100 } },
+                             { upsert: true }
+                           )
+
+      The ``products`` collection contains the newly-inserted document:
+
+      .. code-block:: javascript
+
+         { "_id" : 1, "defaultQty" : 100 }
+
+   .. note::
+
+      The :operator:`$setOnInsert` operator performs no operation for
+      :method:`upserts <db.collection.update()>` that only perform an
+      update and for :method:`updates <db.collection.update()>` where
+      ``upsert`` is not specified or is set to ``false``.
+
+   .. example::
+
+      A collection named ``products`` has the following document:
+
+      .. code-block:: javascript
+
+         { "_id" : 1, "defaultQty" : 100 }
+
+      The following :method:`upsert <db.collection.update()>` operation
+      performs an update:
+
+      .. code-block:: javascript
+
+         db.products.update(
+                             { _id: 1 },
+                             { $setOnInsert: { defaultQty: 500, inStock: true },
+                               $set: { item: "apple" } },
+                             { upsert: true }
+                           )
+
+      Because the :method:`upsert <db.collection.update()>` performs an
+      update only, the upsert ignores the :operator:`$setOnInsert`
+      operation and only applies the :operator:`$set` operation.
+      
+      The ``products`` collection contains the following modified
+      document:
+
+      .. code-block:: javascript
+
+         { "_id" : 1, "defaultQty" : 100, "item" : "apple" }
diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt
index 20a74631e4b..c35023db46f 100644
--- a/source/release-notes/2.4.txt
+++ b/source/release-notes/2.4.txt
@@ -1431,3 +1431,42 @@ key. Consider the following properties when using a hashed shard key:
    Avoid using hashed shard keys when the hashed field has non-integral floating
    point values, see :ref:`hashed indexes <hashed-index-warning>` for
    more information.
+
+New Update Operators
+~~~~~~~~~~~~~~~~~~~~
+
+``$setOnInsert``
+````````````````
+
+To set fields *only* when an :method:`upsert <db.collection.update()>`
+performs an insert, use the :operator:`$setOnInsert` operator with the
+:method:`upsert <db.collection.update()>` .
+
+.. example::
+
+   A collection named ``coll`` has no documents with ``_id`` equal to
+   ``1``.
+
+   The following :method:`upsert <db.collection.update()>` operation
+   inserts a document and applies the :operator:`$setOnInsert` operator
+   to set the fields ``x`` and ``y``:
+
+   .. code-block:: javascript
+
+      db.coll.update( { _id: 1 }, 
+                      { $setOnInsert: { x: 25, y: 30 } }, 
+                      { upsert: true } )
+
+   The newly-inserted document has the field ``x`` set to ``25`` and
+   the field ``y`` set to 30:
+
+   .. code-block:: javascript
+
+      { "_id" : 1, "x" : 25, "y" : 30 }
+
+.. note::
+
+   The :operator:`$setOnInsert` operator performs no operation for
+   :method:`upserts <db.collection.update()>` that only perform an
+   update and for :method:`updates <db.collection.update()>` where
+   ``upsert`` is not specified or is set to ``false``.