Catman...ongoDB(3pm)

💖 Catman...ongoDB(3pm) 💖

okay bestie, sit down, hydrate, and let's talk about Catmandu::Store::MongoDB — a searchable store backed by MongoDB. This one lives in the User Contributed Perl Documentation corner of the world and it is genuinely iconic. 🦋

---

✨ SYNOPSIS ✨

first up, the command line era — look how easy this is:

# On the command line
$ catmandu import -v JSON --multiline 1 to MongoDB --database_name bibliography --bag books < books.json
$ catmandu export MongoDB --database_name bibliography --bag books to YAML
$ catmandu count MongoDB --database_name bibliography --bag books --query '{"PublicationYear": "1937"}'
$ catmandu count MongoDB --database_name bibliography --bag books --query '{"Author": "Jones"}' --sort '{"PublicationYear":1}'

and now the perl era, where we get comfy 💅

# In perl
use Catmandu::Store::MongoDB;

my $store = Catmandu::Store::MongoDB->new(database_name => 'test');

my $obj1 = $store->bag->add({ name => 'Patrick' });

printf "obj1 stored as %s\n" , $obj1->{_id};

# Force an id in the store
my $obj2 = $store->bag->add({ _id => 'test123' , name => 'Nicolas' });

my $obj3 = $store->bag->get('test123');

$store->bag->delete('test123');

$store->bag->delete_all;

# All bags are iterators
$store->bag->each(sub { ... });
$store->bag->take(10)->each(sub { ... });

# Search
my $hits = $store->bag->search(query => '{"name":"Patrick"}');
my $hits = $store->bag->search(query => '{"name":"Patrick"}' , sort => { age => -1} );
my $hits = $store->bag->search(query => {name => "Patrick"} , start => 0 , limit => 100);
my $hits = $store->bag->search(query => {name => "Patrick"} , fields => {_id => 0, name => 1});

my $next_page = $hits->next_page;
my $hits = $store->bag->search(query => '{"name":"Patrick"}' , page => $next_page);

my $iterator = $store->bag->searcher(query => {name => "Patrick"});
my $iterator = $store->bag->searcher(query => {name => "Patrick"}, fields => {_id => 0, name => 1});

# Catmandu::Store::MongoDB supports CQL...
my $hits = $store->bag->search(cql_query => 'name any "Patrick"');

not me re-reading that last line like… CQL support? we love to see it. 😭

---

🌸 DESCRIPTION 🌸

So a Catmandu::Store::MongoDB is a Perl package that can store data into MongoDB databases. big main character energy. The database as a whole is called a 'store', and databases also have compartments (e.g. tables) called Catmandu::Bag-s. 🎀

---

🧚 CONFIGURATION 🧚

database_name

MongoDB database name. (yes, that's the whole vibe check.)

estimate_count

Use a faster estimated collection document count if true. ⚡

and every other option? it just gets passed on to the MongoDB client. no gatekeeping. 🫶

---

👑 METHODS 👑

new(database_name => $name, %connection_opts)

new(database_name => $name , bags => { data => { cql_mapping => $cql_mapping } })

Create a new Catmandu::Store::MongoDB store with name $name. Optionally you can hand over connection parameters too — peep MongoDB::MongoClient for all the possible options bestie. 💜

The store supports CQL searches when a cql_mapping is provided. This hash contains a translation of CQL fields into MongoDB searchable fields. the way that works…

# Example mapping
$cql_mapping = {
    indexes => {
         title => {
           op => {
             'any'   => 1 ,
             'all'   => 1 ,
             '='     => 1 ,
             '<>'    => 1 ,
             'exact' => {field => [qw(mytitle.exact myalttitle.exact)]}
           } ,
           sort  => 1,
           field => 'mytitle',
           cb    => ['Biblio::Search', 'normalize_title']
         }
   }
}

So the CQL mapping above will support the CQL operators for the 'title' field:

any, all, =, <> and exact.

The 'title' field will be mapped into the MongoDB field 'mytitle', except for the 'exact' operator. In the case of 'exact', both the 'mytitle.exact' and 'myalttitle.exact' fields will be searched. 🔍

The CQL mapping also allows for sorting on the 'title' field. If, for instance, we'd like to use a special MongoDB field for sorting, we could have written "sort => { field => 'mytitle.sort' }". 💅

The CQL has an optional callback field 'cb' which contains a reference to subroutines to rewrite or augment the search query. In this case, the Biblio::Search package contains a normalize_title subroutine which returns a string or an ARRAY of string with augmented title(s). E.g.

package Biblio::Search;

sub normalize_title {
   my ($self,$title) = @_;
   # delete all bad characters
   my $new_title =~ s{[^A-Z0-9]+}{}g;
   $new_title;
}

1;

bag($name)

Create or retrieve a bag with name $name. Returns a Catmandu::Bag. 🎀

client

Return the MongoDB::MongoClient instance. 🧚

database

Return a MongoDB::Database instance. 🦋

drop

Delete the store and all it's bags. yes, ALL of them. no takebacks. 💀

transaction(\&sub)

Execute $sub within a transaction. See Catmandu::Transactional.

⚠️ heads up bestie: note that only MongoDB databases with feature compatibility >= 4.0 and in a replica set have support for transactions. See <https://docs.mongodb.com/manual/reference/command/setFeatureCompatibilityVersion/#view-fcv> and <https://docs.mongodb.com/manual/tutorial/convert-standalone-to-replica-set/> for more info. 🙈

Search

Search the database: see Catmandu::Searchable and Catmandu::CQLSearchable. This module supports an additional search parameter:

- fields => { <field> => <0|1> } : limit fields to return from a query (see L<MongoDB Tutorial|https://docs.mongodb.org/manual/tutorial/project-fields-from-query-results/>)

---

🌈 SEE ALSO 🌈

the whole friend group, fr fr:

• Catmandu::Bag
• Catmandu::CQLSearchable
• Catmandu::Droppable
• Catmandu::Transactional
• MongoDB::MongoClient

---

💜 AUTHOR 💜

Nicolas Steenlant, "<nicolas.steenlant at ugent.be>"

---

🫶 CONTRIBUTORS 🫶

Johann Rolschewski, "<jorol at cpan.org>"

---

📜 LICENSE AND COPYRIGHT 📜

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

---

and that's the whole page bestie!! ✨ this one's sitting pretty at perl v5.32.1 and dated 2021-09-02 — go forth and store your data, you absolute icon 👑💖