MongoDB Scala Driver Quick Start

The following code snippets come from the QuickTour.java example code that can be found with the Scala driver source on github.

Prerequisites

• A running MongoDB on localhost using the default port for MongoDB 27017

• MongoDB Scala Driver. See Installation for instructions on how to install the MongoDB driver.

• The following import statements:

New MongoClient API (since 3.7):

import org.mongodb.scala._
import org.mongodb.scala.model.Aggregates._
import org.mongodb.scala.model.Filters._
import org.mongodb.scala.model.Projections._
import org.mongodb.scala.model.Sorts._
import org.mongodb.scala.model.Updates._
import org.mongodb.scala.model._

import scala.collection.JavaConverters._

Make a Connection

Use the MongoClient companion object to make a connection to a running MongoDB instance.

The MongoClient instance represents a pool of connections to the database; you will only need one instance of class MongoClient even with multiple concurrent operations.

Connect to a Single MongoDB instance

The following example shows several ways to connect to a single MongoDB server.

To connect to a single MongoDB instance:

• You can instantiate a MongoClient object without any parameters to connect to a MongoDB instance running on localhost on port 27017:

val mongoClient: MongoClient = MongoClient()

• You can explicitly specify the hostname to connect to a MongoDB instance running on the specified host on port 27017:

val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("hostOne")).asJava))
    .build())

• You can explicitly specify the hostname and the port:

val mongoClient: MongoClient = MongoClient(
  MongoClientSettings.builder()
    .applyToClusterSettings((builder: ClusterSettings.Builder) => builder.hosts(List(new ServerAddress("hostOne", 27017)).asJava))
    .build())

• You can specify the ConnectionString:

val mongoClient: MongoClient = MongoClient("mongodb://hostOne:27017")

Access a Database

Once you have a MongoClient instance connected to a MongoDB deployment, use the MongoClient.getDatabase() method to access a database.

Specify the name of the database to the getDatabase() method. If a database does not exist, MongoDB creates the database when you first store data for that database.

The following example accesses the mydb database:

 val database: MongoDatabase = mongoClient.getDatabase("mydb")

MongoDatabase instances are immutable.

Access a Collection

Once you have a MongoDatabase instance, use its the getCollection(String collectionName) method to access a collection.

Specify the name of the collection to the getCollection() method. If a collection does not exist, MongoDB creates the collection when you first store data for that collection.

For example, using the database instance, the following statement accesses the collection named test in the mydb database:

val collection: MongoCollection[Document] = database.getCollection("test")

MongoCollection instances are immutable.

Create a Document

To create the document using the Scala driver, use the Document class.

For example, consider the following JSON document:

  {
   "name" : "MongoDB",
   "type" : "database",
   "count" : 1,
   "info" : { x : 203, y : 102 }
  }

Using the Document class:

val doc: Document = Document("_id" -> 0, "name" -> "MongoDB", "type" -> "database",
                             "count" -> 1, "info" -> Document("x" -> 203, "y" -> 102))

Insert a Document

Once you have the MongoCollection object, you can insert documents into the collection.

Insert One Document

To insert the document into the collection, use the insertOne() method. Using the results() implicit helper we block until the observer is completed:

collection.insertOne(doc).results()

val observable: Observable[InsertOneResult] = collection.insertOne(doc)

observable.subscribe(new Observer[InsertOneResult] {

  override def onSubscribe(subscription: Subscription): Unit = subscription.request(1)

  override def onNext(result: InsertOneResult): Unit = println(s"onNext $result")

  override def onError(e: Throwable): Unit = println("Failed")
  
  override def onComplete(): Unit = println("Completed")
})

Insert Multiple Documents

To add multiple documents, you can use the collection’s insertMany() method which takes a list of documents to insert.

The following example will add multiple documents of the form:

{ "i" : value }

Create the documents in a loop.

val documents = (1 to 100) map { i: Int => Document("i" -> i) }

To insert these documents to the collection, pass the list of documents to the insertMany() method.

val insertObservable = collection.insertMany(documents)

As we haven’t subscribed yet no documents have been inserted, lets chain together two operations, inserting and counting.

Count Documents in A Collection

Once we’ve inserted the documents list we should, have a total of 101 documents in the collection (the 100 we did in the loop, plus the first one). We can check to see if we have them all using the count() method.

