DOCSP-35974: Update one usage example

docs/usage-examples/updateOne.txt

@@ -0,0 +1,77 @@
+.. _laravel-update-one-usage:
+
+=================
+Update a Document
+=================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: update one, modify, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can update a document in a collection by retrieving a single document and calling
+the ``update()`` method on an Eloquent model or a query builder.
+
+Pass a query filter to the ``where()`` method, sort the matching documents, and call the
+``first()`` method to match only one document. Then, update this matching document by passing
+your intended document changes to the ``update()`` method.
+
+Example
+-------
+
+This usage example performs the following actions:
+
+- Uses the ``Movie`` Eloquent model to represent the ``movies`` collection in the
+  ``sample_mflix`` database.
+- Updates a document from the ``movies`` collection that matches a query filter.
+
+The example calls the following methods on the ``Movie`` model:
+
+- ``where()``: matches documents in which the value of the ``title`` field is ``'Carol'``.
+- ``orderBy()``: sorts matched documents by their ascending ``_id`` values.
+- ``first()``: retrieves only the first matching document.
+- ``update()``: updates the value of the ``imdb.rating`` nested field to from ``6.9`` to
+  ``7.3``. This method also updates the ``imdb.votes`` nested field from ``493`` to ``142000``.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      $movie = Movie::where('title', 'Carol')
+          ->orderBy('_id')
+          ->first()
+          ->update([
+              "imdb" => [
+                  "rating" => 7.3,
+                  "votes" => 142000
+               ],
+         ]);
+
+   .. output::
+      :language: console
+      :visible: false
+
+      1
+
+The expected output shows the number of modified documents. To view the output, add the operation
+to a controller endpoint. Then, create a web route that calls the controller endpoint and returns
+the result to a web interface.
+
+.. tip::
+
+   You can add this usage example to the Laravel application created in the :ref:`laravel-quick-start`
+   and view the expected output. For instructions on editing your ``{+quickstart-app-name+}`` application
+   to run the usage example, see the :ref:`Usage Example landing page <laravel-usage-examples>`.
+
+To learn more about updating data with {+odm-short+}, see the `Updates
+<https://laravel.com/docs/6.x/eloquent#updates>`__ section of the Laravel documentation.