DOCSP-35957: Retrieve guide #2722

norareidy · 2024-02-05T22:19:05Z

Adds a find operations page to the docs.

JIRA: https://jira.mongodb.org/browse/DOCSP-35957
Staging: https://preview-mongodbnorareidy.gatsbyjs.io/laravel/DOCSP-35957/retrieve/

Checklist

Add tests and ensure they pass
Add an entry to the CHANGELOG.md file
Update documentation for new features

rustagir

a few small things + questions

rustagir · 2024-02-06T15:01:50Z

docs/retrieve.txt

+--------
+
+In this guide, you can learn how to retrieve data from your MongoDB
+collections using **find operations**. Find operations are commands that


Suggested change

collections using **find operations**. Find operations are commands that

collections by using **find operations**. Find operations are commands that

rustagir · 2024-02-06T15:03:25Z

docs/retrieve.txt

+Pass the field name and value for which you are querying as parameters to ``where()``.
+
+You can also pass a comparison operator as the ``where()`` method's second parameter,
+such as the ``>`` operator. If you do not include a comparison operator parameter,


S: explain what > does

Suggested change

such as the ``>`` operator. If you do not include a comparison operator parameter,

such as the ``>`` operator to perform a "greater than" comparison. If you do not include a comparison operator parameter,

rustagir · 2024-02-06T15:07:11Z

docs/retrieve.txt

+   .. input::
+      :language: php
+
+      $movies = Movie::all();


Q: does this code example also print the retrieved documents?

The code snippet itself doesn't, but editing the view class according to the Quick Start instructions outputs the results in the format shown

rustagir · 2024-02-06T15:07:46Z

docs/retrieve.txt

+      $movies =
+         Movie::where('year', 2010)
+            ->where('imdb.rating', '>', 8.5)
+            ->get();


Q: same question here - does this code actually print the results?

rustagir · 2024-02-06T15:11:02Z

docs/retrieve.txt

+The following example returns one document in which the value of the ``title`` field
+is ``"The Parent Trap"``:


S: could you use an example here for a query that would definitely match more than one document to show that the method matches only the first one?

I used "The Parent Trap" because there are two versions (the original and the remake) and two matching documents - would it be better to have a query that's even more broad / matches more documents?

I think a query filter such as "year == 1961" or "runtime == 30" could provide a stronger hint that there's more than one result (without risk of causing an overload of results since the limit function hasn't been introduced).

ccho-mongodb · 2024-02-06T18:10:00Z

docs/retrieve.txt

+- Controller class to store and run the find operations
+- View class to display the results of the find operations
+
+For instructions on creating these classes, see the Quick Start.


Suggestion:
I think it would be good to add explanations or links to instructions on how to edit the files and view the results. I think the instructions could eventually be moved to a "Fundamentals" landing page. Happy to help with the content for this.

ccho-mongodb · 2024-02-06T18:21:23Z

docs/retrieve.txt

+To retrieve one document that matches a set of criteria, use the ``where()`` method
+followed by the ``first()`` method. 
+
+For more information about the ``where()`` method and its parameters, see the
+:ref:`laravel-find-all` section of this guide.


Suggestion:
I think it would be helpful to mention sorting, even if showing how to sort is not shown on this page so that the reader can understand, from a set of results, which document to expect as the "first".

ccho-mongodb · 2024-02-06T18:26:40Z

docs/retrieve.txt

+Find All Documents
+------------------
+
+To retrieve all documents in a collection, use the ``all()`` method.


Issue:

I think "use the ___ method" might not be clear as to what you're calling it on.

Suggestion:
I think it could be helpful to make the following changes:

Describe connection between "MongoDB collection" and "Laravel Model" in the Overview section.

Provide specifics on what the user should call the "all()" method on.

ccho-mongodb · 2024-02-06T18:32:13Z

docs/retrieve.txt

+   .. input::
+      :language: php
+
+      $movies = Movie::all();


Issue:
This relates to both "Find All Documents in a Collection Example" and "Find All Matching Documents Example".

I ran an issue retrieving large result sets in the Quick Start because the movies collection is large and the web app will time out trying to retrieve them. If it was able to retrieve them, displaying them on a webpage would probably cause memory issues for the browser.

Suggestion:
I think omitting the example could prevent users from running into the same issue. Instead of showing the example, describe the syntax of the method and alias and what it would do.

