NAME

Class::DBI::Plugin::Senna - Add Instant Fulltext Search Capability With Senna

SYNOPSIS

  package MyDATA;
  use base qw(Class::DBI);
  use Class::DBI::Plugin::Senna (
      index_filename => 'foo',
      index_column   => 'column_name'
  );

  # in main portion of your code..
  my $iter = MyDATA->fulltext_search($query);

DESCRIPTION

Class::DBI::Plugin::Senna harnesses the power of Senna (http://b.razil.jp/project/senna) with Class::DBI. This module installs hooks in your Class::DBI package that automatically creates and updates a Senna index.

You can then call fulltext_search() to retrieve the rows that match the particular fulltext search.

However, because Class::DBI is just a Perl wrapper (albeit a good one) around a database, you will only be able to create simple indices -- that is, you can only create an index against a single column, and not against multiple columns. This may sound limiting, but for anything more than that you really ought to be embedding Senna into the database itself, as that will allow for more complex searching.

HOW TO SETUP

First set up your Class::DBI object like you do normally. Then, add a few lines like this:

  use Class::DBI::Plugin::Senna
    index_filename => 'path/to/index',
    index_column   => 'name_of_column'
  ;

"index_filename" is the name of the index file that Senna will create. "index_column" is the name of the column that you want to build your index on. Class::DBI::Plugin::Senna will *ONLY* create an index on this column alone -- it is possible to apply the same hook that this module does on multiple columns, but the cross-column search just gets too hairy. If you want more power, you really should be embedding Senna in your database (like Senna does for mysql).

Class::DBI::Plugin::Senna willbe responsible for creating/opening the index file. If you want to specify non-default arguments to the create() method for Senna::Index, you can add a "index_createargs" parameter in the above list:

  use Class::DBI::Plugin::Senna
    index_filename => 'path/to/index',
    index_column   => 'name_of_column',
    index_createargs => [ $key_size, $flags, $n_segments, $encoding ]
  ;

Once you do that, your Class::DBI object will now automatically update the Senna index for the particular column you chose as you invoke the regular Class::DBI create/update/delete methods. These will all update the index accordingly:

  $obj = YourDataClass->create({ ... });

  $obj->your_indexed_column($new_value);
  $obj->update;

  $obj->delete;

After you poopulate the index, you can perform a fulltext search on the column you specified by calling:

  my $iter = YourDataClass->fulltext_search($query);

$iter is a special iterator class for Class::DBI::Plugin::Senna. You can also retrieve the whole list of object that matches your query:

  my @obj = YourDataClass->fulltext_search($query);

That's it! Enjoyin searching :)

METHODS

fulltext_search($query)

Performs a fulltext search on the column specified in your class. In list context, returns a list of objects that match your particular query, an instance of Class::DBI::Plugin::Senna::Iterator.

index_filename()

Class method to get the name of the index file. Do NOT modify this value!

index_column()

Class method to get the name of the column that is being indexed by Senna. Do NOT modify this value!

index_createargs()

Class method to get the list of arguments passed to Senna::Index::create(). Do NOT modify this value!

senna_index()

Class method to get the Senna index object that is handling the index. You may performa operations on it, but do not set it to a new index or such.

CAVEATS

The senna index is maitained if and only if you perform your updates through this interface! If you go and change the data behind the scenes (by using a interactive shell, for example), then the actual data and the index will be out of sync.

This module uses triggers to update the index: if you do any exotic data processing in the trigger chain that modifies the data, things may get a bit weird.

AUTHOR

Development fundex by Brazil Ltd. <http://dev.razl.jp/projects/senna>