Databases and Collections

MongoDB stores documents in collections; the collections in databases.

Prerequisites

• Include following import statements:

  import org.mongodb.scala._
  import org.mongodb.scala.model.Filters._
  

Connect to a MongoDB Deployment

Connect to a running MongoDB deployment.

For example, include the following code to connect to a standalone MongoDB deployment running on localhost on port 27017.

val mongoClient = MongoClient()

For more information on connecting to running MongoDB deployments, see Connect to MongoDB.

Access a Database

Once you have a MongoClient instance connected to a MongoDB deployment, use its 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 test database:

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

Access a Collection

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

Specify the name of the collection to the getCollection() method.

For example, using the database instance, the following statement accesses the collection named myTestCollection:

val coll: MongoCollection[Document] = database.getCollection("myTestCollection")

If a collection does not exist, MongoDB creates the collection when you first store data for that collection.

You can also explicitly create a collection with various options, such as setting the maximum size or the documentation validation rules.

Explicitly Create a Collection

The MongoDB driver provides the createCollection() method to explicitly create a collection. When you explicitly create a collection, you can specify various collection options, such as a maximum size or the documentation validation rules, with the CreateCollectionOptions class. If you are not specifying these options, you do not need to explicitly create the collection since MongoDB creates new collections when you first store data for the collections.

Capped Collection

For example, the following operation creates a capped collection sized to 1 megabyte:

// Note: this code example uses a custom implicit helper referenced in the Quick Start Primer
database.createCollection("cappedCollection", CreateCollectionOptions().capped(true).sizeInBytes(0x100000))
        .printResults()

Document Validation

MongoDB provides the capability to validate documents during updates and insertions. Validation rules are specified on a per-collection basis using the ValidationOptions, which takes a filter document that specifies the validation rules or expressions.

// Note: this code example uses a custom implicit helper referenced in the Quick Start Primer
ValidationOptions collOptions = ValidationOptions().validator(
        Filters.or(Filters.exists("email"), Filters.exists("phone")))

database.createCollection("contacts", CreateCollectionOptions().validationOptions(collOptions))
        .printResults()

Get A List of Collections

You can get a list of the collections in a database using the MongoDatabase.listCollectionNames() method:

// Note: this code example uses a custom implicit helper referenced in the Quick Start Primer
database.listCollectionNames().printResults()

Drop a Collection

You can drop a collection by using the MongoCollection.drop() method:

// Note: this code example uses a custom implicit helper referenced in the Quick Start Primer
val collection: MongoCollection[Document] = database.getCollection("contacts")
collection.drop().printResults()

Immutability

MongoDatabase and MongoCollection instances are immutable. To create new instances from existing instances that have different property values, such as read concern, read preference, and write concern, the MongoDatabase and MongoCollection class provides various methods:

• MongoDatabase.withReadConcern

• MongoDatabase.withReadPreference

• MongoDatabase.withWriteConcern

• MongoCollection.withReadConcern

• MongoCollection.withReadPreference

• MongoCollection.withWriteConcern

For details, see Read Operations and Write Operations.

CodecRegistry

An overload of the getCollection method allows clients to specify a different class for representing BSON documents. For example, users may wish to use the strict and typesafe BsonDocument class with the CRUD API:

// Note: this code example uses a custom implicit helper referenced in the Quick Start Primer

// Pass BsonDocument.class as the second argument
import org.mongodb.scala.bson._

val collection: MongoCollection[BsonDocument] = database.getCollection[BsonDocument]("mycoll")

// insert a document
val document = BsonDocument("{x: 1}")
collection.insertOne(document).printResults()

document.append("x", BsonInt32(2)).append("y", BsonInt32(3))

// replace a document
collection.replaceOne(Filters.equal("_id", document.get("_id")), document)
          .printResults()

// find documents
collection.find().printResults()

There are two requirements that must be met for any class used in this way:

• a Codec for it must be registered in the MongoCollection’s CodecRegistry
• the Codec must be one that encodes and decodes a full BSON document (and not just, for example, a single BSON value like an Int32)

By default, a MongoCollection is configured with Codecs for four classes:

• Document (The Scala BsonDocument wrapper)
• BsonDocument
• Document (The Java drivers loosely type Document class)
• BasicDBObject (The legacy Java drivers loosely type Document class)

Applications, however, are free to register Codec implementations for other classes by customizing the CodecRegistry. New CodecRegistry instances are configurable at three levels:

• In a MongoClient via MongoClientSettings
• In a MongoDatabase via its withCodecRegistry method
• In a MongoCollection via its withCodecRegistry method

Consider the case of encoding and decoding instances of the UUID class. The Java driver by default encodes instances of UUID using a byte ordering that is not compatible with other MongoDB drivers, and changing the default would be quite dangerous. But it is possible for new applications that require interoperability across multiple drivers to be able to change that default, and they can do that with a CodecRegistry.

// Replaces the default UuidCodec with one that uses the new standard UUID representation
import org.bson.UuidRepresentation
import org.bson.codecs.UuidCodec
import org.bson.codecs.configuration.CodecRegistries

val codecRegistry = CodecRegistries.fromRegistries(
  CodecRegistries.fromCodecs(new UuidCodec(UuidRepresentation.STANDARD)),
  MongoClient.DEFAULT_CODEC_REGISTRY)

// globally
val settings = MongoClientSettings.builder()
                .codecRegistry(codecRegistry).build()
val client = MongoClient(settings)

// or per database
val database = client.getDatabase("mydb")
                     .withCodecRegistry(codecRegistry)

// or per collection
val collection = database.getCollection("mycoll")
                         .withCodecRegistry(codecRegistry)