NAME

Genezzo::Row::RSTab.pm - Row Source TABle tied hash class.

SYNOPSIS

use Genezzo::Row::RSTab;

# see Tablespace.pm -- implementation and usage is tightly tied
# to genezzo engine...

# make a factory for rsfile
my $fac2 = make_fac2('Genezzo::Row::RSFile');
       
my %args = (
            factory   => $fac2,
            # need tablename, bufcache, etc...
            tablename => ...
            tso       => ...
            bufcache  => ...
                   );

 my %td_hash;
 $tie_val = 
   tie %td_hash, 'Genezzo::Row::RSTab', %args;

# pushhash style 
my @rowarr = ("this is a test", "and this is too");
my $newkey = $tie_val->HPush(\@rowarr);

@rowarr = ("update this entry", "and this is too");
$tied_hash{$newkey} = \@rowarr;

my $getcount = $tie_val->HCount();

DESCRIPTION

RSTab is a hierarchical pushhash (see Genezzo::PushHash::hph) class that stores perl arrays as rows in a table, writing them into a block (byte buffer) via Genezzo::Row::RSFile and Genezzo::Block::RDBlock.

ARGUMENTS

tablename (Required) - the name of the table
tso (Required) - tablespace object from Genezzo::Tablespace
bufcache (Required) - buffer cache object from Genezzo::BufCa::BCFile

CONCEPTS

Logically, a table is made of rows, and rows are vectors of columns. Physically (at least from an OS implementation viewpoint), a table is made up of blocks stored in files. The RSTab hierarchical pushhash (hph) uses an RSFile factory, though it could be constructed as an hph of arbitrary depth. The basic HPush mechanism takes an array, flattens it into a string, and pushes the string into one of the underlying blocks.

While the RSTab api is primarily intended as a row-based interface, it has some extensions to directly manipulate the underlying blocks. These extensions are useful for building specialized index mechanisms (see Genezzo::Index) like B-trees, or for supporting rows that span multiple blocks.

Basic PushHash

You can use RSTab as a persistent hash of arrays of scalars if you like. The arrays and scalars can be of arbitrary length (as long as they fit in your datafiles).

SQL DBI-style interface

RSTab is designed to efficiently support prepare/execute/fetch operations against tables. What distinguishes this API from a standard hash is that the "prepare" operation generates a custom, stateful iterator that understands filters and range selection. A filter is simply a predicate which is applied to every row -- rows which pass are returned to the caller, and rows which fail are "filtered out". Range selection is somewhat similar, with the notion of start and stop keys -- the iterator only returns the rows which are restricted to a certain range of values. In general, range selection is driven off a separate indexing mechanism that positions the fetch to specifically retrieve the range in an efficient manner, versus fetching all rows and filtering rows outside the range.

HPHRowBlk - Row and Block operations

HPHRowBlk is a special pushhash subclass with certain direct block manipulation methods. One very useful function is HSuck, which provides support for rows that span multiple blocks. While the standard HPush fails if a row exceeds the space in a single block, the HSuck api lets the underlying blocks consume the rows in pieces -- each block "sucks up" as much of the row as it can. The RSTab HPush is re-implemented on top of HSuck to support large rows.

Counting, Estimation, Approximation

RSTab has some support for count estimation, inspired by some of Peter Haas' work (Sequential Sampling Procedures for Query Size Estimation, ACM SIGMOD 1992, Online Aggregation (with J. Hellerstein and H. Wang), ACM SIGMOD 1997 Ripple Joins for Online Aggregation (with J. Hellerstein) ACM SIGMOD 1999). It could use support for confidence intervals, so drop me a line if you understand Central Limit Theorem, Hoeffding and Chebyshev inequalites. Knowledge of change-points and time-series is also a plus.

FUNCTIONS

RSTab support all standard hph hierarchical pushhash operations, with the extension that it manipulates arrays of scalars, not individual scalars.

EXPORT

LIMITATIONS

various

TODO

rownum filter support to move to separate package
$href: remove - need a dict function to return allfileused via tso
HSuck: need a way to specify packing method
HSuck: fix trailing zero replacement
NextCount: fix quitloop
localPush/Store: qualify length packstr as percentage of blocksize (1/3?)
localStore: race condition on rowstat
localFetchDelete: frag flag info, delete status. Could express this function as a generalized "RowSplice" (as distinct from RDBlkA::HSplice, which is a block splice operator). Would need be able to splice based upon column number/array offset, as well as substring byte offset -- the inverse functionality of PackRow2/HSuck
DBI - support Bind and projection (returning only certain specified columns, versus all columns)
_init: change to use TSTableAFU support versus href->{filesused}
need support for constraints that "mutate" supplied values, e.g. manipulate numeric precision or supply default values for columns. Also need support for foreign keys in delete.

AUTHOR

Jeffrey I. Cohen, jcohen@genezzo.com

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)