We now know how to convert DBObject instances to custom Scala classes. In this section, you will learn how to construct queries that only return a subset of the documents in the collection.

In the previous section, you learned to retrieve all the documents in a collection as follows:

scala> val objs = collection.find().toList
List[DBObject] = List({ "_id" : { "$oid" : "56365cec46f9534fae8ffd7f"} ,...

The collection.find() method returns an iterator over all the documents in the collection. By calling .toList on this iterator, we materialize it to a list.

We can customize which documents are returned by passing a query document to the .find method. For instance, we can retrieve documents for a specific login name:

scala> val query = DBObject("login" -> "mojombo")
query: DBObject = { "login" : "mojombo"}

scala> val objs = collection.find(query).toList
List[DBObject] = List({ "_id" : { "$oid" : "562e922546f953739c43df02"} , "login" : "mojombo",...

MongoDB queries are expressed as DBObject instances. Keys in the DBObject correspond to fields in the collection's documents, and the values are expressions controlling the allowed values of this field. Thus, DBObject("login" -> "mojombo") will select all the documents for which the login field is mojombo. Using a DBObject instance to represent a query might seem a little obscure, but it will quickly make sense if you read the MongoDB documentation (https://docs.mongodb.org/manual/core/crud-introduction/): queries are themselves just JSON objects in MongoDB. Thus, the fact that the query in Casbah is represented as a DBObject is consistent with other MongoDB client implementations. It also allows someone familiar with MongoDB to start writing Casbah queries in no time.

MongoDB supports more complex queries. For instance, to query everyone with "github_id" between 20 and 30, we can write the following query:

scala> val query = DBObject("github_id" -> 
  DBObject("$gte" -> 20, "$lt" -> 30))
query: DBObject = { "github_id" : { "$gte" : 20 , "$lt" : 30}}

scala> collection.find(query).toList
List[com.mongodb.casbah.Imports.DBObject] = List({ "_id" : { "$oid" : "562e922546f953739c43df0f"} , "github_id" : 23 , "login" : "takeo" , ...

We limit the range of values that github_id can take with DBObject("$gte" -> 20, "$lt" -> 30). The "$gte" string indicates that github_id must be greater or equal to 20. Similarly, "$lt" denotes the less than operator. To get a full list of operators that you can use when querying, consult the MongoDB reference documentation (http://docs.mongodb.org/manual/reference/operator/query/).

So far, we have only looked at queries on top-level fields. Casbah also lets us query fields in subdocuments and arrays using the dot notation. In the context of array values, this will return all the documents for which at least one value in the array matches the query. For instance, to retrieve all users who have a repository whose main language is Scala:

scala> val query = DBObject("repos.language" -> "Scala")
query: DBObject = { "repos.language" : "Scala"}

scala> collection.find(query).toList
List[DBObject] = List({ "_id" : { "$oid" : "5635da4446f953234ca634df"}, "login" : "kevinclark"...