Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

DOCSP-35966 query builder #2790

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ccho-mongodb merged 37 commits into mongodb:4.1 from ccho-mongodb:DOCSP-35966-query-builder
Apr 8, 2024

Conversation

@ccho-mongodb
Copy link
Contributor

@ccho-mongodb ccho-mongodb commented Mar 25, 2024

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

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

@rustagir rustagir left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines 25 to 26
lets you write queries for any supported database by using the same fluent
interface and syntax.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Mar 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Mar 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines 35 to 37
lets you perform database operations. Facades are static interfaces to
classes that make the syntax more concise, avoid runtime errors, and improve
testability.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
**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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Mar 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Mar 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

rustagir reacted with thumbs up emoji
Comment on lines 935 to 937
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``:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I; description does not match

ccho-mongodb reacted with thumbs up emoji
**Push**
MongoDB Write Operations
------------------------

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: add introduction to section list

ccho-mongodb reacted with thumbs up emoji

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

'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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

ccho-mongodb reacted with thumbs up emoji

.. 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 reacted with thumbs up emoji
Copy link
Contributor Author

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

Copy link
Contributor

@rustagir rustagir left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm with some small fixes

Comment on lines +52 to +55
- :ref:`laravel-retrieve-query-builder`
- :ref:`laravel-modify-results-query-builder`
- :ref:`laravel-mongodb-read-query-builder`
- :ref:`laravel-mongodb-write-query-builder`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
Comment on lines 88 to 101
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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
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"``:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"``:

ccho-mongodb reacted with thumbs up emoji
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
or field.
or field:

ccho-mongodb reacted with thumbs up emoji
wildcard characters:

- ``%`` which matches zero or more characters
- ``_`` which matches a single character
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Mar 26, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: remove quotes from the expression

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

ccho-mongodb reacted with thumbs up emoji
@ccho-mongodb ccho-mongodb marked this pull request as ready for review March 26, 2024 19:42
@ccho-mongodb ccho-mongodb requested a review from a team as a code owner March 26, 2024 19:42
Copy link
Member

@GromNaN GromNaN left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

ccho-mongodb reacted with thumbs up emoji
Comment on lines +935 to +938
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:
Copy link
Member

@GromNaN GromNaN Apr 4, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should tell how to create a geo index.

ccho-mongodb reacted with thumbs up emoji
Copy link
Contributor Author

@ccho-mongodb ccho-mongodb Apr 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

@ccho-mongodb ccho-mongodb merged commit 2b0b5e6 into mongodb:4.1 Apr 8, 2024
@ccho-mongodb ccho-mongodb deleted the DOCSP-35966-query-builder branch April 8, 2024 13:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@GromNaN GromNaN GromNaN approved these changes

@rustagir rustagir Awaiting requested review from rustagir

Assignees

No one assigned

Labels

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

AltStyle によって変換されたページ (->オリジナル) /