DOCSP-35966 query builder #2790

ccho-mongodb · 2024-03-25T13:04:55Z

JIRA: https://jira.mongodb.org/browse/DOCSP-35966
Staging: https://preview-mongodbcchomongodb.gatsbyjs.io/laravel/DOCSP-35966-query-builder/query-builder/

Checklist

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

docs/includes/query-builder/MovieController.php

rustagir

Good work on this long page! Happy to discuss any of my comments

rustagir · 2024-03-25T17:49:15Z

docs/query-builder.txt

+lets you write queries for any supported database by using the same fluent
+interface and syntax.


Q: What does "same" mean in this context?

I think I had "a common" previously to represent the "fluent interface and syntax" which might be more clear than "the same". Let me know if one is more clear than the other, or how you might otherwise word it.

maybe you can just add "... the same ... as the Laravel query builder"?

Thanks for that perspective!

I wanted to describe the query builder rather than comparing it with something else, but it seems like using noun phrases (e.g. #2790 (comment)) can cause some confusion.
In this sentence, the items being compared are syntax you use to access each of the supported databases rather than something with the query builder (given it's describing the query builder).

I'll spend a few minutes to try to reorder the sentence in a way that avoids connecting noun phrases to restrictive clauses.

rustagir · 2024-03-25T17:50:47Z

docs/query-builder.txt

+lets you perform database operations. Facades are static interfaces to
+classes that make the syntax more concise, avoid runtime errors, and improve
+testability.


nit: ambiguous identifiers - do the classes made the syntax more concise, etc or the facades

rustagir · 2024-03-25T17:51:15Z

docs/query-builder.txt

-**Where**
+{+odm-short+} aliases the ``DB`` method ``table()`` as the ``collection()``
+method. Chain methods to specify the command and any constraints. Then, chain
+the ``get()`` method at the end to run them on the MongoDB collection. The


Suggested change

the ``get()`` method at the end to run them on the MongoDB collection. The

the ``get()`` method at the end to run the command on the MongoDB collection. The

Thanks for spotting this! I'll reword since "them" refers to the unspecified number of chained methods.

rustagir · 2024-03-25T17:51:47Z

docs/query-builder.txt

-       Post::where('votes', '>', 0)
-           ->orWhere('is_approved', true)
-           ->get();
+This guide shows examples of the following types of query builder operations:


Suggested change

This guide shows examples of the following types of query builder operations:

This guide provides examples for the following types of query builder operations:

I considered the suggestion while, but think that "for" might not be the correct preposition. I think "for" would imply that the examples are being delivered to someone or something. I'll use "provides" and pair it with "of".

docs/query-builder.txt

rustagir · 2024-03-25T19:25:05Z

docs/query-builder.txt

+The following example shows how to use the ``near`` query operator
+with the ``where()`` query builder method to match documents that contain the
+field ``random_review``:


I; description does not match

rustagir · 2024-03-25T19:25:42Z

docs/query-builder.txt


-**Push**
+MongoDB Write Operations
+------------------------



S: add introduction to section list

rustagir · 2024-03-25T19:26:12Z

docs/query-builder.txt


-If you **DON'T** want duplicate items, set the third parameter to ``true``:
+The following example shows how to use the ``increment()``
+query builder method to add "3000" to the value of


Suggested change

query builder method to add "3000" to the value of

query builder method to add ``3000`` to the value of

rustagir · 2024-03-25T19:26:47Z

docs/query-builder.txt

-           'message' => 'Hi John',
-       ]);
+The following example shows how to use the ``push()`` query builder method to
+add "``Gary Cole``" to the ``cast`` array field in the matched document:


Suggested change

add "``Gary Cole``" to the ``cast`` array field in the matched document:

add ``"Gary Cole"`` to the ``cast`` array field in the matched document:

rustagir · 2024-03-25T19:27:02Z

docs/query-builder.txt


-.. code-block:: php
+The following example shows how to use the ``pull()`` query builder method
+to remove the "``Adventure``" value from the ``genres`` field from the document


