Eric Wolf
and 1 contributors


Data::ObjectStore - store perl objects, hashes and arrays in a rooted tree on-disc.


If you have structured data you want to store, store it in an object store. Have really huge arrays or hashes? No problem, those are chunked in batches. They're neatly TIED and loaded as needed.

Add to, remove from or update the structure and the store knows. A single method brings it all of it up to date.


 use Data::ObjectStore;

 my $store = Data::ObjectStore::open_store( '/path/to/data-directory' );

 my $root_container = $store->load_root_container;

 my $current_data = [ 123,123,345,45,3752,346,326,43745,76 ];

 # get_experiment and set_experiment automagically work.
 my $experiment = $root_container->get_expirement;
 unless( $experiment ) {
   # My::Experiment @ISA Data::ObjectStore::Container
   $experiment = $root_container->set_expirement(
             $store->create_container( 'My::Experiment' )

 # returns val if val is defined.
 # If val isn't defined, it sets val to 'default value' and returns it.
 my $val = $experiment->get_val( 'default value' );

 $experiment->set( "note", "this is identical to 'set_note'" );

 # creates data_sets list or uses existing one
 $experiment->add_to_data_sets( $current_data );


 # forgot a point! Add to the current data and save it.
 push @$current_data, 234;


 my $data_sets = $store->load_root_container
 for my $set (@$data_sets) {


Blessed objects must be a subclass of Data::ObjectStore::Container in order to be able to be stored in the object store. _init and _load can be useful to override.

 package Mad::Science::User;
 use Data::ObjectStore;
 use base 'Data::ObjectStore::Container';

 # called when an object is newly created
 sub _init {
   my $self = shift;
   $self->set_status( "NEWLY CREATED" );

 # called when the object is loaded from the store
 sub _load {
   my $self = shift;
   print "Loaded " . $self->get_name . " from store";
   if( @{$self->get_experiments} > 0 ) {
     $self->set_status( "DOING EXPERIMENTS" );

 sub evacuate {
   my $self = shift;
   $self->set_status( "HEADING FOR THE HILLS" );


open_store( '/path/to/directory' )

Starts up a persistance engine that stores data in the given directory and returns it.


Fetches the root node of the store, a Data::ObjectStore::Container object.


Returns a hash of info about this opened data store. Updating the hash has no effect.

 * db_version
 * ObjectStore_version
 * created_time
 * last_update_time


Returns the version of Data::RecordStore that this was created under.


Returns the version of Data::ObjectStore that this was created under.


Returns when the store was created.


Returns the last time this store was updated.

create_container( optionalClass, { data } )

Returns a new Data::ObjectStore::Container container object or a subclass, depending if the optional class parameter is supplied. If provided with data, the object is initialized with the data.

If the object is attached to the root or a container that is ultimately attached to the root, it will be saved when save is called.


This checks for objects that are not traceable to the root object and removes them, recycling thier ids.


When called, this stores all objects that have been changed since the last time save was called.


 Persistant Perl container object.


 $obj_A = $store->create_container;

 $obj_B = $store->create_container( {
                          myfoo  => "This foo is mine",
                          mylist => [ "A", "B", "C" ],
                          myhash => { peanut => "Butter" } 
                                  } );

 $obj_C = $store->create_container( 'My::Subclass' );

 $obj_D = $store->create_container( 'My::Othersubclass', { initial => "DATA" } );

 # get operations
 print $obj_B->get_myfoo; # prints "this foo is mine"

 print $obj_B->get( "myfoo" ); # prints "this foo is mine"

 print $obj_B->get_myhash->{peanut}; # prints 'butter'

 $val = $obj_A->get_val; # $val is now undef

 $val = $obj_A->get_val("default"); # $val is now 'default'

 $val = $obj_A->get_Val("otherdefault"); # $val is still 'default'

 $val = $obj_A->set_arbitraryfield( "SOMEVALUE" ); # $val is 'SOMEVALUE'

 # set operations
 $obj_C->set( "MYSET", "MYVAL" );
 $val = $obj_C->get_MYSET; # $val is 'MYVAL'

 $obj_B->set_A( $obj_A );

 $root = $store->load_root_container;

 $root->set_B( $obj_B );

 # list operations
 $mylist = $obj_B->add_to_mylist( "D" ); #mylist now 'A','B','C','D'

 $newlist = $obj_B->add_to_newlist( 1, 2, 3, 3, 3 );
 print join(",", $newlist);  # prints 1,2,3,3,3

 $obj_B->remove_from_newlist( 3 );
 print join(",", $newlist);  # prints 1,2,3,3
 $obj_B->remove_all_from_newlist( 3 );
 print join(",", $newlist);  # prints 1,2

 # yes, the $newlist reference is changed when the object is operated on with list operations


This is a container object that can be used to store key value data where the keys are strings and the values can be hashes, arrays or Data::ObjectStore::Container objects. Any instances that can trace a reference path to the store's root node are reachable upon reload.

This class is designed to be overridden. Two methods are provided for convenience. _init is run the first time the object is created. _load is run each time the object is loaded from the data store. These methods are no-ops in the base class.


set( field, value )

Sets the field to the given value and returns the value. The value may be a Data::ObjectStore::Container or subclass, or a hash or array reference.

get( field, default_value )

Returns the value associated with the given field. If the value is not defined and a default value is given, this sets the value to the given default value and returns it.

The value may be a Data::ObjectStore::Container or subclass, or a hash or array reference.


Returns the Data::ObjectStore that created this object.


    This is called the first time an object is created. It is not
    called when the object is loaded from storage. This can be used
    to set up defaults. This is meant to be overridden.


    This is called each time the object is loaded from the data store.
    This is meant to be overridden.

AUTHOR Eric Wolf


       Copyright (c) 2018 Eric Wolf. All rights reserved.  This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

VERSION Version 1.106 (April, 2018))