Ruby Tutorial

h2. A Quick Tour

h4. Using the RubyGem

All of the code here assumes that you have already executed the following Ruby code:

{code}require 'rubygems' # not necessary for Ruby 1.9
require 'mongo'
{code}
h4. Making a Connection

An Mongo::Connection instance represents a connection to MongoDB. You use a Connection instance to obtain an Mongo:DB instance, which represents a named database. The database doesn't have to exist - if it doesn't, MongoDB will create it for you.

You can optionally specify the MongoDB server address and port when connecting. The following example shows three ways to connect to the database "mydb" on the local machine:

{code}db = Mongo::Connection.new.db("mydb")
db = Mongo::Connection.new("localhost").db("mydb")
db = Mongo::Connection.new("localhost", 27017).db("mydb")

MongoDB can be run in a secure mode where access to databases is controlled through name and password authentication. When run in this mode, any client application must provide a name and password before doing any operations. In the Ruby driver, you simply do the following with the connected mongo object:

{code}auth = db.authenticate(my_user_name, my_password)
{code}If the name and password are valid for the database, {{auth}} will be {{true}}. Otherwise, it will be {{false}}. You should look at the MongoDB log for further information if available.

h4. Getting a List Of Collections

Each database has zero or more collections. You can retrieve a list of them from the db (and print out any that are there):

{code}db.collection_names.each { |name| puts name }
{code}and assuming that there are two collections, name and address, in the database, you would see

{code}name
address
{code}as the output.

h4. Getting a Collection

You can get a collection to use using the {{collection}} method:
{code}coll = db.collection("testCollection")
{code}This is aliased to the \[\] method:
{code}coll = db["testCollection"]
{code}Once you have this collection object, you can now do things like insert data, query for data, etc.

h4. Inserting a Document

Once you have the collection object, you can insert documents into the collection. For example, lets make a little document that in JSON would be represented as

{code}{
"name" : "MongoDB",
"type" : "database",
"count" : 1,
"info" : {
x : 203,
y : 102
}
}
{code}Notice that the above has an "inner" document embedded within it. To do this, we can use a Hash or the driver's OrderedHash (which preserves key order) to create the document (including the inner document), and then just simply insert it into the collection using the {{insert()}} method.

{code}doc = {"name" => "MongoDB", "type" => "database", "count" => 1,
"info" => {"x" => 203, "y" => '102'}}
coll.insert(doc)
{code}

puts my_doc.inspect

h4. Counting Documents in a Collection

Now that we've inserted 101 documents (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.

{code}puts coll.count()
{code}and it should print {{101}}.

{code}and that should print all 101 documents in the collection.

h4. Getting a Single Document with a Query

We can create a _query_ hash to pass to the {{find()}} method to get a subset of the documents in our collection. For example, if we wanted to find the document for which the value of the "i" field is 71, we would do the following ;

{code}coll.find("i" => 71).each { |row| puts row.inspect }

We can use the query to get a set of documents from our collection. For example, if we wanted to get all documents where "i" > 50, we could write:

{code}coll.find("i" => {"$gt" => 50}).each { |row| puts row }
{code}which should print the documents where i > 50. We could also get a range, say 20 < i <= 30:

{code}coll.find("i" => {"$gt" => 20, "$lte" => 30}).each { |row| puts row }
{code}
h4. Querying with Regular Expressions

Regular expressions can be used to query MongoDB. To find all names that begin with 'a':

{code}coll.find({"name" => /^a/})
{code}

You can also construct a regular expression dynamically. To match a given search string:

{code}
search_string = params['search']

# Constructor syntax
coll.find({"name" => Regexp.new(search_string)})

# Literal syntax
coll.find({"name" => /#{search_string}/})

MongoDB supports indexes, and they are very easy to add on a collection. To create an index, you specify an index name and an array of field names to be indexed, or a single field name. The following creates an ascending index on the "i" field:

{code}# create_index assumes ascending order; see method docs
# for details
coll.create_index("i")
{code}To specify complex indexes or a descending index you need to use a slightly more complex syntax - the index specifier must be an Array of [field name, direction] pairs. Directions should be specified as Mongo::ASCENDING or Mongo::DESCENDING:

You can get a list of the indexes on a collection using {{coll.index_information()}}.