Query MongoDB - Java SDK

Insert a Single Document

You can insert a single document using collection.insertOne().

The following snippet inserts a single document describing a "lily of the valley" plant into a collection of documents that describe plants for sale in a group of stores:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully inserted a document with id: BsonObjectId{value=5f19...}

Insert Multiple Documents

You can insert multiple documents at the same time using collection.insertMany().

The following snippet inserts three documents describing plants into a collection of documents that describe plants for sale in a group of stores:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully inserted 3 documents into the collection.

Find a Single Document

You can find a single document using collection.findOne().

The following snippet finds a single document from the a collection of documents that describe plants for sale in a group of stores where the plant document's type field contains the string value "perennial":

Running this snippet produces output similar to the following:

V/EXAMPLE: successfully found a document: Plant [id=5f18..., name=venus flytrap, sunlight=full, color=white, type=perennial, partition=Store 42]

Find Multiple Documents

You can find multiple documents using collection.find().

The following snippet finds all documents in a collection of documents that describe plants for sale in a group of stores that contain a field named _partition with a value of "Store 42":

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully found all plants for Store 42:
V/EXAMPLE: Plant [id=5f18..., name=venus flytrap, sunlight=full, color=white, type=perennial, partition=Store 42]
V/EXAMPLE: Plant [id=5f18..., name=sweet basil, sunlight=partial, color=green, type=annual, partition=Store 42]
V/EXAMPLE: Plant [id=5f18..., name=thai basil, sunlight=partial, color=green, type=perennial, partition=Store 42]
V/EXAMPLE: Plant [id=5f18..., name=helianthus, sunlight=full, color=yellow, type=annual, partition=Store 42]

Count Documents in the Collection

You can count documents in a collection using collection.count(). You can specify an optional query to determine which documents to count. If you don't specify a query, the action counts all documents in the collection.

The following snippet counts the number of documents in a collection of documents that describe plants for sale in a group of stores:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully counted, number of documents in the collection: 5

Update a Single Document

You can update a single document using collection.updateOne().

The following snippet updates a single document in a collection of documents that describe plants for sale in a group of stores. This operation queries for a document where the name field contains the value "petunia" and changes the value of the first matched document's sunlight field to "partial":

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully updated a document.

Update Multiple Documents

You can update multiple documents using collection.updateMany().

The following snippet updates multiple documents in a collection of documents that describe plants for sale in a group of stores. This operation queries for documents where the _partition field contains the value "Store 47" and changes the value of the _partition field of each matching document to "Store 51":

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully updated 2 documents.

Upsert Documents

If an update operation does not match any document in the collection, you can automatically insert a single new document into the collection that matches the update query by setting the upsert option to true.

The following snippet updates a document in a collection of documents that describe plants for sale in a group of stores or inserts a new document if no document matches the query. This operation queries for documents where:

• the sunlight field has a value of "full"

• the type field has a value of "perennial"

• the color field has a value of "green"

• the _partition field has a value of "Store 47"

Because this snippet sets the upsert option to true, if no document matches the query, MongoDB creates a new document that includes both the query and specified updates:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully upserted a document with id: BsonObjectId{value=5f19...}

Delete a Single Document

You can delete a single document from a collection using collection.deleteOne().

The following snippet deletes one document in a collection of documents that describe plants for sale in a group of stores. This operation queries for a document where the color field has a value of "green" and deletes the first document that matches the query:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully deleted a document.

Delete Multiple Documents

You can delete multiple items from a collection using collection.deleteMany().

The following snippet deletes all documents in a collection of documents that describe plants for sale in a group of stores that match the query that matches documents containing both a sunlight field value of "full" and a type field value of "annual".

Running this snippet produces output resembling the following:

V/EXAMPLE: succcessfully deleted 2 documents.

Watch for Changes in a Collection

You can open a stream of changes made to a collection by calling collection.watch() or collection.watchAsync(). You can watch for changes to specific documents in a collection by passing the object ids of the objects you would like to monitor as a variable number of arguments.

The following snippet watches for changes to any documents in the plants collection:

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully inserted a document with id BsonObjectId{value=5f6bb...}
V/EXAMPLE: Event type: INSERT full document: Plant [id=5f6bb..., name=triffid, sunlight=low, color=green, type=perennial, partition=Store 47]

Watch for Changes in a Collection with a Filter

You can open a stream of changes made to documents in a collection that fulfill certain criteria by calling collection.watchWithFilter() or collection.watchWithFilterAsync(). Both methods accept a Document or BsonDocument parameter that is used as the query of a $match operator to process each database event that occurs while watching the collection.

The following snippet watches for changes to documents in the plants collection, but only triggers the provided callback for events corresponding to documents belonging to the partition named "Store 42":

Running this snippet produces output resembling the following:

V/EXAMPLE: successfully inserted 2 documents into the collection
V/EXAMPLE: Event type: INSERT full document: Plant [id=5f6bb..., name=venomous tentacula, sunlight=low, color=brown, type=annual, partition=Store 42]

Filter Documents

You can use the $match stage to filter documents according to a Query API query filter.

{
  "$match": {
    "<Field Name>": <Query Expression>,
    ...
  }
}

Group Documents

You can use the $group stage to aggregate summary data for one or more documents. MongoDB groups documents based on the expression defined in the _id field value of the $group stage. You can reference a specific document field by prefixing the field name with a $.

The following snippet groups all documents in the plants collection by their type value and aggregates a count of the number of each type:

Project Document Fields

You can use the $project stage to include or omit specific fields from documents. Additionally, you can calculate new fields using aggregation operators. Projections work in two ways:

• Explicitly include fields with a value of 1. This has the side-effect of implicitly excluding all unspecified fields.

• Implicitly exclude fields with a value of 0. This has the side-effect of implicitly including all unspecified fields.

These two methods of projection are mutually exclusive: if you explicitly include fields, you cannot explicitly exclude fields, and vice versa.

{
  "$project": {
    "<Field Name>": <0 | 1 | Expression>,
    ...
  }
}

Add Fields to Documents

You can use the $addFields stage to add new fields with calculated values using aggregation operators.

Unwind Array Values

You can use the $unwind stage to transform a single document containing an array into multiple documents containing individual values from that array. When you unwind an array field, MongoDB copies each document once for each element of the array field but replaces the array value with the array element in each copy.

{
  $unwind: {
    path: <Array Field Path>,
    includeArrayIndex: <string>,
    preserveNullAndEmptyArrays: <boolean>
  }
}

Consider the following document from the a collection of purchases:

   {
     _id: 123,
     customerId: 24601,
     items: [
       { name: "Baseball", quantity: 5 },
       { name: "Baseball Mitt", quantity: 1 },
       { name: "Baseball Bat", quantity: 1 },
     ]
   }

If we apply the example $unwind stage to this document, the stage outputs the following three documents:

   {
     _id: 123,
     customerId: 24601,
     itemIndex: 0,
     items: { name: "Baseball", quantity: 5 }
   }, {
     _id: 123,
     customerId: 24601,
     itemIndex: 1,
     items: { name: "Baseball Mitt", quantity: 1 }
   }, {
     _id: 123,
     customerId: 24601,
     itemIndex: 2,
     items: { name: "Baseball Bat", quantity: 1 }
   }