DOCSP-35948 write operations - insert documents #2804

ccho-mongodb · 2024-03-29T15:39:14Z

JIRA: https://jira.mongodb.org/browse/DOCSP-35948
Staging:

Note for reviewer:

This PR is for one of a few tickets related to completing the "Write Operations" page.

Other "Write Operations" page tickets:

Checklist

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

ccho-mongodb · 2024-03-29T15:50:33Z

docs/fundamentals/write-operations.txt

+- Modify Documents
+- Delete Documents


Note to reviewer:
These sections will be completed in separate tickets and merged together when ready for publishing.

norareidy

Left some suggestions, but overall LGTM!

norareidy · 2024-03-29T20:07:04Z

docs/fundamentals/write-operations.txt

+.. tip::
+
+   The ``$fillable`` attribute lets you use Laravel mass assignment for insert
+   operations. To learn more about mass assignment, see :ref:`laravel-model-mass-assignment`.


S: I'd clarify where this links to

Suggested change

operations. To learn more about mass assignment, see :ref:`laravel-model-mass-assignment`.

operations. To learn more about mass assignment, see the :ref:`laravel-model-mass-assignment` section in the Eloquent Model Class guide.

norareidy · 2024-03-29T20:07:35Z

docs/fundamentals/write-operations.txt

+   data types. To learn more, see `Attribute Casting <https://laravel.com/docs/{+laravel-docs-version+}/eloquent-mutators#attribute-casting>`__
+   in the Laravel documentation.
+
+To learn more about Eloquent models in {+odm-short+} see the :ref:`laravel-eloquent-models`


S: add a comma here

Suggested change

To learn more about Eloquent models in {+odm-short+} see the :ref:`laravel-eloquent-models`

To learn more about Eloquent models in {+odm-short+}, see the :ref:`laravel-eloquent-models`

norareidy · 2024-03-29T20:09:39Z

docs/fundamentals/write-operations.txt

+These examples show how to use the ``save()`` Eloquent method to insert an
+instance of a ``Concert`` model as a MongoDB document.
+
+When the ``save()`` method succeeds, the instance on which you called the


S: since you mention a Concert model instance in the previous paragraph, I think the use of "instance" here is a little confusing. It would be helpful to clarify that this refers to a MongoDB instance:

Suggested change

When the ``save()`` method succeeds, the instance on which you called the

When the ``save()`` method succeeds, the MongoDB instance on which you called the

Good catch! This is the model instance, so I'll clarify that.

norareidy · 2024-03-29T20:10:20Z

docs/fundamentals/write-operations.txt

+This example code performs the following actions:
+
+- Creates a new instance of the ``Concert`` model
+- Assigns string values to the ``performer`` and ``venue`` field


S: [nit] I think field should be plural

Suggested change

- Assigns string values to the ``performer`` and ``venue`` field

- Assigns string values to the ``performer`` and ``venue`` fields

norareidy · 2024-03-29T20:13:34Z

docs/fundamentals/write-operations.txt

+   :end-before: end model insert one mass assign
+
+To learn more about the Carbon PHP API extension, see the
+`Carbon <https://github.com/briannesbitt/Carbon>`__ GitHub repository.


S: you can use :github: here

Suggested change

`Carbon <https://github.com/briannesbitt/Carbon>`__ GitHub repository.

:github:`Carbon <briannesbitt/Carbon>` GitHub repository.

norareidy · 2024-03-29T20:14:46Z

docs/fundamentals/write-operations.txt

+fails, it throws an exception.
+
+The example code saves multiple models in a single call by passing them as
+an array to ``insert()`` method:


S: add "the"

Suggested change

an array to ``insert()`` method:

an array to the ``insert()`` method:

norareidy · 2024-03-29T20:18:21Z

docs/fundamentals/write-operations.txt

+unique index on the ``_id`` field.
+
+For more information on creating indexes on MongoDB collections by using the
+Laravel schema builder, see the :ref:`laravel-eloquent-indexes` guide.


S: since this links to a section of the "Schema Builder" guide and not a separate "Indexes" guide, I think something like this would be more accurate:

Suggested change

Laravel schema builder, see the :ref:`laravel-eloquent-indexes` guide.

Laravel schema builder, see the :ref:`laravel-eloquent-indexes` section of the Schema Builder guide.

norareidy · 2024-03-29T20:26:13Z

docs/fundamentals.txt