Instead of showing output, I think it would be better just to show the syntax of how to provide an empty filter (Movie::get()), which would help them understand how to chain other modifiers, and its alias (Movie::all()). Rather than showing the result sets, it would be helpful to add an admonition mentioning that sample sets such as the movies collection would be too large.

rustagir

a few things!

rustagir · 2024-02-08T16:13:52Z

docs/retrieve.txt

+In this guide, you can learn how to retrieve data from your MongoDB
+collections by using **find operations**. Find operations are commands that
+retrieve documents from the server.


S: these sentences kind of go in circles. The first sentence says that you you can retrieve data by using find operations -> find operations retrieve data. I noticed this is the wording used on our other pages too.. I think you can use the phrase "find operations" first.

What about something like:

Suggested change

In this guide, you can learn how to retrieve data from your MongoDB

collections by using **find operations**. Find operations are commands that

retrieve documents from the server.

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.

rustagir · 2024-02-08T16:14:53Z

docs/retrieve.txt

+- :ref:`laravel-retrieve-setup`
+- :ref:`laravel-retrieve-matching`
+- :ref:`laravel-modify-find`
+- :ref:`laravel-addtl-info`


S: add some description to these sections like here

docs/retrieve.txt

rustagir · 2024-02-08T16:29:59Z

docs/retrieve.txt

+.. warning::
+
+   The ``movies`` collection in the Atlas sample dataset stores a large amount of data.
+   Retrieving and displaying all documents in this collection may cause your web 
+   application to time out.


Suggested change

.. warning::

The ``movies`` collection in the Atlas sample dataset stores a large amount of data.

Retrieving and displaying all documents in this collection may cause your web

application to time out.

.. warning::

The ``movies`` collection in the Atlas sample dataset stores a large amount of data.

Retrieving and displaying all documents in this collection might cause your web

application to time out.

rustagir · 2024-02-08T16:30:48Z

docs/retrieve.txt

+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


S: move into tip at the end of this section

rustagir · 2024-02-08T16:30:57Z

docs/retrieve.txt

+The following example returns one document in which the value of the ``title`` field
+is ``"The Parent Trap"``:


rustagir · 2024-02-08T16:31:16Z

docs/retrieve.txt

+.. important:: Required File Changes
+
+   To run the preceding code example, you must edit the ``MovieController.php`` file in your
+   ``my-app`` application. Copy the code example and paste it into the ``show()`` function, replacing
+   any existing code inside this function.


S: similar to earlier comment, move up

rustagir · 2024-02-08T16:45:35Z

docs/retrieve.txt

+Use Laravel Queries to Retrieve Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rather than on a model, you can run find operations on a query builder instance that


S: the first clause is a bit confusing

Suggested change

Rather than on a model, you can run find operations on a query builder instance that

You can run find operations on a query builder instance that represents your collection instead of running them on models.

ccho-mongodb

Thanks for picking up this prototype page. After going through the staged content, I think the information could be easier to find with descriptive headings that don't overlap and separating out "how to run this" the into tabs.

I think the introductory sentences in each section could guide the readers better if they followed a consistent structure. Let me know if the suggestions I provided make sense.

Finally, while I didn't leave any other comments on this, I think any resource/link mentioned must be accompanied by information that connects it to what the reader should learn, especially when the content of the linked page doesn't provide that specific guidance.

Let me know if you want to pair on changes!

docs/index.txt

docs/retrieve.txt

GromNaN · 2024-02-14T16:14:32Z

docs/retrieve.txt

+
+You can pass the following types of query filters to the ``where()`` method:
+
+- ``where('<field name>', <value>)``: instructs MongoDB to return documents that match


I find it more explicit if the context of the function is provided. Otherwise they can think the function where is global.

Suggested change

- ``where('<field name>', <value>)``: instructs MongoDB to return documents that match

- ``Model::where('<field name>', <value>)``: instructs MongoDB to return documents that match

docs/retrieve.txt

ccho-mongodb

Looks pretty good, thanks for making all the changes! Most of the suggestions are straightforward, but let me know if there's anything you'd like to discuss and/or whether you want another review.

ccho-mongodb · 2024-02-26T22:23:33Z

docs/retrieve.txt

+Overview
+--------
+
+In this guide, you can learn how to use the Laravel package to perform **find operations**


Suggestion:

I think "Laravel MongoDB" (the odm-short source constant) could be more consistent with the product name:

Suggested change

In this guide, you can learn how to use the Laravel package to perform **find operations**

In this guide, you can learn how to use the {+odm-short+} to perform **find operations**

ccho-mongodb · 2024-02-26T23:15:23Z

docs/retrieve.txt

+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


Suggestion:

I think the "Prerequisites" heading should describe a condition/state rather than provide instructions. One potential solution could be to replace the heading title with "Before You Get Started" and explain the following similar to this:

"To run the code in this guide, you need to complete the Quick Start tutorial, which includes setting up a MongoDB Atlas instance with sample data and the following files in your Laravel web application:

Movie.php, which contains the Movie model that ...
"

docs/retrieve.txt

ccho-mongodb · 2024-02-27T00:32:22Z

docs/retrieve.txt

+
+      Use the following syntax to specify the query:
+
+      .. code-block:: go


Issue:

I think "go" syntax highlighting might be compatible in this case, but it would be better to identify this as php code.

Suggestion:

I think using "php" would be more consistent.

Applies to all instances.

oops didn't notice that - fixed!

ccho-mongodb · 2024-02-27T00:53:58Z

docs/retrieve.txt

+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:


Suggestion:

I think the description of the "types" in "types of query filters" is missing from the list items. I think describing the list items directly like the following would help guide the reader:

"You can use one of the following "where()" method calls to build a query:"

ccho-mongodb · 2024-02-27T01:41:47Z

docs/retrieve.txt

+
+.. _laravel-retrieve-one:
+
+Retrieve Only One Result


Suggestion:

I think "Return the First Result" could be more descriptive since the section doesn't describe how to retrieve any other type of a single result (such as the last result).

Applies to the description contained in this section.

ccho-mongodb · 2024-02-27T01:46:06Z

docs/retrieve.txt

+- ``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
+


Suggestion:
I think the subheadings could be introduced, e.g.
"The following sections show examples of how to use these methods."

ccho-mongodb · 2024-02-27T01:59:03Z

docs/retrieve.txt

+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. 


Suggestion:

I think it would be better to recommend a consistent sort order before describing natural ordering.

E.g. "Use the sort() method when you use the first() to get consistent results when you query on a unique value. If you omit the sort() method, MongoDB returns the matching documents according to the documents' natural order."

ccho-mongodb · 2024-02-27T02:04:14Z

docs/retrieve.txt

+
+      Then, make the following changes to your Laravel Quick Start application:
+
+      - Add the ``use Illuminate\Support\Facades\DB`` use statement to your ``MovieController.php``


Suggestion:

I think it could be good to match this with the other mention of this import in the section description since both versions of the example use it. The other instance currently reads:
"import the DB facade into your controller file"

ccho-mongodb · 2024-02-27T02:25:25Z

docs/retrieve.txt

+
+        .. note::
+
+           This change is necessary because you cannot use the ``->`` object operator to access document fields when running


Suggestion:

I think it could be better if the admonition identified which change it refers to.
E.g.

"Since the Laravel query builder returns ... the view accesses the fields by using the ... syntax instead of the "->" object operator."

rustagir

some small suggestions but LGTM! great work on this long PR!

rustagir · 2024-02-28T22:02:27Z

docs/retrieve.txt

+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 the ``movies`` collection


Suggested change

- ``Movie.php`` file, which contains a ``Movie`` model to represent the ``movies`` collection

- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` collection

rustagir · 2024-02-28T22:02:48Z

docs/retrieve.txt

+  operations
+
+The following sections describe how to edit the files in your Laravel application to run 
+the code examples and view the expected output.


Suggested change

the code examples and view the expected output.

the find operation code examples and view the expected output.

rustagir · 2024-02-28T22:05:49Z

docs/retrieve.txt

+
+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 database.


Suggested change

the documents' natural order, or as they appear in the database.

the documents' natural order, or as they appear in the collection.

rustagir · 2024-02-28T22:06:10Z

docs/retrieve.txt

+This example returns one document in which the value of the ``runtime`` field
+is ``30``.


S: also describe that this code orders by _id

…-guide

GromNaN

LGTM after a small fix

GromNaN · 2024-02-29T20:50:29Z

docs/retrieve.txt

+
+      Use the following syntax to specify the query:
+
+      .. code-block:: go


Suggested change

.. code-block:: go

.. code-block:: php

GromNaN · 2024-03-01T11:41:38Z

Thank you @norareidy

DOCSP-35957: Retrieve guide

9b1df2d

rustagir requested changes Feb 6, 2024

View reviewed changes

ccho-mongodb reviewed Feb 6, 2024

View reviewed changes

norareidy added 2 commits February 8, 2024 09:32

restructuring, adding info

c97f21f

small edits

14c0c2b

norareidy requested a review from rustagir February 8, 2024 14:57

rewording, typo

6e9a209

rustagir requested changes Feb 8, 2024

View reviewed changes

ccho-mongodb suggested changes Feb 8, 2024

View reviewed changes

norareidy added 5 commits February 9, 2024 11:18

merge

46fe25d

most of feedback

a4d79c3

feedback + edits

688c7e1

rewording

9a829ab

change section heading

10db9aa

GromNaN added the docs label Feb 13, 2024

GromNaN reviewed Feb 14, 2024

View reviewed changes

norareidy added 10 commits February 14, 2024 13:17

JT feedback

49ccc50

removing files

fdbedbd

wording change

bd92072

code ex with tabs

610cbaa

remove emphasis

62efd33

updating code to tabs

198800f

formatting issues

919211b

wording changes

480d8da

fixes

87d39da

fixing code example

55bf59e

ccho-mongodb approved these changes Feb 27, 2024

View reviewed changes

norareidy added 3 commits February 28, 2024 13:55

CC feedback

a85dece

TOC order

b603b90

typo

278ad21

rustagir approved these changes Feb 28, 2024

View reviewed changes

RR last feedback

815a8b5

norareidy marked this pull request as ready for review February 29, 2024 15:51

norareidy requested a review from a team as a code owner February 29, 2024 15:51

norareidy requested review from GromNaN and removed request for a team February 29, 2024 15:51

Merge remote-tracking branch 'upstream/4.1' into DOCSP-35957-retrieve…

dc47c6e

…-guide

GromNaN approved these changes Feb 29, 2024

View reviewed changes

norareidy added 2 commits February 29, 2024 16:14

code spacing

24ae7f8

missing colon

4e37a78

GromNaN merged commit 2829bbc into mongodb:4.1 Mar 1, 2024

GromNaN mentioned this pull request Mar 1, 2024

Merge 4.1 into 4.2 #2740

Merged

	collections using find operations. Find operations are commands that
	collections by using find operations. Find operations are commands that

	such as the ``>`` operator. If you do not include a comparison operator parameter,
	such as the ``>`` operator to perform a "greater than" comparison. If you do not include a comparison operator parameter,

		The following example returns one document in which the value of the ``title`` field
		is ``"The Parent Trap"``:

	Rather than on a model, you can run find operations on a query builder instance that
	You can run find operations on a query builder instance that represents your collection instead of running them on models.


		You can pass the following types of query filters to the ``where()`` method:

		- ``where('<field name>', <value>)``: instructs MongoDB to return documents that match

	- ``where('<field name>', <value>)``: instructs MongoDB to return documents that match
	- ``Model::where('<field name>', <value>)``: instructs MongoDB to return documents that match

	In this guide, you can learn how to use the Laravel package to perform find operations
	In this guide, you can learn how to use the {+odm-short+} to perform find operations


		Use the following syntax to specify the query:

		.. code-block:: go


		Then, make the following changes to your Laravel Quick Start application:

		- Add the ``use Illuminate\Support\Facades\DB`` use statement to your ``MovieController.php``


		.. note::

		This change is necessary because you cannot use the ``->`` object operator to access document fields when running

	- ``Movie.php`` file, which contains a ``Movie`` model to represent the ``movies`` collection
	- ``Movie.php`` file, which contains a ``Movie`` model to represent documents in the ``movies`` collection

	the code examples and view the expected output.
	the find operation code examples and view the expected output.

	the documents' natural order, or as they appear in the database.
	the documents' natural order, or as they appear in the collection.

		This example returns one document in which the value of the ``runtime`` field
		is ``30``.

DOCSP-35957: Retrieve guide #2722

DOCSP-35957: Retrieve guide #2722

Uh oh!

Conversation

norareidy commented Feb 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

norareidy Feb 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

norareidy Feb 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

norareidy commented Feb 5, 2024 •

edited

Loading

norareidy Feb 6, 2024 •

edited

Loading

norareidy Feb 6, 2024 •

edited

Loading