Suggested change

to remove the "``Adventure``" value from the ``genres`` field from the document

to remove the ``"Adventure"`` value from the ``genres`` field from the document

ccho-mongodb · 2024-03-26T06:21:15Z

@rustagir thanks for the review. I think I addressed everything and went through the content multiple times. I also moved all the code snippets to a new unit test file.

rustagir

lgtm with some small fixes

rustagir · 2024-03-26T17:45:36Z

docs/query-builder.txt

+- :ref:`laravel-retrieve-query-builder`
+- :ref:`laravel-modify-results-query-builder`
+- :ref:`laravel-mongodb-read-query-builder`
+- :ref:`laravel-mongodb-write-query-builder`


S: Make the titles of the subsections all in the same form (action oriented)

rustagir · 2024-03-26T17:47:18Z

docs/query-builder.txt

+The following example shows how to use the ``where()`` query
+builder method to retrieve documents from the ``movies`` collection
+that contain an ``imdb.votes`` field value of ``350``. Click the
+:guilabel:`{+code-output-label+}` button to see the results returned
+by the query:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/query-builder/QueryBuilderTest.php
+      :language: php
+      :dedent:
+      :start-after: begin query where
+      :end-before: end query where


I: description does not match example
imdb.votes field value of 350
where('imdb.rating', 9.3)

rustagir · 2024-03-26T17:47:59Z

docs/query-builder.txt

+The following example shows how to chain the ``orWhere()``
+query builder method to retrieve documents from the
+``movies`` collection that either match the ``year``
+value of ``1955`` or match the title ``"Back to the Future"``:


Suggested change

value of ``1955`` or match the title ``"Back to the Future"``:

value of ``1955`` or match the ``title`` value ``"Back to the Future"``:

rustagir · 2024-03-26T17:50:48Z

docs/query-builder.txt

+The following example shows how to use the ``whereIn()``
+query builder method to retrieve documents from the
+``movies`` collection that match at least one of the
+``title`` values in the specified set.


Suggested change

``title`` values in the specified set.

``title`` values in the specified set:

rustagir · 2024-03-26T17:50:59Z

docs/query-builder.txt

+The following example shows how to use the ``whereNull()``
+query builder method to retrieve documents from the
+``movies`` collection that omit a ``runtime`` value
+or field.


Suggested change

or field.

or field:

rustagir · 2024-03-26T17:52:10Z

docs/query-builder.txt

+wildcard characters:
+
+- ``%`` which matches zero or more characters
+- ``_`` which matches a single character


Q: if the _ matches a single character, why is Spider Woman in the results?

Q: if the _ matches a single character, why is Spider Woman in the results?

Good question -- whitespace is a character in the context of SQL queries. The Laravel documentation omits any explanation of the wildcard characters that they use, but I thought it would be good to reiterate the SQL LIKE syntax.
Let me know if you think this needs further explanation.

rustagir · 2024-03-26T17:58:16Z

docs/query-builder.txt

+The following example shows how to pass the ``mod``
+query operator with the ``where()`` query builder
+method to match documents by using the expression
+``"year % 2 == 0"``, which matches even values for


S: remove quotes from the expression

Suggested change

``"year % 2 == 0"``, which matches even values for

``year % 2 == 0``, which matches even values for

GromNaN

I updated the tests to add assertions, using a subset of the data.

GromNaN · 2024-04-04T14:53:24Z

docs/query-builder.txt

+The following example shows how to use the ``near`` query operator
+with the ``where()`` query builder method to match documents that
+contain a location that is up to ``50`` meters from a GeoJSON Point
+object:


This should tell how to create a geo index.

Will do -- I can link to the Schema Builder section "Create a Geospatial Index". However, I'll need to merge in the 4.1 branch to get that content. Is that ok or should I create a separate ticket to address this?

docs/includes/query-builder/QueryBuilderTest.php

Chris Cho added 26 commits March 15, 2024 13:42

DOCSP-35966: Query builder standardization

8799f74

WIP

3f41921

