P1: CRUD usage examples moved to appropriate pages #618

rachel-mack · 2025-02-19T20:25:34Z

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-47267

Staging Links

crud/read-operations/retrieve

crud/write-operations/bulk

crud/write-operations/delete

crud/write-operations/insert

crud/write-operations/modify

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2025-02-19T20:25:53Z

✅ Deploy Preview for docs-java ready!

Name	Link
🔨 Latest commit	`6ed740d`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-java/deploys/67d1ce32fbe5db0008764cf3
😎 Deploy Preview	https://deploy-preview-618--docs-java.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

norareidy

Left some suggestions!

source/crud/read-operations/retrieve.txt

source/includes/crud/example-intro.rst

source/includes/crud/Delete.java

source/includes/crud/Find.java

source/includes/crud/Insert.java

norareidy

Left some more suggestions, they're all pretty minor but lmk if you want me to take another look

source/crud/read-operations/retrieve.txt

source/crud/write-operations/bulk.txt

source/crud/write-operations/delete.txt

source/includes/crud/Update.java

source/crud/write-operations/bulk.txt

source/crud/write-operations/modify.txt

source/crud/read-operations/retrieve.txt

source/crud/write-operations/delete.txt

rachel-mack · 2025-02-26T14:59:29Z

@katcharov This is ready for tech review.

The .java files have been relocated and a few of them merged together. They have all been run locally.

rachel-mack · 2025-03-04T14:39:59Z

This ready for tech review.
NOTE: Some of the documents have been moved, but the only content that has been changes is under the <Operator> Example: Full File heading on each page.
All examples have been tested locally.

katcharov

Partial review (Retrieve section)

katcharov · 2025-03-05T21:47:59Z

source/crud/read-operations/retrieve.txt

+To retrieve a single document, you can append the ``first()`` method to your
+``find()`` operation. You can use the ``sort()`` operation before selecting the first
+document to help choose the correct file.


Should this discuss any other methods, apart from first()?

To retrieve a single document, you can use the first() method with a find() method. To select a particular document based on ordering, use the sort() method prior to applying first().

"append" is odd.

Let's avoid the term "correct", except to identify actual correctness issues. This suggests first does not behave correctly unless sort is supplied, but it is often fine to select an arbitrary first item.

I think "file" is intended to be a synonym for "document" but this should be avoided since we do not deal with files, and we should refer to documents as such.

Somewhat technical, but the sort is part of the find operation. find() is a method.

If we are counting on using first, and it is worth suggesting sort, it is probably worth suggesting limit due to this.

There are also a few unusual or imprecise phrasings in the paragraphs above:

Use the find operation to retrieve a subset of your existing data in MongoDB. You can specify what data to return including which documents to retrieve, in what order to retrieve them, and how many to retrieve.

"what data to return including which documents to retrieve" suggests that there might be something else besides documents

"subset" and "existing" seem unnecessary: "Use the find operation to retrieve data from MongoDB"?

To perform a find operation, call the find() method on an instance of a MongoCollection.

Somewhat technical, but the operation is not performed (sent to the server and executed there) until a method like "first" (or iterator, etc.) is called.

I've made some changes here. The only thing I wasn't sure what to do about is your last point:

To perform a find operation...

If someone executes the following code:

collection.find(filter)

Does the server execute a find operation? I understand there a distinction between a method and an operation, but the method is the vehicle by which a user causes a find operation to be performed, correct? Like are we just talking about semantics, or is this something that the reader would find confusing about how this written?

I appreciate you checking to make sure this is clear.

collection.find(filter) ... Does the server execute a find operation?

No, this actually happens only after a method like first (or: executeExplain, iterator, cursor, forEach, ...) is invoked. The preceding methods, like sort, build something like an BSON document representing the operation. Those final methods eventually send BSON to the server, where the operation is executed. Calling the find method on an instance of a collection will not initiate a search on the server. (Not that we need to document all of this, but the docs should not imply otherwise.)

(I do realize that some of this goes beyond what was added in this PR, so it is fine if it is addressed in another ticket.)

OK, thanks for the clarification. I've made some changes.