+Learn how to perform the following tasks by using the {+odm-long+} in the
+following pages:


S: this sentence is a little repetitive; you could reword to something like:

Suggested change

Learn how to perform the following tasks by using the {+odm-long+} in the

following pages:

Learn how to use the {+odm-long+} to perform the following tasks:

Thanks, I like this reworded version!

GromNaN

LGTM. Thanks for the test with assertions.

docs/includes/fundamentals/write-operations/WriteOperationsTest.php

GromNaN

Small remark, but LGTM.

GromNaN · 2024-04-04T13:41:51Z

docs/fundamentals/write-operations.txt

+
+When the ``save()`` method succeeds, you can access the model instance on
+which you called the method. If the operation fails, the model instance is
+assigned a null value.


Don't you format the value as code?

Suggested change

assigned a null value.

assigned a ``null`` value.

I meant to use "null" as an adjective, but I can change it to make it clear that it's the value (e.g. "assigned null").

Chris Cho and others added 9 commits March 27, 2024 17:15

DOCSP-35948: Write operations

8fbbcc4

add examples

a5a75ca

apply phpcbf formatting

a678179

wip

eea96e5

apply phpcbf formatting

88024a5

add date info

24fdd13

apply phpcbf formatting

77bdbec

update title of read operations

831f06e

grammar fixes

d813f23

ccho-mongodb commented Mar 29, 2024

View reviewed changes

ccho-mongodb changed the title ~~DOCSP-35948 write operations~~ DOCSP-35948 write operations - insert documents Mar 29, 2024

norareidy approved these changes Mar 29, 2024

View reviewed changes

PRR fixes

9fcce6f

ccho-mongodb marked this pull request as ready for review April 1, 2024 13:50

ccho-mongodb requested a review from a team as a code owner April 1, 2024 13:50

ccho-mongodb requested a review from GromNaN April 1, 2024 13:50

ccho-mongodb added the docs label Apr 1, 2024

ccho-mongodb changed the base branch from 4.1 to 4.1-base-docs-write-operations April 1, 2024 18:58

GromNaN approved these changes Apr 2, 2024

View reviewed changes

docs/includes/fundamentals/write-operations/WriteOperationsTest.php Outdated Show resolved Hide resolved

remove comments from tests

3c04080

GromNaN approved these changes Apr 4, 2024

View reviewed changes

PRR fixes

e8c1491

ccho-mongodb merged commit 4459b55 into mongodb:4.1-base-docs-write-operations Apr 4, 2024

ccho-mongodb deleted the DOCSP-35948-write-operations branch April 4, 2024 18:51

norareidy mentioned this pull request Apr 11, 2024

DOCSP-35978: Insert multiple usage example #2849

Merged

3 tasks

	operations. To learn more about mass assignment, see :ref:`laravel-model-mass-assignment`.
	operations. To learn more about mass assignment, see the :ref:`laravel-model-mass-assignment` section in the Eloquent Model Class guide.

	To learn more about Eloquent models in {+odm-short+} see the :ref:`laravel-eloquent-models`
	To learn more about Eloquent models in {+odm-short+}, see the :ref:`laravel-eloquent-models`

	When the ``save()`` method succeeds, the instance on which you called the
	When the ``save()`` method succeeds, the MongoDB instance on which you called the

	- Assigns string values to the ``performer`` and ``venue`` field
	- Assigns string values to the ``performer`` and ``venue`` fields

	`Carbon <https://github.com/briannesbitt/Carbon>`__ GitHub repository.
	:github:`Carbon <briannesbitt/Carbon>` GitHub repository.

	an array to ``insert()`` method:
	an array to the ``insert()`` method:

	Laravel schema builder, see the :ref:`laravel-eloquent-indexes` guide.
	Laravel schema builder, see the :ref:`laravel-eloquent-indexes` section of the Schema Builder guide.

		Learn how to perform the following tasks by using the {+odm-long+} in the
		following pages:

	Learn how to perform the following tasks by using the {+odm-long+} in the
	following pages:
	Learn how to use the {+odm-long+} to perform the following tasks:

DOCSP-35948 write operations - insert documents #2804

DOCSP-35948 write operations - insert documents #2804

Uh oh!

Conversation

ccho-mongodb commented Mar 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

norareidy 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!

Choose a reason for hiding this comment

Uh oh!

GromNaN left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GromNaN 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!

ccho-mongodb commented Mar 29, 2024 •

edited

Loading