#
#  Copyright 2009-2013 10gen, Inc.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#


# PODNAME: MongoDB::Tutorial
# ABSTRACT: Getting started with MongoDB

__END__

=pod

=encoding UTF-8

=head1 NAME

MongoDB::Tutorial - Getting started with MongoDB

=head1 VERSION

version v1.8.0

=head1 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 B<standalone> MongoDB database
server (i.e. not a replica set) locally on the default port.  You can
download MongoDB from L<http://www.mongodb.org>.

=head1 TERMINOLOGY

Document-oriented database terms and their relational equivalents:

=over

=item Database

Database

=item Collection

Table

=item Document

Record or row

=item L<MongoDB::OID>

Autoincrementing primary key

=back

=head1 PREAMBLE

To use MongoDB, you'll usually just start with:

    use MongoDB;

The L<MongoDB> module loads most of the modules you'll need to interact
with MongoDB:

=over 4

=item *

L<MongoDB::MongoClient>

=item *

L<MongoDB::Database>

=item *

L<MongoDB::Collection>

=item *

Query result classes like L<MongoDB::Cursor> and L<MongoDB::QueryResult>

=item *

Write result classes like L<MongoDB::InsertOneResult> and L<MongoDB::UpdateResult>

=back

=head1 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
L<connect|MongoDB/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 L<ns|MongoDB::MongoClient/get_namespace> method is a short cut to get
a L<MongoDB::Collection> object direct from the client.

    my $users = $client->ns("tutorial.users");

=head1 CRUD

=head2 Creating Documents

=head3 Inserting

To add a document to the collection, we use the
L<insert_one|MongoDB::Collection/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.

=head3 L<MongoDB::OID>s

When a document is inserted, it is given a C<_id> field if one does not already
exist.  By default, this field is a L<MongoDB::OID>, 12 bytes that are
guaranteed to be unique. The C<_id> field of the inserted document is returned
in a L<MongoDB::InsertOneResult> object by the C<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 L<insert_many|MongoDB::Collection/insert_many>, which
returns a L<MongoDB::InsertManyResult> describing the documents inserted.

    my $result = $users->insert_many(\@many_users);

=head2 Retrieving Documents

=head3 Queries

To retrieve documents that were saved to a collection, we can use the
L<find|MongoDB::Collection/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 L<MongoDB::DataTypes/"Regular Expressions"> for more information.

=head3 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 }});

=head3 Cursors

C<find> returns a L<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";

=head2 Updating Documents

=head3 C<$>-operators

To change a document after it has been saved to the database, you must pass
L<update_one|MongoDB::Collection/update_one> (or
L<update_many|MongoDB::Collection/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 C<$push>.  So, to add an element to
the C<"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
C<$set>.  For example, to change the _id field to a username, we would say:

    $users->update_one({"_id" => $id}, {'$set' => {'name' => 'joe_schmoe'}});

=head3 Options

C<update_one> and C<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.

=head2 Deleting Documents

To delete documents, we use the L<delete_one|MongoDB::Collection/delete_one>
or L<delete_many|MongoDB::Collection/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 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 C<drop>:

    $users->drop;

C<drop> can also be used for whole databases:

    $db->drop;

=head1 MONGODB BASICS

=head2 Database Commands

There are a large number of useful database commands that can be called
directly on C<$db> with the L<run_command|MongoDB::Database/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
L<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 L<Tie::IxHash> object).

=head1 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
(L<http://www.mongodb.org>) into Perl.

Check out L<MongoDB::Examples> for more examples.

=head1 AUTHORS

=over 4

=item *

David Golden <david@mongodb.com>

=item *

Rassi <rassi@mongodb.com>

=item *

Mike Friedman <friedo@friedo.com>

=item *

Kristina Chodorow <k.chodorow@gmail.com>

=item *

Florian Ragwitz <rafl@debian.org>

=back

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by MongoDB, Inc.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

=cut