Koha/ElasticSearch.pm

   1 package Koha::ElasticSearch;
   2
   3 # Copyright 2013 Catalyst IT
   4 #
   5 # This file is part of Koha.
   6 #
   7 # Koha is free software; you can redistribute it and/or modify it under the
   8 # terms of the GNU General Public License as published by the Free Software
   9 # Foundation; either version 3 of the License, or (at your option) any later
  10 # version.
  11 #
  12 # Koha is distributed in the hope that it will be useful, but WITHOUT ANY
  13 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  14 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU General Public License along
  17 # with Koha; if not, write to the Free Software Foundation, Inc.,
  18 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  19
  20 use base qw(Class::Accessor);
  21
  22 use C4::Context;
  23 use Carp;
  24 use Koha::Database;
  25 use Modern::Perl;
  26 use Readonly;
  27
  28 use Data::Dumper;    # TODO remove
  29
  30 __PACKAGE__->mk_ro_accessors(qw( index ));
  31
  32 # Constants to refer to the standard index names
  33 Readonly our $BIBLIOS_INDEX     => 'biblios';
  34 Readonly our $AUTHORITIES_INDEX => 'authorities';
  35
  36 =head1 NAME
  37
  38 Koha::ElasticSearch - Base module for things using elasticsearch
  39
  40 =head1 ACCESSORS
  41
  42 =over 4
  43
  44 =item index
  45
  46 The name of the index to use, generally 'biblios' or 'authorities'.
  47
  48 =back
  49
  50 =head1 FUNCTIONS
  51
  52 =cut
  53
  54 sub new {
  55     my $class = shift @_;
  56     my $self = $class->SUPER::new(@_);
  57     # Check for a valid index
  58     croak('No index name provided') unless $self->index;
  59     return $self;
  60 }
  61
  62 =head2 get_elasticsearch_params
  63
  64     my $params = $self->get_elasticsearch_params();
  65
  66 This provides a hashref that contains the parameters for connecting to the
  67 ElasicSearch servers, in the form:
  68
  69     {
  70         'nodes' => ['127.0.0.1:9200', 'anotherserver:9200'],
  71         'index_name' => 'koha_instance_index',
  72     }
  73
  74 This is configured by the following in the C<config> block in koha-conf.xml:
  75
  76     <elasticsearch>
  77         <server>127.0.0.1:9200</server>
  78         <server>anotherserver:9200</server>
  79         <index_name>koha_instance</index_name>
  80     </elasticsearch>
  81
  82 =cut
  83
  84 sub get_elasticsearch_params {
  85     my ($self) = @_;
  86
  87     # Copy the hash so that we're not modifying the original
  88     my $conf = C4::Context->config('elasticsearch');
  89     die "No 'elasticsearch' block is defined in koha-conf.xml.\n" if ( !$conf );
  90     my $es = { %{ $conf } };
  91
  92     # Helpfully, the multiple server lines end up in an array for us anyway
  93     # if there are multiple ones, but not if there's only one.
  94     my $server = $es->{server};
  95     delete $es->{server};
  96     if ( ref($server) eq 'ARRAY' ) {
  97
  98         # store it called 'nodes' (which is used by newer Search::Elasticsearch)
  99         $es->{nodes} = $server;
 100     }
 101     elsif ($server) {
 102         $es->{nodes} = [$server];
 103     }
 104     else {
 105         die "No elasticsearch servers were specified in koha-conf.xml.\n";
 106     }
 107     die "No elasticserver index_name was specified in koha-conf.xml.\n"
 108       if ( !$es->{index_name} );
 109     # Append the name of this particular index to our namespace
 110     $es->{index_name} .= '_' . $self->index;
 111     return $es;
 112 }
 113
 114 =head2 get_elasticsearch_settings
 115
 116     my $settings = $self->get_elasticsearch_settings();
 117
 118 This provides the settings provided to elasticsearch when an index is created.
 119 These can do things like define tokenisation methods.
 120
 121 A hashref containing the settings is returned.
 122
 123 =cut
 124
 125 sub get_elasticsearch_settings {
 126     my ($self) = @_;
 127
 128     # Ultimately this should come from a file or something, and not be
 129     # hardcoded.
 130     my $settings = {
 131         index => {
 132             analysis => {
 133                 analyzer => {
 134                     analyser_phrase => {
 135                         tokenizer => 'keyword',
 136                         filter    => ['lowercase'],
 137                     },
 138                     analyser_standard => {
 139                         tokenizer => 'standard',
 140                         filter    => ['lowercase'],
 141                     }
 142                 },
 143             }
 144         }
 145     };
 146     return $settings;
 147 }
 148
 149 =head2 get_elasticsearch_mappings
 150
 151     my $mappings = $self->get_elasticsearch_mappings();
 152
 153 This provides the mappings that get passed to elasticsearch when an index is
 154 created.
 155
 156 =cut
 157
 158 sub get_elasticsearch_mappings {
 159     my ($self) = @_;
 160
 161     my $mappings = {
 162         data => {
 163             properties => {
 164                 record => {
 165                     store          => "yes",
 166                     include_in_all => "false",
 167                     type           => "string",
 168                 },
 169                 '_all.phrase' => {
 170                     search_analyzer => "analyser_phrase",
 171                     index_analyzer  => "analyser_phrase",
 172                     type            => "string",
 173                 },
 174             }
 175         }
 176     };
 177     my $marcflavour = lc C4::Context->preference('marcflavour');
 178     $self->_foreach_mapping(
 179         sub {
 180             my ( $name, $type, $facet, $marc_type ) = @_;
 181             return if $marc_type ne $marcflavour;
 182             # TODO if this gets any sort of complexity to it, it should
 183             # be broken out into its own function.
 184
 185             # TODO be aware of date formats, but this requires pre-parsing
 186             # as ES will simply reject anything with an invalid date.
 187             my $es_type =
 188               $type eq 'boolean'
 189               ? 'boolean'
 190               : 'string';
 191             $mappings->{data}{properties}{$name} = {
 192                 search_analyzer => "analyser_standard",
 193                 index_analyzer  => "analyser_standard",
 194                 type            => $es_type,
 195                 fields          => {
 196                     phrase => {
 197                         search_analyzer => "analyser_phrase",
 198                         index_analyzer  => "analyser_phrase",
 199                         type            => "string",
 200                         copy_to         => "_all.phrase",
 201                     },
 202                 },
 203             };
 204             $mappings->{data}{properties}{$name}{null_value} = 0
 205               if $type eq 'boolean';
 206             if ($facet) {
 207                 $mappings->{data}{properties}{ $name . '__facet' } = {
 208                     type  => "string",
 209                     index => "not_analyzed",
 210                 };
 211             }
 212         }
 213     );
 214     return $mappings;
 215 }
 216
 217 # Provides the rules for data conversion.
 218 sub get_fixer_rules {
 219     my ($self) = @_;
 220
 221     my $marcflavour = lc C4::Context->preference('marcflavour');
 222     my @rules;
 223     $self->_foreach_mapping(
 224         sub {
 225             my ( $name, $type, $facet, $marc_type, $marc_field ) = @_;
 226             return if $marc_type ne $marcflavour;
 227             my $options = '';
 228
 229             # There's a bug when using 'split' with something that
 230             # selects a range
 231             # The split makes everything into nested arrays, but that's not
 232             # really a big deal, ES doesn't mind.
 233             $options = '-split => 1' unless $marc_field =~ m|_/| || $type eq 'sum';
 234             push @rules, "marc_map('$marc_field','${name}', $options)";
 235             if ($facet) {
 236                 push @rules, "marc_map('$marc_field','${name}__facet', $options)";
 237             }
 238             if ( $type eq 'boolean' ) {
 239
 240                 # boolean gets special handling, basically if it doesn't exist,
 241                 # it's added and set to false. Otherwise we can't query it.
 242                 push @rules,
 243                   "unless exists('$name') add_field('$name', 0) end";
 244             }
 245             if ($type eq 'sum' ) {
 246                 push @rules, "sum('$name')";
 247             }
 248         }
 249     );
 250     return \@rules;
 251 }
 252
 253 =head2 _foreach_mapping
 254
 255     $self->_foreach_mapping(
 256         sub {
 257             my ( $name, $type, $facet, $marc_type, $marc_field ) = @_;
 258             return unless $marc_type eq 'marc21';
 259             print "Data comes from: " . $marc_field . "\n";
 260         }
 261     );
 262
 263 This allows you to apply a function to each entry in the elasticsearch mappings
 264 table, in order to build the mappings for whatever is needed.
 265
 266 In the provided function, the files are:
 267
 268 =over 4
 269
 270 =item C<$name>
 271
 272 The field name for elasticsearch (corresponds to the 'mapping' column in the
 273 database.
 274
 275 =item C<$type>
 276
 277 The type for this value, e.g. 'string'.
 278
 279 =item C<$facet>
 280
 281 True if this value should be facetised. This only really makes sense if the
 282 field is understood by the facet processing code anyway.
 283
 284 =item C<$marc_type>
 285
 286 A string that indicates the MARC type that this mapping is for, e.g. 'marc21',
 287 'unimarc', 'normarc'.
 288
 289 =item C<$marc_field>
 290
 291 A string that describes the MARC field that contains the data to extract.
 292 These are of a form suited to Catmandu's MARC fixers.
 293
 294 =back
 295
 296 =cut
 297
 298 sub _foreach_mapping {
 299     my ( $self, $sub ) = @_;
 300
 301     # TODO use a caching framework here
 302     my $database = Koha::Database->new();
 303     my $schema   = $database->schema();
 304     my $rs =
 305       $schema->resultset('SearchMarcMap')
 306       ->search( { index_name => $self->index } );
 307     for my $row ( $rs->all ) {
 308         my $marc_type = $row->marc_type;
 309         my $marc_field = $row->marc_field;
 310         my $facet = $row->facet;
 311         my $search_field = $row->search_fields();
 312         for my $sf ( $search_field->all ) {
 313             $sub->(
 314                 $sf->name,
 315                 $sf->type,
 316                 $facet,
 317                 $marc_type,
 318                 $marc_field,
 319             );
 320         }
 321     }
 322 }
 323
 324 =head2 process_error
 325
 326     die process_error($@);
 327
 328 This parses an Elasticsearch error message and produces a human-readable
 329 result from it. This result is probably missing all the useful information
 330 that you might want in diagnosing an issue, so the warning is also logged.
 331
 332 Note that currently the resulting message is not internationalised. This
 333 will happen eventually by some method or other.
 334
 335 =cut
 336
 337 sub process_error {
 338     my ($self, $msg) = @_;
 339
 340     warn $msg; # simple logging
 341
 342     # This is super-primitive
 343     return "Unable to understand your search query, please rephrase and try again.\n" if $msg =~ /ParseException/;
 344
 345     return "Unable to perform your search. Please try again.\n";
 346 }
 347
 348 1;
 349
 350 __END__
 351
 352 =head1 AUTHOR
 353
 354 =over 4
 355
 356 =item Chris Cormack C<< <chrisc@catalyst.net.nz> >>
 357
 358 =item Robin Sheat C<< <robin@catalyst.net.nz> >>
 359
 360 =back
 361
 362 =cut