Provided by: libmongodb-perl_1.8.1-1_amd64 
NAME
MongoDB::Tutorial - Getting started with MongoDB
VERSION
version v1.8.1
DESCRIPTION
The tutorial runs through the basic functionality of the MongoDB package. This is a good
starting point if you have never used MongoDB before.
The tutorial assumes that you are running a standalone MongoDB database server (i.e. not a
replica set) locally on the default port. You can download MongoDB from
<http://www.mongodb.org>.
TERMINOLOGY
Document-oriented database terms and their relational equivalents:
Database
Database
Collection
Table
Document
Record or row
MongoDB::OID
Autoincrementing primary key
PREAMBLE
To use MongoDB, you'll usually just start with:
use MongoDB;
The MongoDB module loads most of the modules you'll need to interact with MongoDB:
• MongoDB::MongoClient
• MongoDB::Database
• MongoDB::Collection
• Query result classes like MongoDB::Cursor and MongoDB::QueryResult
• Write result classes like MongoDB::InsertOneResult and MongoDB::UpdateResult
CONNECTING
To get started, we have to connect to the database server. Because it's running locally
on the default port, we need not pass any parameters to the connect method.
my $client = MongoDB->connect();
Now we we have a client connected to the MongoDB server. Next we need a database to work
with, we'll call it "tutorial". You need not do anything special to create the database,
MongoDB will create it on the fly.
my $db = $client->get_database( 'tutorial' );
The last part of the preliminary setup is to choose a collection. We'll be using the
"users" collection to start out.
my $users = $db->get_collection( 'users' );
Again, there is no need to create the collection in advance, it will be created as needed.
The ns method is a short cut to get a MongoDB::Collection object direct from the client.
my $users = $client->ns("tutorial.users");
CRUD
Creating Documents
Inserting
To add a document to the collection, we use the insert_one function. It takes a hash
reference which is saved to the collection.
$users->insert_one( {
"name" => "Joe",
"age" => 52,
"likes" => [qw/skiing math ponies/]
});
Now there is a user in the collection.
MongoDB::OIDs
When a document is inserted, it is given a "_id" field if one does not already exist. By
default, this field is a MongoDB::OID, 12 bytes that are guaranteed to be unique. The
"_id" field of the inserted document is returned in a MongoDB::InsertOneResult object by
the "insert_one" method.
my $result = $users->insert_one({"name" => "Bill"});
my $id = $result->inserted_id;
An efficient way to insert documents is to send many at a time to the database by using
insert_many, which returns a MongoDB::InsertManyResult describing the documents inserted.
my $result = $users->insert_many(\@many_users);
Retrieving Documents
Queries
To retrieve documents that were saved to a collection, we can use the find method.
my $all_users = $users->find;
To query for certain criteria, say, all users named Joe, pass the query a hash with the
key/value pair you wish to match:
my $some_users = $users->find({"name" => "Joe"});
You can match array elements in your queries; for example, to find all users who like
math:
my $geeks = $users->find({"likes" => "math"});
This being Perl, it is important to mention that you can also use regular expressions to
search for strings. If you wanted to find all users with the name John and all variations
of said name, you could do:
my $john = $users->find({"name" => qr/joh?n/i});
See "Regular Expressions" in MongoDB::DataTypes for more information.
Ranges
As queries are hashes, they use a special syntax to express comparisons, such as "x < 4".
To make the query a valid hash, MongoDB uses $-prefixed terms. For example, "x < 4" could
be expressed by:
my $doc321 = $collection->find({'x' => { '$lt' => 4 }});
Comparison operators can be combined to get a range:
my $doc32 = $collection->find({'x' => { '$gte' => 2, '$lt' => 4 }});
Cursors
"find" returns a MongoDB::Cursor, which can be iterated over. It lazily loads results
from the database. The following prints all of the users' names:
while (my $doc = $all_users->next) {
print $doc->{'name'}."\n";
}
A cursor can also be converted into an array of hash references. For example, to print
the "name" field of the first result:
my @arr = $geeks->all;
print $arr[0]->{'name'}."\n";
Updating Documents
"$"-operators
To change a document after it has been saved to the database, you must pass update_one (or
update_many to change many documents at once) two arguments. The first is a query
argument, identical to the previous section, to identify the document you want to change.
The second is an argument that describes the change that you wish to make.
The change is described by $-prefixed descriptors. For example, to increment a field, we
would write:
$users->update_one({"_id" => $id}, {'$inc' => {'age' => 1}});
To add an element to an array, we can use $push. So, to add an element to the "likes"
array, we write:
$users->update_one({"_id" => $id}, {'$push' => {'likes' => 'reading'}});
To add a new field or change the type or value of an existing field, we use $set. For
example, to change the "name" field to a username, we would say:
$users->update_one({"_id" => $id}, {'$set' => {'name' => 'joe_schmoe'}});
Options
"update_one" and "update_many" do nothing if no document matches the query.
Sometimes we may want update to create an element if it does not already exist. This is
called an 'upsert' (a combination of an update and an insert). For example, the same code
could be used for creating and updating a log document:
$pageviews->update_one(
{"url" => "www.example.com"},
{'$inc' => {"views" => 1}},
{'upsert' => 1}
);
If the pageview counter for www.example.com did not exist yet, it would be created and the
"views" field would be set to 1. If it did exist, the "views" field would be incremented.
Deleting Documents
To delete documents, we use the delete_one or delete_many methods. They take the same
type of hash queries do:
$users->delete_many({"name" => "Joe"});
It does not delete the collection, though (in that it will still appear if the user lists
collections in the database and the indexes will still exist). To remove a collection
entirely, call "drop":
$users->drop;
"drop" can also be used for whole databases:
$db->drop;
MONGODB BASICS
Database Commands
There is a large number of useful database commands that can be called directly on $db
with the run_command method.
For example, you can use a database command to create a capped collection like so:
use boolean; # imports 'true' and 'false'
my $cmd = [
create => "posts",
capped => true,
size => 10240,
max => 100
];
$db->run_command($cmd);
This will create a capped collection called "posts" in the current database. It has a
maximum size of 10240 bytes and can contain up to 100 documents. The boolean module must
be used whenever the database expects an actual boolean argument (i.e. not "1" or "0").
MongoDB expects commands to have key/value pairs in a certain order, so you must give
arguments in an array reference (or Tie::IxHash object).
NEXT STEPS
Now that you know the basic syntax used by the Perl driver, you should be able to
translate the JavaScript examples in the main MongoDB documentation
(<http://www.mongodb.org>) into Perl.
Check out MongoDB::Examples for more examples.
AUTHORS
• David Golden <david@mongodb.com>
• Rassi <rassi@mongodb.com>
• Mike Friedman <friedo@friedo.com>
• Kristina Chodorow <k.chodorow@gmail.com>
• Florian Ragwitz <rafl@debian.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2018 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004