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

# Catmandu::Bag(3pm)

A Catmandu::Store compartment to persist data

## NAME

Catmandu::Bag - A Catmandu::Store compartment to persist data

## SYNOPSIS

```
    my $store = Catmandu::Store::DBI->new(data_source => 'DBI:mysql:database=test');
    my $store = Catmandu::Store::DBI->new(
            data_source => 'DBI:mysql:database=test',
            bags => { journals => {
                            fix => [ ... ] ,
                            autocommit => 1 ,
                            plugins => [ ... ] ,
                            id_generator => Catmandu::IdGenerator::UUID->new ,
                      }
                    },
            bag_class => Catmandu::Bag->with_plugins('Datestamps')
            );
    # Use the default bag...
    my $bag = $store->bag;
    # Or a named bag...
    my $bag = $store->bag('journals');
    # Every bag is an iterator...
    $bag->each(sub { ... });
    $bag->take(10)->each(sub { ... });
    $bag->add($hash);
    $bag->add_many($iterator);
    $bag->add_many([ $hash, $hash , ...]);
    # Commit changes...
    $bag->commit;
    if ($bag->exists($id)) {
        # ...
    }
    my $obj = $bag->get($id);
    $bag->delete($id);
    $bag->delete_all;
```

## CONFIGURATION

- fix

  Contains an array of fixes (or Fix files) to be applied before importing data into the bag.

- plugins

  An array of Catmandu::Pluggable to apply to the bag items.

- autocommit

  When set to a true value an commit automatically gets executed when the bag goes out of scope.

- id\_generator

  A Catmandu::IdGenerator or name of an IdGenerator class. By default Catmandu::IdGenerator::UUID is used.

- id\_key

  Use a custom key to hold id's in this bag. See Catmandu::Store for the default or store wide value. Also aliased as `"id_field"`.

## METHODS

### add($hash)

Add a hash to the bag or updates an existing hash by using its '\_id' key. Returns the stored hash on success or undef on failure.

### add\_many($array)

### add\_many($iterator)

Add or update one or more items to the bag.

### get($id)

Retrieves the item with identifier `$id` from the bag.

### exists($id)

Returns `1` if the item with identifier `$id` exists in the bag.

### get\_or\_add($id, $hash)

Retrieves the item with identifier `$id` from the store or adds `$hash` with \_id `$id` if it's not found.

### delete($id)

Deletes the item with `$id` from the bag.

### delete\_all

Clear the bag.

### touch($key, $format)

Add the current datetime to each record.

```
    $bag->touch('date_updated', 'iso_date_time');
```

See Catmandu::Util::now for possible format values.

### commit

Commit changes.

### log

Return the current logger.

## CLASS METHODS

### with\_plugins($plugin)

### with\_plugins(\\@plugins)

Plugins are a kind of fixes that should be available for each bag. E.g. the Datestamps plugin will automatically store into each bag item the fields 'date\_updated' and 'date\_created'. The with\_plugins accept one or an array of plugin classnames and returns a subclass of the Bag with the plugin methods implemented.

## SEE ALSO

Catmandu::Iterable, Catmandu::Searchable, Catmandu::Fix, Catmandu::Pluggable