katcharov · 2025-03-05T22:07:13Z

source/includes/crud/Find.java

@@ -36,12 +38,20 @@ public static void main( String[] args ) {
                    .sort(Sorts.descending("title")).iterator();


The comments could be more specific, // Projects "title" and "imdb" fields, excludes "_id"., or Retrieves documents that have a runtime length of under 15 minutes, sorted in reverse-alphabetical order etc. This should probably also apply to "System.out" outputs.

It seems unusual to sort in reverse-alphabetical order - perhaps this is confusing, and suggests descending is alphabetical?

katcharov · 2025-03-05T22:10:05Z

source/includes/crud/Find.java

-            } finally {
-                cursor.close();
+            System.out.println("Number of documents found with find(): " + cursor.available() + "\n");
+            cursor.close();


Consider using try-with-resources.

katcharov · 2025-03-05T22:10:35Z

source/includes/crud/Find.java

-                }
-            } finally {
-                cursor.close();
+            System.out.println("Number of documents found with find(): " + cursor.available() + "\n");


It does not make sense to sort if all we need is the total number of documents. If we really need the number, we should use a $count stage.

It seems that we should demonstrate cursor iteration - this is much more common and important than available or first.

Reworked this eg

katcharov · 2025-03-05T22:44:56Z

source/includes/crud/Find.java

+            // Retrieves the first matching document, applying a projection and a descending sort to the results
+            Document doc = collection.find(eq("title", "The Room"))
+                    .projection(projectionFields)
+                    .sort(Sorts.descending("imdb.rating"))
+                    .first();


It seems unusual to find the best-rated movie with a particular name (or other identifier) - usually we would return all movies, or include some other criteria such as year.

A more realistic query might be to find the best-rated ("first") movie under 15 minutes.

katcharov · 2025-03-05T22:49:28Z

source/includes/crud/Insert.java

+            // Prints a message if any exceptions occur during the operation
+            } catch (MongoException me) {
+                System.err.println("Unable to insert due to an error: " + me);


The comment might be too obvious or literal (by literal, a severe case would be saying "catches a MongoException" or "calls println"). If it really is needed, I would put it after the catch above the println, since it's the println that prints.

katcharov · 2025-03-10T15:01:56Z

source/includes/crud/Find.java

+            System.out.print("10 movies under 15 minutes: ");
+            docs.forEach(doc -> System.out.print(doc.get("title") + ", "));


Suggested change

System.out.print("10 movies under 15 minutes: ");

docs.forEach(doc -> System.out.print(doc.get("title") + ", "));

System.out.println("10 movies under 15 minutes: ");

docs.forEach(doc -> System.out.println("- " + doc.get("title")));

System.out.println();

Avoids trailing comma issue, and the lack of trailing newline, and moves the newline "spacer" to the end of the list.

katcharov · 2025-03-10T15:04:40Z

source/includes/crud/Find.java

                    .projection(projectionFields)
-                    .sort(Sorts.descending("title")).iterator();
+                    .sort(Sorts.ascending("title"))
+                    .limit(10);

            // Prints the results of the find operation as JSON


Suggested change

// Prints the results of the find operation as JSON

This is no longer json.

katcharov · 2025-03-10T15:09:27Z

source/includes/crud/Find.java

            if (doc == null) {
                System.out.println("No results found.");
            } else {
-                System.out.println("Document found with find().first(): " + doc.toJson());
+                System.out.println("\n\nThe highest rated movie under 15 minutes: " + doc.toJson());


Suggested change

System.out.println("\n\nThe highest rated movie under 15 minutes: " + doc.toJson());

System.out.println("The highest rated movie under 15 minutes: " + doc.toJson().get("title"));

For consistency with changes to preceding example (no longer prints json).

katcharov · 2025-03-10T15:10:41Z

source/includes/crud/Find.java

                    .first();

-            // Prints a message if there are no result documents, or prints the result document as JSON
+            // Prints result document as JSON


Suggested change

// Prints result document as JSON

katcharov · 2025-03-10T17:02:07Z

source/crud/read-operations/retrieve.txt

+- Calls the ``find()`` method to retrieve multiple documents that have a ``runtime`` value less than ``15``, applying a projection and sort to the results 
+- Calls the ``find()`` and ``first()`` methods to retrieve a document that has a ``title`` value of ``"The Room"``, applying a projection and sort before returning the first match 


This is no longer accurate

katcharov · 2025-03-10T17:06:37Z

source/includes/crud/Delete.java

+                System.out.println("deleteOne() document count: " + result.getDeletedCount());
+
+            // Prints a message if any exceptions occur during the operation
+            } catch (MongoException me) {


(This comment is optional/informational.)

Note that even the find operation can fail with an exception (it does not have these try-catch blocks).

If you feel these operation-level try-catch blocks clutter things up now that the files are merged, it is fine to remove them (also fine to keep). They should of course be kept if there is some reason, for example in this section, there is this suggestion to use try-catch blocks for a particular purpose:

Use a try-catch block to get an acknowledgment for successfully processed documents before the error occurs:

As an aside, that message phrasing could be improved:

Use a try-catch block to learn which documents were successfully processed before the error occured:

katcharov · 2025-03-10T17:21:53Z

source/includes/crud/Delete.java


                // Prints the number of deleted documents
-                System.out.println("Deleted document count: " + result.getDeletedCount());
+                System.out.println("deleteMany() document count: " + result.getDeletedCount());


It is not obvious what a "deleteMany document count" is.

Usually the target audience of output messages (vs log messages, or system outs intended for debugging purposes) is the end-user running the program, so they do not make reference to specific methods or other implementation details.

Compare with the output messages from the Insert page:

InsertOneResult result = collection.insertOne(doc1); System.out.println("Inserted a document with the following id: " + ...); ... System.out.println("Inserted documents with the following ids: " +

Here, the plural disambiguates which method was used.

In any case, it seems the style should be consistent across the pages and examples.

katcharov · 2025-03-10T18:23:38Z

source/includes/crud/Update.java

+            UpdateOptions options = new UpdateOptions().upsert(true);
+
+
+            Document updateOneQuery = new Document().append("title",  "Cool Runnings 2");


Suggested change

UpdateOptions options = new UpdateOptions().upsert(true);

Document updateOneQuery = new Document().append("title", "Cool Runnings 2");

UpdateOptions options = new UpdateOptions().upsert(true);

Document updateOneQuery = new Document().append("title", "Cool Runnings 2");

just excess whitespace

katcharov · 2025-03-10T18:41:53Z

source/includes/crud/Delete.java

@@ -1,8 +1,8 @@
-// Deletes multiple documents from a collection by using the Java driver
+// Deletes a document from a collection by using the Java driver


This file now includes a deleteMany, so the old incorrect comment is now correct. Might be worth doublechecking these comments across files.

rachel-mack requested a review from a team as a code owner February 19, 2025 20:25

rachel-mack requested review from katcharov and removed request for a team February 19, 2025 20:25

rachel-mack marked this pull request as draft February 19, 2025 20:25

rachel-mack changed the title ~~Move BulkWrite example~~ P1: CRUD usage examples moved to appropriate pages Feb 25, 2025

rachel-mack marked this pull request as ready for review February 25, 2025 16:46

norareidy requested changes Feb 25, 2025

View reviewed changes

norareidy approved these changes Feb 25, 2025

View reviewed changes

katcharov requested changes Mar 5, 2025

View reviewed changes

rachel-mack requested a review from katcharov March 7, 2025 20:54

katcharov requested changes Mar 10, 2025

View reviewed changes

katcharov reviewed Mar 10, 2025

View reviewed changes

rachel-mack added 15 commits March 11, 2025 21:33

bulk write eg

b6f35b0

update bulk write eg

b409766

add data details

20c0cc8

add data details

49e3cbe

intro

a63df06

delete

9dadaf1

insert

f37bea4

modify

218137d

modify

2da92fe

remove files

e9dd4f3

retrieve

985d8ef

clean up

efbb1f7

readd BulkWrite snippets

d733ce6

vale

80c94ba

NR feedback

229473f

rachel-mack added 8 commits March 11, 2025 21:39

NR feedback

d1667ee

NR feedback

e9c8af8

comments

8e165d9

tags

73af453

meta data

bcdd1f8

MK feedback

5b02415

MK feedback

6e5455e

MK feedback

afb49e7

rachel-mack force-pushed the DOCSP-47267-bulkwrite branch from 827b3b3 to afb49e7 Compare March 12, 2025 01:41

rachel-mack added 2 commits March 11, 2025 21:47

readd

24b9168

readd

924ba59

rachel-mack requested a review from katcharov March 12, 2025 01:48

remove try blocks

6ed740d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

P1: CRUD usage examples moved to appropriate pages #618

P1: CRUD usage examples moved to appropriate pages #618

rachel-mack commented Feb 19, 2025 •

edited by github-actions bot

Loading

netlify bot commented Feb 19, 2025 •

edited

Loading

norareidy left a comment

norareidy left a comment

rachel-mack commented Feb 26, 2025

rachel-mack commented Mar 4, 2025 •

edited

Loading

katcharov left a comment

katcharov Mar 5, 2025

rachel-mack Mar 7, 2025

katcharov Mar 7, 2025

rachel-mack Mar 11, 2025

katcharov Mar 5, 2025

katcharov Mar 5, 2025

katcharov Mar 5, 2025

rachel-mack Mar 7, 2025

katcharov Mar 5, 2025

katcharov Mar 5, 2025

katcharov Mar 10, 2025

katcharov Mar 10, 2025

katcharov Mar 10, 2025

katcharov Mar 10, 2025

katcharov Mar 10, 2025

katcharov Mar 10, 2025 •

edited

Loading

katcharov Mar 10, 2025

katcharov Mar 10, 2025 •

edited

Loading

katcharov Mar 10, 2025

		@@ -36,12 +38,20 @@ public static void main( String[] args ) {
		.sort(Sorts.descending("title")).iterator();

		System.out.print("10 movies under 15 minutes: ");
		docs.forEach(doc -> System.out.print(doc.get("title") + ", "));

-            System.out.print("10 movies under 15 minutes: ");
-            docs.forEach(doc -> System.out.print(doc.get("title") + ", "));
+            System.out.println("10 movies under 15 minutes: ");
+            docs.forEach(doc -> System.out.println("- " + doc.get("title")));
+            System.out.println();

	System.out.println("\n\nThe highest rated movie under 15 minutes: " + doc.toJson());
	System.out.println("The highest rated movie under 15 minutes: " + doc.toJson().get("title"));

		- Calls the ``find()`` method to retrieve multiple documents that have a ``runtime`` value less than ``15``, applying a projection and sort to the results
		- Calls the ``find()`` and ``first()`` methods to retrieve a document that has a ``title`` value of ``"The Room"``, applying a projection and sort before returning the first match

		UpdateOptions options = new UpdateOptions().upsert(true);


		Document updateOneQuery = new Document().append("title", "Cool Runnings 2");

		@@ -1,8 +1,8 @@
		// Deletes multiple documents from a collection by using the Java driver
		// Deletes a document from a collection by using the Java driver

P1: CRUD usage examples moved to appropriate pages #618

Are you sure you want to change the base?

P1: CRUD usage examples moved to appropriate pages #618

Conversation

rachel-mack commented Feb 19, 2025 • edited by github-actions bot Loading

Pull Request Info

Staging Links

Self-Review Checklist

netlify bot commented Feb 19, 2025 • edited Loading

✅ Deploy Preview for docs-java ready!

norareidy left a comment

Choose a reason for hiding this comment

norareidy left a comment

Choose a reason for hiding this comment

rachel-mack commented Feb 26, 2025

rachel-mack commented Mar 4, 2025 • edited Loading

katcharov left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

katcharov Mar 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

katcharov Mar 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rachel-mack commented Feb 19, 2025 •

edited by github-actions bot

Loading

netlify bot commented Feb 19, 2025 •

edited

Loading

rachel-mack commented Mar 4, 2025 •

edited

Loading

katcharov Mar 10, 2025 •

edited

Loading

katcharov Mar 10, 2025 •

edited

Loading