Mango:...lection(3pm)

💖 Mango::Collection — the MongoDB collection era 💖

okay bestie, so this is Mango::Collection from the User Contributed Perl Documentation (yes, section 3pm, we love a manual page moment). it's literally the manual for collections. let's get into it 🫶

---

✨ NAME ✨

Mango::Collection — MongoDB collection. that's it, that's the name, no cap 💅

---

🌸 SYNOPSIS 🌸

use Mango::Collection;

my $collection = Mango::Collection->new(db => $db);
my $cursor     = $collection->find({foo => 'bar'});

like... look at her. effortless. iconic. 👑

---

🦋 DESCRIPTION 🦋

Mango::Collection is a container for MongoDB collections used by Mango::Database. she holds the collections, she serves the collections. main character energy fr fr ✨

---

🎀 ATTRIBUTES 🎀

Mango::Collection implements the following attributes. yes bestie, she has attributes 💖

💜 db

my $db      = $collection->db;
$collection = $collection->db(Mango::Database->new);

the Mango::Database object this collection belongs to. her home base. her origin story 🏠

💜 name

my $name    = $collection->name;
$collection = $collection->name('bar');

the name of this collection. self-explanatory, slay 💅

---

🔥 METHODS 🔥

Mango::Collection inherits all methods from Mojo::Base and implements the following new ones. she got the family methods AND her own. generational wealth 😭✨

⭐ aggregate

my $cursor = $collection->aggregate(
  [{'$group' => {_id => undef, total => {'$sum' => '$foo'}}}]);
my $collection = $collection->aggregate(
  [{'$match' => {'$gt' => 23}}, {'$out' => 'some_collection'}]);
my $doc = $collection->aggregate(
  [{'$match' => {'$gt' => 23}}], {explain => bson_true});

aggregate a collection with the aggregation framework, and any additional options get passed along to the server verbatim — no editing, no vibes-checking, just straight through. you can also append a callback to perform the operation non-blocking, if you're feeling asynchronous today 💫