Lets chain the two operations together using a for comprehension. The following code should insert the documents then count the number of documents and print the results:

val insertAndCount = for {
  insertResult <- insertObservable
  countResult <- collection.countDocuments()
} yield countResult

println(s"total # of documents after inserting 100 small ones (should be 101):  ${insertAndCount.headResult()}")

Query the Collection

To query the collection, you can use the collection’s find() method. You can call the method without any arguments to query all documents in a collection or pass a filter to query for documents that match the filter criteria.

Find the First Document in a Collection

To return the first document in the collection, use the find() method without any parameters and chain to find() method the first() method.

The following example prints the first document found in the collection.

collection.find().first().printHeadResult()

The example should print the following document:

{ "_id" : { "$oid" : "551582c558c7b4fbacf16735" },
  "name" : "MongoDB",
  "type" : "database",
  "count" : 1,
  "info" : { "x" : 203, "y" : 102 } }

Find All Documents in a Collection

To retrieve all the documents in the collection, we will use the find() method. The find() method returns a FindObservable instance that provides a fluent interface for chaining or controlling find operations. The following code retrieves all documents in the collection and prints them out (101 documents):

collection.find().printResults()

Specify a Query Filter

To query for documents that match certain conditions, pass a filter object to the find() method. To facilitate creating filter objects, the Scala driver provides the Filters helper.

Get A Single Document That Matches a Filter

For example, to find the first document where the field i has the value 71, pass an equal filter object to specify the equality condition:

collection.find(equal("i", 71)).first().printHeadResult()

The example prints one document:

{ "_id" : { "$oid" : "5515836e58c7b4fbc756320b" }, "i" : 71 }

Get All Documents That Match a Filter

The following example returns and prints all documents where "i" > 50:

// now use a range query to get a larger subset
collection.find(gt("i", 50)).printResults()

which should print the documents where i > 50.

To specify a filter for a range, such as 50 < i <= 100, you can use the and helper:

collection.find(and(gt("i", 50), lte("i", 100))).printResults()

Update Documents

To update documents in a collection, you can use the collection’s updateOne and updateMany methods.

Pass to the methods:

• A filter object to determine the document or documents to update. To facilitate creating filter objects, the Scala driver provides the Filters helper. To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

• An update document that specifies the modifications. For a list of the available operators, see update operators.

The update methods return an UpdateResult which provides information about the operation including the number of documents modified by the update.

Update a Single Document

To update at most a single document, use the updateOne

The following example updates the first document that meets the filter i equals 10 and sets the value of i to 110:

collection.updateOne(equal("i", 10), set("i", 110)).printHeadResult("Update Result: ")

Update Multiple Documents

To update all documents matching the filter, use the updateMany method.

The following example increments the value of i by 100 for all documents where =i is less than 100:

collection.updateMany(lt("i", 100), inc("i", 100)).printHeadResult("Update Result: ")

Delete Documents

To delete documents from a collection, you can use the collection’sdeleteOne and deleteMany methods.

Pass to the methods a filter object to determine the document or documents to delete. To facilitate creating filter objects, the Scala driver provides the Filters helper. To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

The delete methods return a DeleteResult which provides information about the operation including the number of documents deleted.

Delete a Single Document That Match a Filter

To delete at most a single document that match the filter, use thedeleteOne method:

The following example deletes at most one document that meets the filter i equals 110:

collection.deleteOne(equal("i", 110)).printHeadResult("Delete Result: ")

Delete All Documents That Match a Filter

To delete all documents matching the filter use the deleteMany method.

The following example deletes all documents where i is greater or equal to 100:

collection.deleteMany(gte("i", 100)).printHeadResult("Delete Result: ")

Create Indexes

To create an index on a field or fields, pass an index specification document to the createIndex() method. An index key specification document contains the fields to index and the index type for each field:

Document(<field1> -> <type1>, <field2>, <type2>, ...)

• For an ascending index type, specify 1 for <type>.
• For a descending index type, specify -1 for <type>.

The following example creates an ascending index on the i field:

collection.createIndex(Document("i" -> 1)).printHeadResult("Create Index Result: %s")

For a list of other index types, see Create Indexes

Additional Information

For additional tutorials about using MongoDB with Case Classes, see the Case Class Quick Start.

For additional tutorials (such as to use the aggregation framework, specify write concern, etc.), see Scala Driver Tutorials