wip

c90150a

WIP

e386f25

WIP

2007356

fix RST

1de9614

fix RST

3c658c3

WIP

c886c36

WIP

2ab0c46

fix

ea3dd8e

wip

1e0ce7f

wip

7f9c68f

WIP

64e321b

WIP

d34a04d

WIP

41cff58

fix indent

0a8db8c

fix RST

b334cfa

format code

d95620e

reformat code

e2f34d6

WIP

3775d5a

elemmatch update

1308927

fixes

94b00d6

WIP

41efa9b

capitalize

619b7b0

single quotes

06efb4c

standardize value formatting, fix link

b901c86

GromNaN reviewed Mar 25, 2024

View reviewed changes

docs/includes/query-builder/MovieController.php Outdated Show resolved Hide resolved

GromNaN added the docs label Mar 25, 2024

GromNaN changed the base branch from 4.1 to docs-rewrite March 25, 2024 16:25

GromNaN changed the base branch from docs-rewrite to 4.1 March 25, 2024 16:58

rustagir requested changes Mar 25, 2024

View reviewed changes

Chris Cho added 5 commits March 25, 2024 23:20

PRR fixes

8bfe031

tweaks

31cdfae

use unit test file

91525b2

reorder

131c65e

fixes

c69dded

ccho-mongodb requested a review from rustagir March 26, 2024 06:19

rustagir approved these changes Mar 26, 2024

View reviewed changes

Chris Cho added 2 commits March 26, 2024 15:32

PRR fixes

649e879

PRR fix 2

d79f852

ccho-mongodb marked this pull request as ready for review March 26, 2024 19:42

ccho-mongodb requested a review from a team as a code owner March 26, 2024 19:42

ccho-mongodb requested a review from GromNaN March 26, 2024 19:42

grammar fix

8a50517

caitlindavey requested a review from rustagir April 1, 2024 18:46

Update tests with data

e3708ff

GromNaN reviewed Apr 5, 2024

View reviewed changes

Merge branch '4.1' into DOCSP-35966-query-builder

c908bd6

GromNaN approved these changes Apr 5, 2024

View reviewed changes

add link to schema builder for info on creating geospatial indexes

0a1fc68

ccho-mongodb merged commit 2b0b5e6 into mongodb:4.1 Apr 8, 2024

ccho-mongodb deleted the DOCSP-35966-query-builder branch April 8, 2024 13:45

This was referenced Apr 8, 2024

Merge 4.1 into 4.2 #2831

Merged

Merge 4.2 into 4.3 #2832

Closed

Merge 4.2 into 4.3 #2835

Merged

		lets you write queries for any supported database by using the same fluent
		interface and syntax.

	the ``get()`` method at the end to run them on the MongoDB collection. The
	the ``get()`` method at the end to run the command on the MongoDB collection. The

	This guide shows examples of the following types of query builder operations:
	This guide provides examples for the following types of query builder operations:

	query builder method to add "3000" to the value of
	query builder method to add ``3000`` to the value of

	add "``Gary Cole``" to the ``cast`` array field in the matched document:
	add ``"Gary Cole"`` to the ``cast`` array field in the matched document:

	to remove the "``Adventure``" value from the ``genres`` field from the document
	to remove the ``"Adventure"`` value from the ``genres`` field from the document

	value of ``1955`` or match the title ``"Back to the Future"``:
	value of ``1955`` or match the ``title`` value ``"Back to the Future"``:

	``title`` values in the specified set.
	``title`` values in the specified set:

	``"year % 2 == 0"``, which matches even values for
	``year % 2 == 0``, which matches even values for

DOCSP-35966 query builder #2790

DOCSP-35966 query builder #2790

Uh oh!

Conversation

ccho-mongodb commented Mar 25, 2024

Checklist

Uh oh!

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!

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!

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 commented Mar 26, 2024

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!

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!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ccho-mongodb Apr 5, 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!

Uh oh!

Uh oh!

ccho-mongodb Apr 5, 2024 •

edited

Loading