From a1f12162c274a298df5308eaa80aeb2527859ad5 Mon Sep 17 00:00:00 2001 From: Nicolas Steenlant Date: Thu, 6 Nov 2014 10:13:28 +0100 Subject: [PATCH] milla --- Build.PL | 30 ----------- README | 17 ------ README.md | 151 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ cpanfile | 12 +++++ dist.ini | 3 ++ 5 files changed, 166 insertions(+), 47 deletions(-) delete mode 100644 Build.PL delete mode 100644 README create mode 100644 README.md create mode 100644 cpanfile create mode 100644 dist.ini diff --git a/Build.PL b/Build.PL deleted file mode 100644 index b987145..0000000 --- a/Build.PL +++ /dev/null @@ -1,30 +0,0 @@ -use strict; -use warnings; -use Module::Build; - -my $builder = Module::Build->new( - module_name => 'Catmandu::Store::Elasticsearch', - license => 'perl', - dist_author => [ - 'Nicolas Steenlant ', - ], - build_requires => { - 'Software::License' => 0, - 'Test::Exception' => 0, - 'Test::More' => 0, - }, - requires => { - 'perl' => '5.10.1', - 'Catmandu' => '0.9206', - 'CQL::Parser' => '1.12', - 'Moo' => '1.00', - 'Search::Elasticsearch' => '1.14', - }, - add_to_cleanup => [qw( - Catmandu-Store-Elasticsearch-* - )], - create_makefile_pl => 'traditional', - create_license => 1, -); - -$builder->create_build_script; diff --git a/README b/README deleted file mode 100644 index a5e424e..0000000 --- a/README +++ /dev/null @@ -1,17 +0,0 @@ -Catmandu-Store-ElasticSearch - -INSTALLATION - -To install this module, run the following commands: - - perl Build.PL - ./Build - ./Build test - ./Build install - -SUPPORT AND DOCUMENTATION - -After installing, you can find documentation for this module with the -perldoc command. - - perldoc Catmandu::Store::ElasticSearch diff --git a/README.md b/README.md new file mode 100644 index 0000000..ed7dd02 --- /dev/null +++ b/README.md @@ -0,0 +1,151 @@ +# NAME + +Catmandu::Store::Elasticsearch - A searchable store backed by Elasticsearch + +# VERSION + +Version 0.01 + +# SYNOPSIS + + use Catmandu::Store::Elasticsearch; + + my $store = Catmandu::Store::Elasticsearch->new(index_name => 'catmandu'); + + my $obj1 = $store->bag->add({ name => 'Patrick' }); + + printf "obj1 stored as %s\n" , $obj1->{_id}; + + # Force an id in the store + my $obj2 = $store->bag->add({ _id => 'test123' , name => 'Nicolas' }); + + # Commit all changes + $store->bag->commit; + + my $obj3 = $store->bag->get('test123'); + + $store->bag->delete('test123'); + + $store->bag->delete_all; + + # All bags are iterators + $store->bag->each(sub { ... }); + $store->bag->take(10)->each(sub { ... }); + + # Some stores can be searched + my $hits = $store->bag->search(query => 'name:Patrick'); + + # Catmandu::Store::Elasticsearch supports CQL... + my $hits = $store->bag->search(cql_query => 'name any "Patrick"'); + +# METHODS + +## new(index\_name => $name) + +## new(index\_name => $name , bags => { data => { cql\_mapping => \\%mapping } }) + +## new(index\_name => $name , index\_mapping => $mapping) + +Create a new Catmandu::Store::ElasticSearch store connected to index $name. + +The store supports CQL searches when a cql\_mapping is provided. This hash +contains a translation of CQL fields into Elasticsearch searchable fields. + + # Example mapping + $cql_mapping = { + title => { + op => { + 'any' => 1 , + 'all' => 1 , + '=' => 1 , + '<>' => 1 , + 'exact' => {field => [qw(mytitle.exact myalttitle.exact)]} + } , + sort => 1, + field => 'mytitle', + cb => ['Biblio::Search', 'normalize_title'] + } + } + +The CQL mapping above will support for the 'title' field the CQL operators: any, all, =, <> and exact. + +For all the operators the 'title' field will be mapping into the Elasticsearch field 'mytitle', except +for the 'exact' operator. In case of 'exact' we will search both the 'mytitle.exact' and 'myalttitle.exact' +fields. + +The CQL mapping allows for sorting on the 'title' field. If, for instance, we would like to use a special +Elasticsearch field for sorting we could have written "sort => { field => 'mytitle.sort' }". + +The CQL has an optional callback field 'cb' which contains a reference to subroutines to rewrite or +augment the search query. In this case, in the Biblio::Search package there is a normalize\_title +subroutine which returns a string or an ARRAY of string with augmented title(s). E.g. + + package Biblio::Search; + + sub normalize_title { + my ($self,$title) = @_; + my $new_title =~ s{[^A-Z0-9]+}{}g; + $new_title; + } + + 1; + +Optionally, index\_mappings contain Elastic Search schema mappings. E.g. + + # The 'data' index can ony contain one field 'title' of type 'string' + index_mappings => { + data => { + dynamic => 'strict', + properties => { + title => { type => 'string' } + } + } + } + +## drop + +Deletes the elasticsearch index backing this store. Calling functions after +this may fail until this class is reinstantiated, creating a new index. + +# COMPATIBILITY + +This store expects version 1.0 or higher of the Elasticsearch server. + +# ERROR HANDLING + +Error handling can be activated by specifying an error handling callback for index when creating +a store. E.g. to create an error handler for the bag 'data' index use: + + my $store = Catmandu::Store::ElasticSearch->new( + index_name => 'catmandu' + bags => { data => { on_error => \&error_handler } } + }); + + sub error_handler { + my ($action,$response,$i) = @_; + } + +See: http://search.cpan.org/~drtech/ElasticSearch-0.68/lib/ElasticSearch.pm#Error\_handlers for more +information. + +# SEE ALSO + +[Catmandu::Store](https://metacpan.org/pod/Catmandu::Store) + +# AUTHOR + +Nicolas Steenlant, `` + +# CONTRIBUTORS + +- Dave Sherohman, `dave.sherohman at ub.lu.se` +- Robin Sheat, `robin at kallisti.net.nz` +- Patrick Hochstenbach, `patrick.hochstenbach at ugent.be` + +# LICENSE AND COPYRIGHT + +This program is free software; you can redistribute it and/or modify it +under the terms of either: the GNU General Public License as published +by the Free Software Foundation; or the Artistic License. + +See http://dev.perl.org/licenses/ for more information. diff --git a/cpanfile b/cpanfile new file mode 100644 index 0000000..adced9a --- /dev/null +++ b/cpanfile @@ -0,0 +1,12 @@ +requires 'perl', 'v5.10.1'; + +on 'test', sub { + requires 'Test::Simple', '1.001003'; + requires 'Test::More', '1.001003'; +}; + +requires 'Catmandu', '0.9206'; +requires 'CQL::Parser', '1.12'; +requires 'Moo', '1.0'; +requires 'Search::Elasticsearch', '1.14'; + diff --git a/dist.ini b/dist.ini new file mode 100644 index 0000000..f2bb100 --- /dev/null +++ b/dist.ini @@ -0,0 +1,3 @@ +[@Milla] +installer = ModuleBuild +