NAME

  ObjStore::Table2 - Simulated RDBMS Tables

SYNOPSIS

  # posh 1.21 (Perl 5.00454 ObjectStore Release 5.0.1.0)
  cd table-test ObjStore::Table2::Database

  my $a = $db->array; for (1..10) { $a->_Push({row => $_}) }

  $db->table->new_index('Field', 'row');
  $db->table->build_indices;

DESCRIPTION

 $at = TABLE ObjStore::Table2 {
  [10] of ObjStore::HV {
    row => 1,
  },
  indices: ROW;
 },

Unstructured perl databases are probably under-constrained for most applications. Tables standardize the interface for storing a bunch of records and their associated indices.

Raw Representation

 $at = ObjStore::Table2 {
  _array => ObjStore::AV [
    ObjStore::HV {
      row => 1,
    },
    ObjStore::HV {
      row => 2,
    },
    ObjStore::HV {
      row => 3,
    },
    ...
  ],
  _index_segments => 1,
  row => ObjStore::Table::Index::Field {
    _field => 'row',
    _name => 'row',
    _segment => 6,
    _table => ObjStore::Ref => ObjStore::Table2 ...
    ctime => 882030349,
    map => ObjStore::HV {
      1 => ObjStore::HV ...
      10 => ObjStore::HV ...
      2 => ObjStore::HV ...
      ...
    },
    row => ObjStore::HV ...
  },
 },

API

• $t->add($e)

  Adds $e to the table and updates indices.

• $t->remove($e)

  Removes $e from the table and updates indices.

• $t->index($index_name)

  Returns the index named $index_name.

• $t->fetch($index_name, $key)

  Returns the record resulting from looking up $key in the index named $index_name.

• $t->index_segments($yes)

  Indices can be allocated in their own segments or in the same segment as the table array. The default is to use separate segments.

• $t->new_index($type, @ARGS)

  Creates an index of type $type using @ARGS and adds it to the table.

• $t->add_index($index)

  Adds the given index to the table.

• $t->remove_index($index)

• $t->build_indices

• $t->rebuild_indices

• $t->drop_indices

• $t->repair_indices($rec, $array_index)

  Attempt to repair all indices after a change at $array_index. $rec is the record that was added or deleted at $array_index.

• $t->map_indices($coderef)

  Invokes $coderef->($index) over each index.

Representation Independent API

A database can essentially be a table or tables can be stored within a database. The implementation is only slightly different in either case. To smooth things over, a few accessor methods are provided that always work consistently.

• $t->table

  Returns the top-level hash.

ObjStore::Table::Index

Base class for indices.

• $class->new($table, $name)

  Adds an index called $name to the given table.

• $i->name

  Returns the name of the index.

• $i->table

  Returns the table to which the index is attached.

• $i->build

• $i->is_built

• $i->drop

  Frees the index but preserves enough information to rebuild it.

• $i->rebuild

• $i->set_index_segment($segment)

  Sets the segment where the index will be created. May only be called once. A different API will be available for multisegment indices.

ObjStore::Table::Index::Field - DEPRECIATED

  $table->new_index('Field', $name, $field)

A basic unique index over all records. $field is an access path into the records to be indexed. For example, if your records looks like this:

  { f1 => [1,2,3] }

The access path would be "f1->0" to index the zeroth element of the array at hash key f1.

ObjStore::Table::Index::GroupBy - DEPRECIATED

  $table->new_index('GroupBy', $name, $field);

Groups all records into arrays indexed by $field. $field is an access path into the records to be indexed.

MIGRATION

Both ObjStore::HV::Database and ObjStore::Table are bless-migratible to ObjStore::Table2.

The old ObjStore::Table stored all indices in a hash under the top-level. Table2 stores them directly in the top-level. This should make index lookups slightly more efficient.

BUGS

Usage is a bit more cumbersome than I would like. The interface will change slightly as perl supports more overload-type features.

TODO

• B-Trees desperately needed!

• A table is essentially a collection of indices over the same elements whereby the indices are updated to reflect changes in the elements.

  Like an event manager! You submit events when your records change. There are various ways to repair the table.

  You cannot drop all indices because elements are not stored elsewhere.

• Automatic index maintanance: the array will be overloaded so adds/deletes trigger index updates

• More built-in index types

cpanm ObjStore

perl -MCPAN -e shell
install ObjStore