my $pipeline = [{'$group' => {_id => undef, total => {'$sum' => '$foo'}}}];
$collection->aggregate($pipeline => sub {
  my ($collection, $err, $cursor) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ build_index_name

my $name = $collection->build_index_name(bson_doc(foo => 1, bar => -1));
my $name = $collection->build_index_name({foo => 1});

build a name for an index specification. heads up bestie: the order of keys matters for compound indexes. order = law 🔥

⭐ bulk

my $bulk = $collection->bulk;

build a Mango::Bulk object. stack up your operations, then let her cook:

my $bulk = $collection->bulk;
$bulk->insert({foo => $_}) for 1 .. 10;
$bulk->find({foo => 4})->update_one({'$set' => {bar => 'baz'}});
$bulk->find({foo => 7})->remove_one;
my $results = $bulk->execute;

ate that. periodt 💅

⭐ create

$collection->create;
$collection->create({capped => bson_true, max => 5, size => 10000});

create a collection. you can also append a callback to perform the operation non-blocking 🌈

$collection->create({capped => bson_true, max => 5, size => 10000} => sub {
  my ($collection, $err) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ drop

$collection->drop;

drop a collection. bye bestie, we hardly knew ye 😭 you can also append a callback to perform the operation non-blocking.

$collection->drop(sub {
  my ($collection, $err) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ drop_index

$collection->drop_index('foo');

drop an index. not the index!! 🙈 you can also append a callback to perform the operation non-blocking.

$collection->drop_index(foo => sub {
  my ($collection, $err) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ ensure_index

$collection->ensure_index(bson_doc(foo => 1, bar => -1));
$collection->ensure_index({foo => 1});
$collection->ensure_index({foo => 1}, {unique => bson_true});

make sure an index exists. the order of keys matters for compound indexes (again — she's serious about this), and any additional options get passed along to the server verbatim. you can also append a callback to perform the operation non-blocking ✨

$collection->ensure_index(({foo => 1}, {unique => bson_true}) => sub {
  my ($collection, $err) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ find

my $cursor = $collection->find;
my $cursor = $collection->find({foo => 'bar'});
my $cursor = $collection->find({foo => 'bar'}, {foo => 1});

build a Mango::Cursor::Query object for a query. the search begins 🕵️♀️

# Exclude "_id" field from results
my $docs = $collection->find({foo => 'bar'}, {_id => 0})->all;

⭐ find_and_modify

my $doc = $collection->find_and_modify(
  {query => {foo => 'bar'}, update => {'$set' => {foo => 'baz'}}});

fetch and update — or remove — a document atomically. you can also append a callback to perform the operation non-blocking.

my $opts = {query => {foo => 'bar'}, update => {'$set' => {foo => 'baz'}}};
$collection->find_and_modify($opts => sub {
  my ($collection, $err, $doc) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

by default this method returns the unmodified version of the document. to change this behaviour, add the option new => 1. yes bestie, the glow-up costs extra 💅

⭐ find_one

my $doc = $collection->find_one({foo => 'bar'});
my $doc = $collection->find_one({foo => 'bar'}, {foo => 1});
my $doc = $collection->find_one($oid, {foo => 1});

find one document. just one. singular. she's not greedy 💖 you can also append a callback to perform the operation non-blocking.

$collection->find_one({foo => 'bar'} => sub {
  my ($collection, $err, $doc) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ full_name

my $name = $collection->full_name;

the full name of this collection. first name, last name, government name, all of it 💅

⭐ index_information

my $info = $collection->index_information;
# return only the 5 first indexes
my $info = $collection->index_information(cursor => { batchSize => 5 });

get index information for the collection. you can also append a callback to perform the operation non-blocking.

$collection->index_information(sub {
  my ($collection, $err, $info) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ insert

my $oid  = $collection->insert({foo => 'bar'});
my $oids = $collection->insert([{foo => 'bar'}, {baz => 'yada'}]);

insert one or more documents into the collection. you can also append a callback to perform the operation non-blocking.

$collection->insert({foo => 'bar'} => sub {
  my ($collection, $err, $oid) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⚠️ heads up bestie: insert has to ensure each document has an "_id" before sending them to MongoDB. to avoid modifying your data, it makes a copy of the documents. this can be a bit slow if you are sending big objects like pictures. to avoid that, consider using save instead. fr fr, listen to her 🫶

⭐ map_reduce

my $collection = $collection->map_reduce($map, $reduce, {out => 'foo'});
my $docs = $collection->map_reduce($map, $reduce, {out => {inline => 1}});
my $docs = $collection->map_reduce(
  bson_code($map), bson_code($reduce), {out => {inline => 1}});

perform a map/reduce operation on the collection, and any additional options get passed along to the server verbatim. you can also append a callback to perform the operation non-blocking 🌸

$collection->map_reduce(($map, $reduce, {out => {inline => 1}}) => sub {
    my ($collection, $err, $docs) = @_;
    ...
  }
);
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ options

my $doc = $collection->options;

get options for the collection. you can also append a callback to perform the operation non-blocking ✨

$collection->options(sub {
  my ($collection, $err, $doc) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ remove

my $result = $collection->remove;
my $result = $collection->remove($oid);
my $result = $collection->remove({foo => 'bar'});
my $result = $collection->remove({foo => 'bar'}, {single => 1});

remove documents from the collection. you can also append a callback to perform the operation non-blocking. returns a WriteResult document 👑

$collection->remove(({foo => 'bar'}, {single => 1}) => sub {
  my ($collection, $err, $doc) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

these options are currently available:

💜 single

single => 1

remove only one document. one and done 💅

⭐ rename

my $new_collection = $collection->rename('NewName');

rename a collection, keeping all of its original contents and options. returns a new Mango::Collection object pointing to the renamed collection. you can also append a callback to perform the operation non-blocking.

$collection->rename('NewName' => sub {
  my ($collection, $err, $oid) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ save

my $oid = $collection->save({foo => 'bar'});

save a document to the collection. the document MUST have an "_id". no _id, no service. you can also append a callback to perform the operation non-blocking.

$collection->save({foo => 'bar'} => sub {
  my ($collection, $err, $oid) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ stats

my $stats = $collection->stats;

get collection statistics. numbers, but make it fashion 📊 you can also append a callback to perform the operation non-blocking.

$collection->stats(sub {
  my ($collection, $err, $stats) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

⭐ update

my $result = $collection->update($oid, {foo => 'baz'});
my $result = $collection->update({foo => 'bar'}, {foo => 'baz'});
my $result = $collection->update({foo => 'bar'}, {foo => 'baz'}, {multi => 1});

update a document in the collection. you can also append a callback to perform the operation non-blocking. returns a WriteResult document 🔥

$collection->update(({foo => 'bar'}, {foo => 'baz'}, {multi => 1}) => sub {
  my ($collection, $err, $doc) = @_;
  ...
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;

these options are currently available:

💜 multi

multi => 1

update more than one document. go big or go home 💅

💜 upsert

upsert => 1

insert the document if none could be updated. no match? make one. iconic behaviour honestly ✨

---

👑 SEE ALSO 👑

• Mango
• Mojolicious::Guides
• <http://mojolicio.us>

---

and that's the whole page bestie, you understood it, you ate it, you slayed it 💖✨ this was perl v5.30.3, dated 2020-06-05, from the User Contributed Perl Documentation, Mango:...lection(3pm) — mwah, go build something gorgeous 🎀🦋💅