DOCSP-35957: Retrieve guide

docs/index.txt

@@ -13,6 +13,8 @@ Laravel MongoDB
    :titlesonly:
    :maxdepth: 1
 
+   /install
+   /retrieve
    /quick-start
    /eloquent-models
    /query-builder
@@ -50,6 +52,7 @@ Fundamentals
 To learn how to perform the following tasks by using the {+odm-short+},
 see the following content:
 
+- :ref:`laravel-fundamentals-retrieve`
 - :ref:`laravel-eloquent-models`
 - :ref:`laravel-query-builder`
 - :ref:`laravel-user-authentication`

docs/retrieve.txt

@@ -0,0 +1,360 @@
+.. _laravel-fundamentals-retrieve:
+
+==============
+Retrieve Data
+==============
+
+.. facet::
+   :name: genre
+   :values: tutorial
+
+.. meta::
+   :keywords: find one, find many, code example
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the Laravel package to perform **find operations**
+on your MongoDB collections. Find operations allow you to retrieve documents based on
+criteria that you specify.
+
+This guide shows you how to perform the following tasks:
+
+- :ref:`laravel-retrieve-matching`
+- :ref:`laravel-retrieve-all`
+- :ref:`Modify Find Operation Behavior <laravel-modify-find>`
+
+Prerequisites
+-------------
+
+Complete the :ref:`Quick Start <laravel-quick-start>` tutorial before running the examples in this
+guide.
+
+After completing the Quick Start, ensure that your MongoDB deployment and Laravel application
+satisfy the following requirements:
+
+- Your Atlas MongoDB deployment contains the Atlas sample data
+- ``Movie.php`` file contains a ``Movie`` model to represent the ``movies`` collection
+- ``MovieController.php`` file contains a ``show()`` function to run database operations
+- ``browse_movies.blade.php`` file contains HTML code to display the results of database
+  operations
+
+The following sections describe how to edit the files in your Laravel application to run 
+the code examples and view the expected output.
+
+.. _laravel-retrieve-matching:
+
+Retrieve Documents that Match a Query
+-------------------------------------
+
+You can retrieve documents that match a set of criteria by passing a query filter to the ``where()``
+method. A query filter specifies field value requirements and instructs the find operation
+to only return documents that meet these requirements. To run the query, call the ``where()``
+method on an Eloquent model or query builder that represents your collection.
+
+You can pass the following types of query filters to the ``where()`` method:
+
+- ``where('<field name>', <value>)``: instructs MongoDB to return documents that match
+  the exact value for the specified field name
+
+- ``where('<field name>', '<comparison operator>', <value>)``: instructs MongoDB to
+  return documents in which the field values meet the comparison criteria
+
+To apply multiple sets of criteria to the find operation, you can chain a series
+of ``where()`` methods together.
+
+.. _laravel-retrieve-eloquent:
+
+Use Eloquent Models to Retrieve Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent
+MongoDB collections. To retrieve documents from a collection, call the ``where()`` method
+on the collection's corresponding Eloquent model.
+
+This example calls two ``where()`` methods on the ``Movie`` Eloquent model to retrieve
+documents that meet the following criteria:
+
+- ``year`` field has a value of ``2010``
+- ``imdb.rating`` nested field has a value greater than ``8.5``
+
+.. important:: Required File Changes
+
+   To run the code example, you must edit the ``MovieController.php`` file in your
+   Laravel Quick Start application. Copy the code example and paste it into the ``show()``
+   function, replacing any existing code inside this function.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      return view('browse_movies', [
+         'movies' => Movie::where('year', 2010)
+            ->where('imdb.rating', '>', 8.5)
+            ->get()
+      ]);
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Title: Inception
+      Year: 2010
+      Runtime: 148
+      IMDB Rating: 8.8
+      IMDB Votes: 1294646
+      Plot: A thief who steals corporate secrets through use of dream-sharing
+      technology is given the inverse task of planting an idea into the mind of a CEO.
+
+      Title: Senna
+      Year: 2010
+      Runtime: 106
+      IMDB Rating: 8.6
+      IMDB Votes: 41904
+      Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the
+      F1 world championship three times before his death at age 34.
+
+.. _laravel-retrieve-query-builder:
+
+Use Laravel Queries to Retrieve Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use Laravel's database query builder to run find operations instead of using Eloquent
+models. To run the database query, import the ``DB`` facade into your controller file and use
+Laravel's query builder syntax.
+
+The following example uses Laravel's query builder to retrieve documents in which the value
+of the ``imdb.votes`` nested field is greater than ``1300000``.
+
+.. important:: Required File Changes
+
+   To run the code example, you must make the following changes to your Laravel Quick Start
+   application:
+
+   - Copy the code example and paste it into the ``show()`` function in your ``MovieController.php`` file
+   - Add the ``use Illuminate\Support\Facades\DB`` use statement to your ``MovieController.php``
+     file
+   - Replace ``DB_CONNECTION=mysql`` with ``DB_CONNECTION=mongodb`` in your ``.env`` file
+   - Replace the contents of your ``browse_movies.blade.php`` file with the following code:
+
+      .. code-block:: php
+
+         <!DOCTYPE html>
+         <html>
+         <head>
+            <title>Browse Movies</title>
+         </head>
+         <body>
+         <h2>Movies</h2>
+
+         @forelse ($movies as $movie)
+         <p>
+            Title: {{ $movie['title'] }}<br>
+            Year: {{ $movie['year'] }}<br>
+            Runtime: {{ $movie['runtime'] }}<br>
+            IMDB Rating: {{ $movie['imdb']['rating'] }}<br>
+            IMDB Votes: {{ $movie['imdb']['votes'] }}<br>
+            Plot: {{ $movie['plot'] }}<br>
+         </p>
+         @empty
+            <p>No results</p>
+         @endforelse
+
+         </body>
+         </html>
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      return view('browse_movies', [
+         'movies' => DB::collection('movies')
+               ->where('imdb.votes', '>', 1300000)
+               ->get()
+      ]);
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Title: The Shawshank Redemption
+      Year: 1994
+      Runtime: 142
+      IMDB Rating: 9.3
+      IMDB Votes: 1513145
+      Plot: Two imprisoned men bond over a number of years, finding solace and eventual redemption
+      through acts of common decency.
+
+      Title: The Dark Knight
+      Year: 2008
+      Runtime: 152
+      IMDB Rating: 9
+      IMDB Votes: 1495351
+      Plot: When the menace known as the Joker wreaks havoc and chaos on the people of Gotham, the
+      caped crusader must come to terms with one of the greatest psychological tests of his ability to
+      fight injustice.
+
+.. _laravel-retrieve-all:
+
+Retrieve All Documents in a Collection
+--------------------------------------
+
+You can retrieve documents without specifying a query filter, which returns all
+documents in a collection.
+
+To retrieve all documents, call the ``get()`` method on an Eloquent model that represents
+your collection. Alternatively, you can use the ``get()`` method's alias ``all()`` to perform
+the same operation.
+
+.. _laravel-retrieve-all-example:
+
+Retrieve All Documents
+~~~~~~~~~~~~~~~~~~~~~~
+
+Use the following syntax to run a find operation that matches all documents:
+
+.. code-block:: php
+
+   $movies = Movie::get();
+
+.. warning::
+
+   The ``movies`` collection in the Atlas sample dataset contains a large amount of data.
+   Retrieving and displaying all documents in this collection might cause your web 
+   application to time out.
+
+.. _laravel-modify-find:
+
+Modify Behavior
+---------------
+
+You can modify the results of a find operation by chaining the following methods
+to ``where()``:
+
+- ``skip()``: sets the number of documents to skip when returning results
+- ``take()``: sets the total number of documents to return
+- ``first()``: returns the first document that matches the query filter
+
+Skip and Limit Results
+~~~~~~~~~~~~~~~~~~~~~~
+
+The following example queries for documents in which the ``year`` value is ``1999``.
+The operation skips the first ``2`` matching documents and outputs a total of ``3``
+documents.
+
+.. important:: Required File Changes
+
+   To run the code example, you must edit the ``MovieController.php`` file in your
+   Laravel Quick Start application. Copy the code example and paste it into the ``show()``
+   function, replacing any existing code inside this function.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      return view('browse_movies', [
+         'movies' => Movie::where('year', 1999)
+            ->skip(2)
+            ->take(3)
+            ->get()
+      ]);
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Title: Three Kings
+      Year: 1999
+      Runtime: 114
+      IMDB Rating: 7.2
+      IMDB Votes: 130677
+      Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold
+      that was stolen from Kuwait, but they discover people who desperately need their help.
+
+      Title: Toy Story 2
+      Year: 1999
+      Runtime: 92
+      IMDB Rating: 7.9
+      IMDB Votes: 346655
+      Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him,
+      but Woody finds the idea of immortality in a museum tempting.
+
+      Title: Beowulf
+      Year: 1999
+      Runtime: 95
+      IMDB Rating: 4
+      IMDB Votes: 9296
+      Plot: A sci-fi update of the famous 6th Century poem. In a beseiged land, Beowulf must
+      battle against the hideous creature Grendel and his vengeance seeking mother.
+
+.. _laravel-retrieve-one:
+
+Retrieve Only One Result
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To retrieve only one document that matches a set of criteria, use the ``where()`` method
+followed by the ``first()`` method. By default, the ``first()`` method returns the first
+matching document according to the documents' natural order, or as they appear in the
+database. If you apply a sort to the find operation, ``first()`` returns the first matching
+document according to the sorted order. 
+
+The following example returns one document in which the value of the ``runtime`` field
+is ``30``.
+
+.. important:: Required File Changes
+
+   To run the code example, you must edit the ``MovieController.php`` file in your
+   Laravel Quick Start application. Copy the code example and paste it into the ``show()``
+   function, replacing any existing code inside this function.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      return view('browse_movies', [
+         'movies' => Movie::where('runtime', 30)
+            ->first()
+      ]);
+
+   .. output::
+      :language: none
+      :visible: false
+
+      Title: Statues also Die
+      Year: 1953
+      Runtime: 30
+      IMDB Rating: 7.6
+      IMDB Votes: 620
+      Plot: A documentary of black art.
+
+.. tip:: 
+
+   To learn more about sorting, see the following resources:
+
+   - :manual:`Natural order </reference/glossary/#std-term-natural-order>`
+     in the Server manual glossary
+   - `Ordering, Grouping, Limit and Offset
+     <https://laravel.com/docs/10.x/queries#ordering-grouping-limit-and-offset>`__ in the Laravel
+     documentation
+
+.. _laravel-addtl-info:
+
+Additional Information
+----------------------
+
+To learn more about other query methods in {+odm-short+}, see the :ref:`laravel-query-builder`
+page.