NAME

Catalyst::Model::Search::Plucene - Index and search using Plucene

SYNOPSIS

    package MyApp::M::Search;

    use strict;
    use base qw/Catalyst::Model::Search::Plucene/;
    
    __PACKAGE__->config(
        index        => MyApp->config->{home} . '/plucene',
        analyzer     => 'Plucene::Plugin::Analyzer::SnowballAnalyzer',
        return_style => 'full',
    );
    
    1;
    
    # meanwhile, in a controller...
    
    my $search = 'MyApp::M::Search';
    
    $search->add( {
        $key => {
            stuff => 'that',
            you   => 'want',
            to    => 'index',
        },
    } );
    
    my $results = $search->query( 'want' );
    # Hits: $results->total_hits
    foreach my $result ( $results->hits ) {
        # Score: $result->score
        # Key:   $result->key
        # Data:  $result->get('you') # returns 'want'
    }

DESCRIPTION

This model implements the standard Catalyst::Model::Search interface to a Plucene index.

CONFIGURATION OPTIONS

    index

Plucene uses a single directory to store index files. This value defaults to a 'plucene' directory in your application's home directory.

    analyzer

The analyzer filters your input data before indexing it. You may specify a different analyzer if the default one is not to your liking.

    return_style

This value controls the amount of data stored and returned from a search query. The default value is 'key', where only the key value is stored in the index. If set to 'full', all of your input data is stored in the index and returned to you when performing a search query. See the query method for more details.

METHODS

add( $hashref )

Add one or more items to the search index.

    $search->add( {
        'page1' => {
            author  => 'jdoe',
            date    => '2005-10-01',
            text    => 'some text on the page',
            _hidden => 'foo', 
        },
        'page2' => 'some more text on this page',
    } );
    

Every item must be indexed with a unique key and may optionally contain other metadata. See the query method for examples of retrieving this data.

If you do not need to store additional metadata, you may simply pass in any text to be indexed.

update( $hashref )

The update method is the same as add, except that every key is removed from the index first and then re-added.

remove( $key )

The remove method removes a single key from the index.

query( $query_string )

Perform a search query. If metadata was specified during add(), you may perform searches on the metadata keys. For example,

    'author:jdoe'               # page1
    '2005-10-01'                # page1
    'foo'                       # no results
    '_hidden:foo'               # page1
    'page'                      # page1, page2
    

An unqualified search such as '2005-10-01' will search the default field. The default field is a special field made up of all pieces of text except for text associated with keys that begin with an underscore.

query returns a Catalyst::Model::Search::Results object. This object contains two methods, total_hits, and hits.

    my $results = $search->query( 'some' );
    $results->get_total_hits;   # 2
    

Loop through the search hits, returns Catalyst::Model::Search::Item objects. The results are sorted by highest score.

    foreach my $item ( $results->get_items ) {
        $item;                  # stringifies to 'page1'
        $item->get_score;       # 0.50000
        $item->get_key;         # 'page1'
        $item->get_fields;      # array of available fields
        $item->get('author')    # 'jdoe'
    }

Note that the $item->get() method only returns data if return_style is set to 'full'.

is_indexed( $key )

Returns true if the specified key exists in the index.

optimize()

Optimizes the entire index.

AUTHOR

Andy Grundman, <andy@hybridized.org> Marcus Ramberg, <mramberg@cpan.org>

THANKS

Marc Kerr, <coder@stray-toaster.co.uk>, for Plucene::Simple from which this module borrows heavily.

COPYRIGHT

This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Catalyst::Model::Search

perl -MCPAN -e shell
install Catalyst::Model::Search