---
name: "Catmandu::Store"
section: "3pm"
platform: "linux"
package: "libcatmandu-perl"
version: "1.2024-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Catmandu::Store"
---

# Catmandu::Store(3pm)

Namespace for packages that can make data persistent

## 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