NAME

       Catmandu::Store - Namespace for packages that can make data persistent

SYNOPSIS

           # From the command line

           $ catmandu import JSON into MongoDB --database_name 'bibliography' < data.json

           $ catmandu export MongoDB --database_name 'bibliography' to YAML
           $ catmandu export MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}'
           $ catmandu count  MongoDB --database_name 'bibliography' --query '{"PublicationYear": "1937"}'

           # From Perl
           use Catmandu;

           my $store = Catmandu->store('MongoDB',database_name => 'bibliography');

           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;

           # Some stores can be searched
           my $hits = $store->bag->search(query => 'name:Patrick');

DESCRIPTION

       A Catmandu::Store is a stub for Perl packages that can store data into databases or search
       engines. The database as a whole is called a 'store'.  Databases also have compartments
       (e.g. tables) called Catmandu::Bag-s.  Some stores can be searched using
       Catmandu::Searchable methods.

CONFIGURATION

       default_plugins
           Specify plugins that will be applied to every bag in the store.

               my $store = Catmandu::Store::MyDB->new(default_plugins => ['Datestamps']);

       default_bag
           The name of the bag to use if no explicit bag is given. Default is 'data'.

               my $store = Catmandu::Store::MyDB->new(default_bag => 'stuff');
               # this will return the stuff bag
               my $bag = $store->bag;

       bags
           Specify configuration for individual bags.

               my $store = Catmandu::Store::Hash->new(
                   bags => {stuff => {plugins => ['Datestamps']}});
               # this bag will use the L<Catmandu::Plugin::Datestamps> role
               $store->bag('stuff')
               # this bag won't
               $store->bag('otherbag')

       bag_class
           An optional custom class to use for bags. Default is "Bag" in the store's namespace.
           This class should consume the Catmandu::Bag role.

               # this will use the Catmandu::Store::MyDB::Bag class for bags
               Catmandu::Store::MyDB->new()
               # this will use MyBag
               Catmandu::Store::MyDB->new(bag_class => 'MyBag')

       key_prefix
           Use a custom prefix to mark the reserved or special keys that the store uses.  By
           default an underscore gets prependend. The only special key in a normal store is
           '_id'. Catmandu::Plugin::Versioning will also use '_version'. Other plugins or stores
           may add their own special keys.

               # this store will use the my_id key to hold id's
               Catmandu::Store::MyDB->new(key_prefix => 'my_')

       id_key
           Define a custom key to hold id's for all bags of this store. See "key_prefix" for the
           default value. Also aliased as "id_field". Note that this can also be overriden on a
           per bag basis.

METHODS

   bag($name)
       Create or retieve a bag with name $name. Returns a Catmandu::Bag.

   key_for($key)
       Helper method that applies "key_prefix" to the $key given.

   log
       Return the current logger. Can be used when creating your own Stores.

       E.g.

           package Catmandu::Store::Hash;

           ...

           sub generator {
               my ($self) = @_;

               $self->log->debug("generating record");
               ...
           }

       See also: Catmandu for activating the logger in your main code.

SEE ALSO

       Catmandu::Bag, Catmandu::Searchable