From b28cf9be28222012fca07612c7373b9b193e0231 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Feb 2025 16:19:55 -0500 Subject: [PATCH 1/5] DOCSP-35945: read operations reorg --- docs/fundamentals/read-operations.txt | 609 +----------------- .../read-operations/modify-results.txt | 300 +++++++++ .../fundamentals/read-operations/retrieve.txt | 223 +++++++ .../read-operations/search-text.txt | 157 +++++ .../before-you-get-started.rst | 15 + 5 files changed, 724 insertions(+), 580 deletions(-) create mode 100644 docs/fundamentals/read-operations/modify-results.txt create mode 100644 docs/fundamentals/read-operations/retrieve.txt create mode 100644 docs/fundamentals/read-operations/search-text.txt create mode 100644 docs/includes/fundamentals/read-operations/before-you-get-started.rst diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index d5605033b..a9f5447c6 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -10,7 +10,13 @@ Read Operations :values: tutorial .. meta:: - :keywords: find one, find many, code example + :keywords: find one, find many, skip, limit, paginate, string, code example + +.. toctree:: + + Retrieve Data + Search Text + Modify Query Results .. contents:: On this page :local: @@ -21,588 +27,31 @@ Read Operations Overview -------- -In this guide, you can learn how to use {+odm-long+} 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:`laravel-retrieve-text-search` -- :ref:`Modify Find Operation Behavior ` - -Before You Get Started ----------------------- - -To run the code examples in this guide, complete the :ref:`Quick Start ` -tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with -sample data and creating the following files in your Laravel web application: - -- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` - collection -- ``MovieController.php`` file, which contains a ``show()`` function to run database operations -- ``browse_movies.blade.php`` file, which 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 find operation code examples and view the expected output. - -.. _laravel-retrieve-matching: - -Retrieve Documents that Match a Query -------------------------------------- - -You can use Laravel's Eloquent object-relational mapper (ORM) to create models -that represent MongoDB collections and chain methods on them to specify -query criteria. - -To retrieve documents that match a set of criteria, call the ``where()`` -method on the collection's corresponding Eloquent model, then pass a query -filter to the method. - -A query filter specifies field value requirements and instructs the find -operation to return only documents that meet these requirements. - -You can use one of the following ``where()`` method calls to build a query: - -- ``where('', )`` builds a query that matches documents in - which the target field has the exact specified value - -- ``where('', '', )`` builds a query - that matches documents in which the target field's value meets the comparison - criteria - -To apply multiple sets of criteria to the find operation, you can chain a series -of ``where()`` methods together. - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -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`` - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-query - :end-before: end-query - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 2010) - ->where('imdb.rating', '>', 8.5) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. 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. - -To learn how to query by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder` page. - -Match Array Field Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can specify a query filter to match array field elements when -retrieving documents. If your documents contain an array field, you can -match documents based on if the value contains all or some specified -array elements. - -You can use one of the following ``where()`` method calls to build a -query on an array field: - -- ``where('', )`` builds a query that matches documents in - which the array field value is exactly the specified array - -- ``where('', 'in', )`` builds a query - that matches documents in which the array field value contains one or - more of the specified array elements - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -Select from the following :guilabel:`Exact Array Match` and -:guilabel:`Element Match` tabs to view the query syntax for each pattern: - -.. tabs:: - - .. tab:: Exact Array Match - :tabid: exact-array - - This example retrieves documents in which the ``countries`` array is - exactly ``['Indonesia', 'Canada']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-exact-array - :end-before: end-exact-array - - .. tab:: Element Match - :tabid: element-match - - This example retrieves documents in which the ``countries`` array - contains one of the values in the array ``['Canada', 'Egypt']``: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-elem-match - :end-before: end-elem-match - -To learn how to query array fields by using the Laravel query builder instead of the -Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in -the Query Builder guide. - -.. _laravel-retrieve-all: - -Retrieve All Documents in a Collection --------------------------------------- - -You can retrieve all documents in a collection by omitting the query filter. -To return the 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. - -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. - - To avoid this issue, specify a document limit by using the ``take()`` method. For - more information about ``take()``, see the :ref:`laravel-modify-find` section of this - guide. - -.. _laravel-retrieve-text-search: - -Search Text Fields ------------------- - -A text search retrieves documents that contain a **term** or a **phrase** in the -text-indexed fields. A term is a sequence of characters that excludes -whitespace characters. A phrase is a sequence of terms with any number -of whitespace characters. - -.. note:: - - Before you can perform a text search, you must create a :manual:`text - index ` on - the text-valued field. To learn more about creating - indexes, see the :ref:`laravel-eloquent-indexes` section of the - Schema Builder guide. - -You can perform a text search by using the :manual:`$text -` operator followed -by the ``$search`` field in your query filter that you pass to the -``where()`` method. The ``$text`` operator performs a text search on the -text-indexed fields. The ``$search`` field specifies the text to search for. - -After building your query by using the ``where()`` method, chain the ``get()`` -method to retrieve the query results. - -This example calls the ``where()`` method on the ``Movie`` Eloquent model to -retrieve documents in which the ``plot`` field contains the phrase -``"love story"``. To perform this text search, the collection must have -a text index on the ``plot`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text - :end-before: end-text - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('$text', ['$search' => '"love story"']) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Cafè de Flore - Year: 2011 - Runtime: 120 - IMDB Rating: 7.4 - IMDB Votes: 9663 - Plot: A love story between a man and woman ... - - Title: Paheli - Year: 2005 - Runtime: 140 - IMDB Rating: 6.7 - IMDB Votes: 8909 - Plot: A folk tale - supernatural love story about a ghost ... - - Title: Por un puèado de besos - Year: 2014 - Runtime: 98 - IMDB Rating: 6.1 - IMDB Votes: 223 - Plot: A girl. A boy. A love story ... - - ... - -A text search assigns a numerical :manual:`text score ` to indicate how closely -each result matches the string in your query filter. You can sort the -results by relevance by using the ``orderBy()`` method to sort on the -``textScore`` metadata field. You can access this metadata by using the -:manual:`$meta ` operator: - -.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-text-relevance - :end-before: end-text-relevance - :emphasize-lines: 2 - -.. tip:: - - To learn more about the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. - -.. _laravel-modify-find: - -Modify Behavior ---------------- - -You can modify the results of a find operation by chaining more methods -to ``where()``. - -The following sections demonstrate how to modify the behavior of the ``where()`` -method: - -- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents - to skip and the ``take()`` method to set the total number of documents to return -- :ref:`laravel-sort` uses the ``orderBy()`` method to return query - results in a specified order based on field values -- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document - that matches the query filter - -.. _laravel-skip-limit: - -Skip and Limit Results -~~~~~~~~~~~~~~~~~~~~~~ - -This 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. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-skip-limit - :end-before: end-skip-limit - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('year', 1999) - ->skip(2) - ->take(3) - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. 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 besieged land, Beowulf must - battle against the hideous creature Grendel and his vengeance seeking mother. - -.. _laravel-sort: - -Sort Query Results -~~~~~~~~~~~~~~~~~~ - -To order query results based on the values of specified fields, use the ``where()`` method -followed by the ``orderBy()`` method. - -You can set an **ascending** or **descending** sort direction on -results. By default, the ``orderBy()`` method sets an ascending sort on -the supplied field name, but you can explicitly specify an ascending -sort by passing ``"asc"`` as the second parameter. To -specify a descending sort, pass ``"desc"`` as the second parameter. - -If your documents contain duplicate values in a specific field, you can -handle the tie by specifying more fields to sort on. This ensures consistent -results if the other fields contain unique values. - -This example queries for documents in which the value of the ``countries`` field contains -``"Indonesia"`` and orders results first by an ascending sort on the -``year`` field, then a descending sort on the ``title`` field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-sort - :end-before: end-sort - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movies = Movie::where('countries', 'Indonesia') - ->orderBy('year') - ->orderBy('title', 'desc') - ->get(); - - return view('browse_movies', [ - 'movies' => $movies - ]); - } - } - - .. output:: - :language: none - :visible: false - - Title: Joni's Promise - Year: 2005 - Runtime: 83 - IMDB Rating: 7.6 - IMDB Votes: 702 - Plot: A film delivery man promises ... - - Title: Gie - Year: 2005 - Runtime: 147 - IMDB Rating: 7.5 - IMDB Votes: 470 - Plot: Soe Hok Gie is an activist who lived in the sixties ... - - Title: Requiem from Java - Year: 2006 - Runtime: 120 - IMDB Rating: 6.6 - IMDB Votes: 316 - Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) - are young married couple ... - - ... +In this guide, you can see code templates of common +methods that you can use to read data from MongoDB by using +{+odm-long+}. .. tip:: - To learn more about sorting, see the following resources: - - - :manual:`Natural order ` - in the {+server-docs-name+} glossary - - `Ordering, Grouping, Limit, and Offset `__ - in the Laravel documentation + To learn more about any of the methods included in this guide, + see the links provided in each section. -.. _laravel-retrieve-one: +Insert One +---------- -Return the First Result -~~~~~~~~~~~~~~~~~~~~~~~ +The following code shows how to insert a single document into a +collection: -To retrieve the first document that matches a set of criteria, use the ``where()`` method -followed by the ``first()`` method. - -Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique -value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to -the documents' natural order, or as they appear in the collection. - -This example queries for documents in which the value of the ``runtime`` field is -``30`` and returns the first matching document according to the value of the ``_id`` -field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-first - :end-before: end-first - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movie = Movie::where('runtime', 30) - ->orderBy('_id') - ->first(); - - return view('browse_movies', [ - 'movies' => $movie - ]); - } - } - - .. 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 the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. +.. code-block:: php + + SampleModel::create([ + '' => '', + '' => '', + ... + ]); + +To view a runnable example that inserts one document, see the +:ref:`laravel-insert-one-usage` usage example. + +To learn more about inserting documents, see the +:ref:`laravel-fundamentals-write-insert` guide. diff --git a/docs/fundamentals/read-operations/modify-results.txt b/docs/fundamentals/read-operations/modify-results.txt new file mode 100644 index 000000000..2a76609ee --- /dev/null +++ b/docs/fundamentals/read-operations/modify-results.txt @@ -0,0 +1,300 @@ +.. _laravel-modify-find: +.. _laravel-read-modify-results: + +==================== +Modify Query Results +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to customize the way that {+odm-long+} +returns results from queries. You can modify the results of a find +operation by chaining more methods to the ``where()`` method. + +The following sections demonstrate how to modify the behavior of the +``where()`` method: + +- :ref:`laravel-skip-limit` uses the ``skip()`` method to set the number of documents + to skip and the ``take()`` method to set the total number of documents to return +- :ref:`laravel-sort` uses the ``orderBy()`` method to return query + results in a specified order based on field values +- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document + that matches the query filter + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-skip-limit: + +Skip and Limit Results +---------------------- + +This 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. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-skip-limit + :end-before: end-skip-limit + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 1999) + ->skip(2) + ->take(3) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. 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 besieged land, Beowulf must + battle against the hideous creature Grendel and his vengeance seeking mother. + +.. _laravel-sort: + +Sort Query Results +------------------ + +To order query results based on the values of specified fields, use the ``where()`` method +followed by the ``orderBy()`` method. + +You can set an **ascending** or **descending** sort direction on +results. By default, the ``orderBy()`` method sets an ascending sort on +the supplied field name, but you can explicitly specify an ascending +sort by passing ``"asc"`` as the second parameter. To +specify a descending sort, pass ``"desc"`` as the second parameter. + +If your documents contain duplicate values in a specific field, you can +handle the tie by specifying more fields to sort on. This ensures consistent +results if the other fields contain unique values. + +This example queries for documents in which the value of the ``countries`` field contains +``"Indonesia"`` and orders results first by an ascending sort on the +``year`` field, then a descending sort on the ``title`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-sort + :end-before: end-sort + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('countries', 'Indonesia') + ->orderBy('year') + ->orderBy('title', 'desc') + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Joni's Promise + Year: 2005 + Runtime: 83 + IMDB Rating: 7.6 + IMDB Votes: 702 + Plot: A film delivery man promises ... + + Title: Gie + Year: 2005 + Runtime: 147 + IMDB Rating: 7.5 + IMDB Votes: 470 + Plot: Soe Hok Gie is an activist who lived in the sixties ... + + Title: Requiem from Java + Year: 2006 + Runtime: 120 + IMDB Rating: 6.6 + IMDB Votes: 316 + Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi) + are young married couple ... + + ... + +.. tip:: + + To learn more about sorting, see the following resources: + + - :manual:`Natural order ` + in the {+server-docs-name+} glossary + - `Ordering, Grouping, Limit, and Offset `__ + in the Laravel documentation + +.. _laravel-retrieve-one: + +Return the First Result +----------------------- + +To retrieve the first document that matches a set of criteria, use the ``where()`` method +followed by the ``first()`` method. + +Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique +value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to +the documents' natural order, or as they appear in the collection. + +This example queries for documents in which the value of the ``runtime`` field is +``30`` and returns the first matching document according to the value of the ``_id`` +field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-first + :end-before: end-first + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movie = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + return view('browse_movies', [ + 'movies' => $movie + ]); + } + } + + .. 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 the ``orderBy()`` method, see the + :ref:`laravel-sort` section of this guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/fundamentals/read-operations/retrieve.txt b/docs/fundamentals/read-operations/retrieve.txt new file mode 100644 index 000000000..eb6006a88 --- /dev/null +++ b/docs/fundamentals/read-operations/retrieve.txt @@ -0,0 +1,223 @@ +.. _laravel-fundamentals-retrieve-documents: +.. _laravel-fundamentals-read-retrieve: + +============= +Retrieve Data +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, criteria, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to retrieve data from MongoDB +collections by using {+odm-long+}. This guide describes the Eloquent +model methods that you can use to retrieve data and provides examples +of different types of find operations. + +To learn more about Eloquent models in the {+odm-short+}, see the +:ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +.. _laravel-retrieve-matching: + +Retrieve Documents that Match a Query +------------------------------------- + +You can use Laravel's Eloquent object-relational mapper (ORM) to create models +that represent MongoDB collections and chain methods on them to specify +query criteria. + +To retrieve documents that match a set of criteria, call the ``where()`` +method on the collection's corresponding Eloquent model, then pass a query +filter to the method. + +A query filter specifies field value requirements and instructs the find +operation to return only documents that meet these requirements. + +You can use one of the following ``where()`` method calls to build a query: + +- ``where('', )`` builds a query that matches documents in + which the target field has the exact specified value + +- ``where('', '', )`` builds a query + that matches documents in which the target field's value meets the comparison + criteria + +To apply multiple sets of criteria to the find operation, you can chain a series +of ``where()`` methods together. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +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`` + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-query + :end-before: end-query + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('year', 2010) + ->where('imdb.rating', '>', 8.5) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. 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. + +To learn how to query by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder` page. + +Match Array Field Elements +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a query filter to match array field elements when +retrieving documents. If your documents contain an array field, you can +match documents based on if the value contains all or some specified +array elements. + +You can use one of the following ``where()`` method calls to build a +query on an array field: + +- ``where('', )`` builds a query that matches documents in + which the array field value is exactly the specified array + +- ``where('', 'in', )`` builds a query + that matches documents in which the array field value contains one or + more of the specified array elements + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +Select from the following :guilabel:`Exact Array Match` and +:guilabel:`Element Match` tabs to view the query syntax for each pattern: + +.. tabs:: + + .. tab:: Exact Array Match + :tabid: exact-array + + This example retrieves documents in which the ``countries`` array is + exactly ``['Indonesia', 'Canada']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-exact-array + :end-before: end-exact-array + + .. tab:: Element Match + :tabid: element-match + + This example retrieves documents in which the ``countries`` array + contains one of the values in the array ``['Canada', 'Egypt']``: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-elem-match + :end-before: end-elem-match + +To learn how to query array fields by using the Laravel query builder instead of the +Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in +the Query Builder guide. + +.. _laravel-retrieve-all: + +Retrieve All Documents in a Collection +-------------------------------------- + +You can retrieve all documents in a collection by omitting the query filter. +To return the 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. + +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. + + To avoid this issue, specify a document limit by using the ``take()`` method. For + more information about ``take()``, see the :ref:`laravel-modify-find` + section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to insert data into MongoDB, see the +:ref:`laravel-fundamentals-write-ops` guide. diff --git a/docs/fundamentals/read-operations/search-text.txt b/docs/fundamentals/read-operations/search-text.txt new file mode 100644 index 000000000..4b465e737 --- /dev/null +++ b/docs/fundamentals/read-operations/search-text.txt @@ -0,0 +1,157 @@ +.. _laravel-fundamentals-search-text: +.. _laravel-retrieve-text-search: + +=========== +Search Text +=========== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: filter, string, CRUD, code example + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to run a **text search** by using +{+odm-long+}. + +You can use a text search to retrieve documents that contain a term or a +phrase in a specified field. A term is a sequence of characters that +excludes whitespace characters. A phrase is a sequence of terms with any +number of whitespace characters. + +This guide describes the Eloquent model methods that you can use to +search text and provides examples. To learn more about Eloquent models +in the {+odm-short+}, see the :ref:`laravel-eloquent-models` section. + +.. include:: /includes/fundamentals/read-operations/before-you-get-started.rst + +Search Text Fields +------------------ + +Before you can perform a text search, you must create a :manual:`text +index ` on +the text-valued field. To learn more about creating +indexes, see the :ref:`laravel-eloquent-indexes` section of the +Schema Builder guide. + +You can perform a text search by using the :manual:`$text +` operator followed +by the ``$search`` field in your query filter that you pass to the +``where()`` method. The ``$text`` operator performs a text search on the +text-indexed fields. The ``$search`` field specifies the text to search for. + +After building your query by using the ``where()`` method, chain the ``get()`` +method to retrieve the query results. + +This example calls the ``where()`` method on the ``Movie`` Eloquent model to +retrieve documents in which the ``plot`` field contains the phrase +``"love story"``. To perform this text search, the collection must have +a text index on the ``plot`` field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text + :end-before: end-text + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movies = Movie::where('$text', ['$search' => '"love story"']) + ->get(); + + return view('browse_movies', [ + 'movies' => $movies + ]); + } + } + + .. output:: + :language: none + :visible: false + + Title: Cafè de Flore + Year: 2011 + Runtime: 120 + IMDB Rating: 7.4 + IMDB Votes: 9663 + Plot: A love story between a man and woman ... + + Title: Paheli + Year: 2005 + Runtime: 140 + IMDB Rating: 6.7 + IMDB Votes: 8909 + Plot: A folk tale - supernatural love story about a ghost ... + + Title: Por un puèado de besos + Year: 2014 + Runtime: 98 + IMDB Rating: 6.1 + IMDB Votes: 223 + Plot: A girl. A boy. A love story ... + + ... + +Search Score +------------ + +A text search assigns a numerical :manual:`text score ` to indicate how closely +each result matches the string in your query filter. You can sort the +results by relevance by using the ``orderBy()`` method to sort on the +``textScore`` metadata field. You can access this metadata by using the +:manual:`$meta ` operator: + +.. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-text-relevance + :end-before: end-text-relevance + :emphasize-lines: 2 + +.. tip:: + + To learn more about the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Output guide. + +Additional Information +---------------------- + +To view runnable code examples that demonstrate how to perform find +operations by using the {+odm-short+}, see the following usage examples: + +- :ref:`laravel-find-one-usage` +- :ref:`laravel-find-usage` + +To learn how to retrieve data based on filter criteria, see the +:ref:`laravel-fundamentals-read-retrieve` guide. diff --git a/docs/includes/fundamentals/read-operations/before-you-get-started.rst b/docs/includes/fundamentals/read-operations/before-you-get-started.rst new file mode 100644 index 000000000..9555856fc --- /dev/null +++ b/docs/includes/fundamentals/read-operations/before-you-get-started.rst @@ -0,0 +1,15 @@ +Before You Get Started +---------------------- + +To run the code examples in this guide, complete the :ref:`Quick Start ` +tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with +sample data and creating the following files in your Laravel web application: + +- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` + collection +- ``MovieController.php`` file, which contains a ``show()`` function to run database operations +- ``browse_movies.blade.php`` file, which 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 find operation code examples and view the expected output. From d5bc8d4046ee7cf7fb06be7212383b0cc1178706 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Feb 2025 16:45:27 -0500 Subject: [PATCH 2/5] skip --- docs/fundamentals/read-operations.txt | 154 ++++++++++++++++-- .../fundamentals/read-operations/retrieve.txt | 10 ++ 2 files changed, 151 insertions(+), 13 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index a9f5447c6..ad0d36acf 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -36,22 +36,150 @@ methods that you can use to read data from MongoDB by using To learn more about any of the methods included in this guide, see the links provided in each section. -Insert One ----------- +Find One +-------- + +The following code shows how to retrieve the first matching document +from a collection: + +.. code-block:: php + + SampleModel::where('', ) + ->first(); + +To view a runnable example that finds one document, see the +:ref:`laravel-find-one-usage` usage example. + +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. + +To learn more about the ``first()`` method, see the +:ref:`laravel-fundamentals-read-retrieve` guide. + +Find Multiple +------------- + +The following code shows how to retrieve all documents that match a +query filter from a collection: + +.. code-block:: php + + SampleModel::where('', ) + ->get(); + +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. -The following code shows how to insert a single document into a +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. + +Return All Documents +-------------------- + +The following code shows how to retrieve all documents from a collection: .. code-block:: php - - SampleModel::create([ - '' => '', - '' => '', - ... - ]); -To view a runnable example that inserts one document, see the -:ref:`laravel-insert-one-usage` usage example. + SampleModel::get(); + + /* Or, use the all() method. */ + + SampleModel::all(); + +To view a runnable example that finds documents, see the +:ref:`laravel-find-usage` usage example. + +To learn more about retrieving documents, see the +:ref:`laravel-fundamentals-read-retrieve` guide. + +Search Text +----------- + +The following code shows how to perform a full-text search on a string +field in a collection's documents: + +.. code-block:: php + + SampleModel::where('$text', ['$search' => '']) + ->get(); + +To learn more about searching on text fields, see the +:ref:`laravel-retrieve-text-search` guide. + +Count Documents in a Collection +------------------------------- + +The following code shows how to count documents in a collection: + +.. code-block:: php + + SampleModel::count(); + + /* You can also count documents that match a filter. */ + + SampleModel::where('', '') + ->count(); + +To view a runnable example that counts documents, see the +:ref:`laravel-count-usage` usage example. + +Retrieve Distinct Values +------------------------ + +The following code shows how to retrieve the distinct values of a +specified field: + +.. code-block:: php + + SampleModel::select('') + ->distinct() + ->get(); + +To view a runnable example that returns distinct field values, see the +:ref:`laravel-distinct-usage` usage example. + +Skip Results +------------ + +The following code shows how to skip a specified number of documents +returned from MongoDB: + +.. code-block:: php + + SampleModel::where('', '') + ->skip() + ->get(); + +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. + +Limit Results +------------- + +The following code shows how to return only a specified number of +documents from MongoDB: + +.. code-block:: php + + SampleModel::where('', '') + ->take() + ->get(); + +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. + +Sort Results +------------ + +The following code shows how to set a sort order on results returned +from MongoDB: + +.. code-block:: php + +Movie::where('field name', '') + ->orderBy('') + ->get(); -To learn more about inserting documents, see the -:ref:`laravel-fundamentals-write-insert` guide. +To learn more about modifying how {+odm-long+} returns results, see the +:ref:`laravel-read-modify-results` guide. diff --git a/docs/fundamentals/read-operations/retrieve.txt b/docs/fundamentals/read-operations/retrieve.txt index eb6006a88..65478c8ef 100644 --- a/docs/fundamentals/read-operations/retrieve.txt +++ b/docs/fundamentals/read-operations/retrieve.txt @@ -44,6 +44,13 @@ To retrieve documents that match a set of criteria, call the ``where()`` method on the collection's corresponding Eloquent model, then pass a query filter to the method. +.. tip:: Retrieve One Document + + The ``where()`` method retrieves all matching documents. To retrieve + the first matching document, you can chain the ``first()`` method. To + learn more and view an example, see the :ref:`laravel-retrieve-one` + section of the Modify Query Results guide. + A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements. @@ -221,3 +228,6 @@ operations by using the {+odm-short+}, see the following usage examples: To learn how to insert data into MongoDB, see the :ref:`laravel-fundamentals-write-ops` guide. + +To learn how to modify the way that the {+odm-short+} returns results, +see the :ref:`laravel-read-modify-results` guide. From 08855cbf163f0c61cba7773448e00cc63d0f579a Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Feb 2025 16:53:40 -0500 Subject: [PATCH 3/5] small fixes --- docs/fundamentals/read-operations.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index ad0d36acf..a7f73945d 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -44,7 +44,7 @@ from a collection: .. code-block:: php - SampleModel::where('', ) + SampleModel::where('', '') ->first(); To view a runnable example that finds one document, see the @@ -64,7 +64,7 @@ query filter from a collection: .. code-block:: php - SampleModel::where('', ) + SampleModel::where('', '') ->get(); To view a runnable example that finds documents, see the @@ -107,8 +107,8 @@ field in a collection's documents: To learn more about searching on text fields, see the :ref:`laravel-retrieve-text-search` guide. -Count Documents in a Collection -------------------------------- +Count Documents +--------------- The following code shows how to count documents in a collection: @@ -177,9 +177,9 @@ from MongoDB: .. code-block:: php -Movie::where('field name', '') - ->orderBy('') - ->get(); + SampleModel::where('field name', '') + ->orderBy('') + ->get(); To learn more about modifying how {+odm-long+} returns results, see the :ref:`laravel-read-modify-results` guide. From 17ab049faa078ec9933fd300a05b8bcf34e45252 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 27 Feb 2025 16:56:51 -0500 Subject: [PATCH 4/5] small fixes --- docs/fundamentals/read-operations.txt | 6 ++---- docs/fundamentals/write-operations.txt | 3 +-- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index a7f73945d..558f35268 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -83,8 +83,7 @@ collection: SampleModel::get(); - /* Or, use the all() method. */ - + // Or, use the all() method. SampleModel::all(); To view a runnable example that finds documents, see the @@ -116,8 +115,7 @@ The following code shows how to count documents in a collection: SampleModel::count(); - /* You can also count documents that match a filter. */ - + // You can also count documents that match a filter. SampleModel::where('', '') ->count(); diff --git a/docs/fundamentals/write-operations.txt b/docs/fundamentals/write-operations.txt index 0a4d8a6ca..1b2f163be 100644 --- a/docs/fundamentals/write-operations.txt +++ b/docs/fundamentals/write-operations.txt @@ -133,8 +133,7 @@ matching document doesn't exist: ['upsert' => true], ); - /* Or, use the upsert() method. */ - + // Or, use the upsert() method. SampleModel::upsert( [], '', From 2c19a64ece1479dda1d40ac34defbdc593c40292 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 28 Feb 2025 10:30:56 -0500 Subject: [PATCH 5/5] fixes - RM and moved a section --- docs/fundamentals/read-operations.txt | 7 +- .../read-operations/modify-results.txt | 73 ------------------- .../fundamentals/read-operations/retrieve.txt | 73 ++++++++++++++++++- 3 files changed, 74 insertions(+), 79 deletions(-) diff --git a/docs/fundamentals/read-operations.txt b/docs/fundamentals/read-operations.txt index 558f35268..303e53a3e 100644 --- a/docs/fundamentals/read-operations.txt +++ b/docs/fundamentals/read-operations.txt @@ -50,11 +50,8 @@ from a collection: To view a runnable example that finds one document, see the :ref:`laravel-find-one-usage` usage example. -To learn more about retrieving documents, see the -:ref:`laravel-fundamentals-read-retrieve` guide. - -To learn more about the ``first()`` method, see the -:ref:`laravel-fundamentals-read-retrieve` guide. +To learn more about retrieving documents and the ``first()`` method, see +the :ref:`laravel-fundamentals-read-retrieve` guide. Find Multiple ------------- diff --git a/docs/fundamentals/read-operations/modify-results.txt b/docs/fundamentals/read-operations/modify-results.txt index 2a76609ee..fd67422ae 100644 --- a/docs/fundamentals/read-operations/modify-results.txt +++ b/docs/fundamentals/read-operations/modify-results.txt @@ -32,8 +32,6 @@ The following sections demonstrate how to modify the behavior of the to skip and the ``take()`` method to set the total number of documents to return - :ref:`laravel-sort` uses the ``orderBy()`` method to return query results in a specified order based on field values -- :ref:`laravel-retrieve-one` uses the ``first()`` method to return the first document - that matches the query filter To learn more about Eloquent models in the {+odm-short+}, see the :ref:`laravel-eloquent-models` section. @@ -216,77 +214,6 @@ This example queries for documents in which the value of the ``countries`` field - `Ordering, Grouping, Limit, and Offset `__ in the Laravel documentation -.. _laravel-retrieve-one: - -Return the First Result ------------------------ - -To retrieve the first document that matches a set of criteria, use the ``where()`` method -followed by the ``first()`` method. - -Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique -value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to -the documents' natural order, or as they appear in the collection. - -This example queries for documents in which the value of the ``runtime`` field is -``30`` and returns the first matching document according to the value of the ``_id`` -field. - -.. tabs:: - - .. tab:: Query Syntax - :tabid: query-syntax - - Use the following syntax to specify the query: - - .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php - :language: php - :dedent: - :start-after: start-first - :end-before: end-first - - .. tab:: Controller Method - :tabid: controller - - To see the query results in the ``browse_movies`` view, edit the ``show()`` function - in the ``MovieController.php`` file to resemble the following code: - - .. io-code-block:: - :copyable: true - - .. input:: - :language: php - - class MovieController - { - public function show() - { - $movie = Movie::where('runtime', 30) - ->orderBy('_id') - ->first(); - - return view('browse_movies', [ - 'movies' => $movie - ]); - } - } - - .. 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 the ``orderBy()`` method, see the - :ref:`laravel-sort` section of this guide. - Additional Information ---------------------- diff --git a/docs/fundamentals/read-operations/retrieve.txt b/docs/fundamentals/read-operations/retrieve.txt index 65478c8ef..a4ca31091 100644 --- a/docs/fundamentals/read-operations/retrieve.txt +++ b/docs/fundamentals/read-operations/retrieve.txt @@ -49,7 +49,7 @@ filter to the method. The ``where()`` method retrieves all matching documents. To retrieve the first matching document, you can chain the ``first()`` method. To learn more and view an example, see the :ref:`laravel-retrieve-one` - section of the Modify Query Results guide. + section of this guide. A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements. @@ -191,6 +191,77 @@ To learn how to query array fields by using the Laravel query builder instead of Eloquent ORM, see the :ref:`laravel-query-builder-elemMatch` section in the Query Builder guide. +.. _laravel-retrieve-one: + +Retrieve the First Result +------------------------- + +To retrieve the first document that matches a set of criteria, use the ``where()`` method +followed by the ``first()`` method. + +Chain the ``orderBy()`` method to ``first()`` to get consistent results when you query on a unique +value. If you omit the ``orderBy()`` method, MongoDB returns the matching documents according to +the documents' natural order, or as they appear in the collection. + +This example queries for documents in which the value of the ``runtime`` field is +``30`` and returns the first matching document according to the value of the ``_id`` +field. + +.. tabs:: + + .. tab:: Query Syntax + :tabid: query-syntax + + Use the following syntax to specify the query: + + .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php + :language: php + :dedent: + :start-after: start-first + :end-before: end-first + + .. tab:: Controller Method + :tabid: controller + + To see the query results in the ``browse_movies`` view, edit the ``show()`` function + in the ``MovieController.php`` file to resemble the following code: + + .. io-code-block:: + :copyable: true + + .. input:: + :language: php + + class MovieController + { + public function show() + { + $movie = Movie::where('runtime', 30) + ->orderBy('_id') + ->first(); + + return view('browse_movies', [ + 'movies' => $movie + ]); + } + } + + .. 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 the ``orderBy()`` method, see the + :ref:`laravel-sort` section of the Modify Query Results guide. + .. _laravel-retrieve-all: Retrieve All Documents in a Collection