Koha/SearchEngine/Elasticsearch.pm

   1 package Koha::SearchEngine::Elasticsearch;
   2
   3 # Copyright 2015 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
  24 use Koha::Database;
  25 use Koha::Exceptions::Config;
  26 use Koha::SearchFields;
  27 use Koha::SearchMarcMaps;
  28
  29 use Carp;
  30 use JSON;
  31 use Modern::Perl;
  32 use Readonly;
  33 use Search::Elasticsearch;
  34 use Try::Tiny;
  35 use YAML::Syck;
  36
  37 __PACKAGE__->mk_ro_accessors(qw( index ));
  38 __PACKAGE__->mk_accessors(qw( sort_fields ));
  39
  40 # Constants to refer to the standard index names
  41 Readonly our $BIBLIOS_INDEX     => 'biblios';
  42 Readonly our $AUTHORITIES_INDEX => 'authorities';
  43
  44 =head1 NAME
  45
  46 Koha::SearchEngine::Elasticsearch - Base module for things using elasticsearch
  47
  48 =head1 ACCESSORS
  49
  50 =over 4
  51
  52 =item index
  53
  54 The name of the index to use, generally 'biblios' or 'authorities'.
  55
  56 =back
  57
  58 =head1 FUNCTIONS
  59
  60 =cut
  61
  62 sub new {
  63     my $class = shift @_;
  64     my $self = $class->SUPER::new(@_);
  65     # Check for a valid index
  66     croak('No index name provided') unless $self->index;
  67     return $self;
  68 }
  69
  70 =head2 get_elasticsearch_params
  71
  72     my $params = $self->get_elasticsearch_params();
  73
  74 This provides a hashref that contains the parameters for connecting to the
  75 ElasicSearch servers, in the form:
  76
  77     {
  78         'nodes' => ['127.0.0.1:9200', 'anotherserver:9200'],
  79         'index_name' => 'koha_instance_index',
  80     }
  81
  82 This is configured by the following in the C<config> block in koha-conf.xml:
  83
  84     <elasticsearch>
  85         <server>127.0.0.1:9200</server>
  86         <server>anotherserver:9200</server>
  87         <index_name>koha_instance</index_name>
  88     </elasticsearch>
  89
  90 =cut
  91
  92 sub get_elasticsearch_params {
  93     my ($self) = @_;
  94
  95     # Copy the hash so that we're not modifying the original
  96     my $conf = C4::Context->config('elasticsearch');
  97     die "No 'elasticsearch' block is defined in koha-conf.xml.\n" if ( !$conf );
  98     my $es = { %{ $conf } };
  99
 100     # Helpfully, the multiple server lines end up in an array for us anyway
 101     # if there are multiple ones, but not if there's only one.
 102     my $server = $es->{server};
 103     delete $es->{server};
 104     if ( ref($server) eq 'ARRAY' ) {
 105
 106         # store it called 'nodes' (which is used by newer Search::Elasticsearch)
 107         $es->{nodes} = $server;
 108     }
 109     elsif ($server) {
 110         $es->{nodes} = [$server];
 111     }
 112     else {
 113         die "No elasticsearch servers were specified in koha-conf.xml.\n";
 114     }
 115     die "No elasticserver index_name was specified in koha-conf.xml.\n"
 116       if ( !$es->{index_name} );
 117     # Append the name of this particular index to our namespace
 118     $es->{index_name} .= '_' . $self->index;
 119
 120     $es->{key_prefix} = 'es_';
 121     return $es;
 122 }
 123
 124 =head2 get_elasticsearch_settings
 125
 126     my $settings = $self->get_elasticsearch_settings();
 127
 128 This provides the settings provided to elasticsearch when an index is created.
 129 These can do things like define tokenisation methods.
 130
 131 A hashref containing the settings is returned.
 132
 133 =cut
 134
 135 sub get_elasticsearch_settings {
 136     my ($self) = @_;
 137
 138     # Use state to speed up repeated calls
 139     state $settings = undef;
 140     if (!defined $settings) {
 141         my $config_file = C4::Context->config('elasticsearch_index_config');
 142         $config_file ||= C4::Context->config('intranetdir') . '/etc/searchengine/elasticsearch/index_config.yaml';
 143         $settings = LoadFile( $config_file );
 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     # Use state to speed up repeated calls
 162     state %all_mappings;
 163     state %sort_fields;
 164
 165     if (!defined $all_mappings{$self->index}) {
 166         $sort_fields{$self->index} = {};
 167         my $mappings = {
 168             data => _get_elasticsearch_mapping('general', '')
 169         };
 170         my $marcflavour = lc C4::Context->preference('marcflavour');
 171         $self->_foreach_mapping(
 172             sub {
 173                 my ( $name, $type, $facet, $suggestible, $sort, $marc_type ) = @_;
 174                 return if $marc_type ne $marcflavour;
 175                 # TODO if this gets any sort of complexity to it, it should
 176                 # be broken out into its own function.
 177
 178                 # TODO be aware of date formats, but this requires pre-parsing
 179                 # as ES will simply reject anything with an invalid date.
 180                 my $es_type = 'text';
 181                 if ($type eq 'boolean') {
 182                     $es_type = 'boolean';
 183                 } elsif ($type eq 'number' || $type eq 'sum') {
 184                     $es_type = 'integer';
 185                 } elsif ($type eq 'isbn' || $type eq 'stdno') {
 186                     $es_type = 'stdno';
 187                 }
 188
 189                 $mappings->{data}{properties}{$name} = _get_elasticsearch_mapping('search', $es_type);
 190
 191                 if ($facet) {
 192                     $mappings->{data}{properties}{ $name . '__facet' } = _get_elasticsearch_mapping('facet', $es_type);
 193                 }
 194                 if ($suggestible) {
 195                     $mappings->{data}{properties}{ $name . '__suggestion' } = _get_elasticsearch_mapping('suggestible', $es_type);
 196                 }
 197                 # Sort is a bit special as it can be true, false, undef.
 198                 # We care about "true" or "undef",
 199                 # "undef" means to do the default thing, which is make it sortable.
 200                 if (!defined $sort || $sort) {
 201                     $mappings->{data}{properties}{ $name . '__sort' } = _get_elasticsearch_mapping('sort', $es_type);
 202                     $sort_fields{$self->index}{$name} = 1;
 203                 }
 204             }
 205         );
 206         $all_mappings{$self->index} = $mappings;
 207     }
 208     $self->sort_fields(\%{$sort_fields{$self->index}});
 209
 210     return $all_mappings{$self->index};
 211 }
 212
 213 =head2 _get_elasticsearch_mapping
 214
 215 Get the ES mappings for the given purpose and data type
 216
 217 $mapping = _get_elasticsearch_mapping('search', 'text');
 218
 219 =cut
 220
 221 sub _get_elasticsearch_mapping {
 222
 223     my ( $purpose, $type ) = @_;
 224
 225     # Use state to speed up repeated calls
 226     state $settings = undef;
 227     if (!defined $settings) {
 228         my $config_file = C4::Context->config('elasticsearch_field_config');
 229         $config_file ||= C4::Context->config('intranetdir') . '/etc/searchengine/elasticsearch/field_config.yaml';
 230         $settings = LoadFile( $config_file );
 231     }
 232
 233     if (!defined $settings->{$purpose}) {
 234         die "Field purpose $purpose not defined in field config";
 235     }
 236     if ($type eq '') {
 237         return $settings->{$purpose};
 238     }
 239     if (defined $settings->{$purpose}{$type}) {
 240         return $settings->{$purpose}{$type};
 241     }
 242     if (defined $settings->{$purpose}{'default'}) {
 243         return $settings->{$purpose}{'default'};
 244     }
 245     return undef;
 246 }
 247
 248 sub reset_elasticsearch_mappings {
 249     my ( $reset_fields ) = @_;
 250     my $mappings_yaml = C4::Context->config('elasticsearch_index_mappings');
 251     $mappings_yaml ||= C4::Context->config('intranetdir') . '/etc/searchengine/elasticsearch/mappings.yaml';
 252     my $indexes = LoadFile( $mappings_yaml );
 253
 254     while ( my ( $index_name, $fields ) = each %$indexes ) {
 255         while ( my ( $field_name, $data ) = each %$fields ) {
 256             my $field_type = $data->{type};
 257             my $field_label = $data->{label};
 258             my $mappings = $data->{mappings};
 259             my $search_field = Koha::SearchFields->find_or_create({ name => $field_name, label => $field_label, type => $field_type }, { key => 'name' });
 260             for my $mapping ( @$mappings ) {
 261                 my $marc_field = Koha::SearchMarcMaps->find_or_create({ index_name => $index_name, marc_type => $mapping->{marc_type}, marc_field => $mapping->{marc_field} });
 262                 $search_field->add_to_search_marc_maps($marc_field, { facet => $mapping->{facet} || 0, suggestible => $mapping->{suggestible} || 0, sort => $mapping->{sort} } );
 263             }
 264         }
 265     }
 266 }
 267
 268 # This overrides the accessor provided by Class::Accessor so that if
 269 # sort_fields isn't set, then it'll generate it.
 270 sub sort_fields {
 271     my $self = shift;
 272     if (@_) {
 273         $self->_sort_fields_accessor(@_);
 274         return;
 275     }
 276     my $val = $self->_sort_fields_accessor();
 277     return $val if $val;
 278
 279     # This will populate the accessor as a side effect
 280     $self->get_elasticsearch_mappings();
 281     return $self->_sort_fields_accessor();
 282 }
 283
 284 # Provides the rules for data conversion.
 285 sub get_fixer_rules {
 286     my ($self) = @_;
 287
 288     my $marcflavour = lc C4::Context->preference('marcflavour');
 289     my @rules;
 290
 291     $self->_foreach_mapping(
 292         sub {
 293             my ( $name, $type, $facet, $suggestible, $sort, $marc_type, $marc_field ) = @_;
 294             return if $marc_type ne $marcflavour;
 295             my $options ='';
 296
 297             push @rules, "marc_map('$marc_field','${name}.\$append', $options)";
 298             if ($facet) {
 299                 push @rules, "marc_map('$marc_field','${name}__facet.\$append', $options)";
 300             }
 301             if ($suggestible) {
 302                 push @rules,
 303                     #"marc_map('$marc_field','${name}__suggestion.input.\$append', '')"; #must not have nested data structures in .input
 304                     "marc_map('$marc_field','${name}__suggestion.input.\$append')";
 305             }
 306             if ( $type eq 'boolean' ) {
 307
 308                 # boolean gets special handling, basically if it doesn't exist,
 309                 # it's added and set to false. Otherwise we can't query it.
 310                 push @rules,
 311                   "unless exists('$name') add_field('$name', 0) end";
 312             }
 313             if ($type eq 'sum' ) {
 314                 push @rules, "sum('$name')";
 315             }
 316             if ($self->sort_fields()->{$name}) {
 317                 if ($sort || !defined $sort) {
 318                     push @rules, "marc_map('$marc_field','${name}__sort.\$append', $options)";
 319                 }
 320             }
 321         }
 322     );
 323
 324     push @rules, "move_field(_id,es_id)"; #Also you must set the Catmandu::Store::ElasticSearch->new(key_prefix: 'es_');
 325     return \@rules;
 326 }
 327
 328 =head2 _foreach_mapping
 329
 330     $self->_foreach_mapping(
 331         sub {
 332             my ( $name, $type, $facet, $suggestible, $sort, $marc_type,
 333                 $marc_field )
 334               = @_;
 335             return unless $marc_type eq 'marc21';
 336             print "Data comes from: " . $marc_field . "\n";
 337         }
 338     );
 339
 340 This allows you to apply a function to each entry in the elasticsearch mappings
 341 table, in order to build the mappings for whatever is needed.
 342
 343 In the provided function, the files are:
 344
 345 =over 4
 346
 347 =item C<$name>
 348
 349 The field name for elasticsearch (corresponds to the 'mapping' column in the
 350 database.
 351
 352 =item C<$type>
 353
 354 The type for this value, e.g. 'string'.
 355
 356 =item C<$facet>
 357
 358 True if this value should be facetised. This only really makes sense if the
 359 field is understood by the facet processing code anyway.
 360
 361 =item C<$sort>
 362
 363 True if this is a field that a) needs special sort handling, and b) if it
 364 should be sorted on. False if a) but not b). Undef if not a). This allows,
 365 for example, author to be sorted on but not everything marked with "author"
 366 to be included in that sort.
 367
 368 =item C<$marc_type>
 369
 370 A string that indicates the MARC type that this mapping is for, e.g. 'marc21',
 371 'unimarc', 'normarc'.
 372
 373 =item C<$marc_field>
 374
 375 A string that describes the MARC field that contains the data to extract.
 376 These are of a form suited to Catmandu's MARC fixers.
 377
 378 =back
 379
 380 =cut
 381
 382 sub _foreach_mapping {
 383     my ( $self, $sub ) = @_;
 384
 385     # TODO use a caching framework here
 386     my $search_fields = Koha::Database->schema->resultset('SearchField')->search(
 387         {
 388             'search_marc_map.index_name' => $self->index,
 389         },
 390         {   join => { search_marc_to_fields => 'search_marc_map' },
 391             '+select' => [
 392                 'search_marc_to_fields.facet',
 393                 'search_marc_to_fields.suggestible',
 394                 'search_marc_to_fields.sort',
 395                 'search_marc_map.marc_type',
 396                 'search_marc_map.marc_field',
 397             ],
 398             '+as'     => [
 399                 'facet',
 400                 'suggestible',
 401                 'sort',
 402                 'marc_type',
 403                 'marc_field',
 404             ],
 405         }
 406     );
 407
 408     while ( my $search_field = $search_fields->next ) {
 409         $sub->(
 410             $search_field->name,
 411             $search_field->type,
 412             $search_field->get_column('facet'),
 413             $search_field->get_column('suggestible'),
 414             $search_field->get_column('sort'),
 415             $search_field->get_column('marc_type'),
 416             $search_field->get_column('marc_field'),
 417         );
 418     }
 419 }
 420
 421 =head2 process_error
 422
 423     die process_error($@);
 424
 425 This parses an Elasticsearch error message and produces a human-readable
 426 result from it. This result is probably missing all the useful information
 427 that you might want in diagnosing an issue, so the warning is also logged.
 428
 429 Note that currently the resulting message is not internationalised. This
 430 will happen eventually by some method or other.
 431
 432 =cut
 433
 434 sub process_error {
 435     my ($self, $msg) = @_;
 436
 437     warn $msg; # simple logging
 438
 439     # This is super-primitive
 440     return "Unable to understand your search query, please rephrase and try again.\n" if $msg =~ /ParseException/;
 441
 442     return "Unable to perform your search. Please try again.\n";
 443 }
 444
 445 =head2 _read_configuration
 446
 447     my $conf = _read_configuration();
 448
 449 Reads the I<configuration file> and returns a hash structure with the
 450 configuration information. It raises an exception if mandatory entries
 451 are missing.
 452
 453 The hashref structure has the following form:
 454
 455     {
 456         'nodes' => ['127.0.0.1:9200', 'anotherserver:9200'],
 457         'index_name' => 'koha_instance',
 458     }
 459
 460 This is configured by the following in the C<config> block in koha-conf.xml:
 461
 462     <elasticsearch>
 463         <server>127.0.0.1:9200</server>
 464         <server>anotherserver:9200</server>
 465         <index_name>koha_instance</index_name>
 466     </elasticsearch>
 467
 468 =cut
 469
 470 sub _read_configuration {
 471
 472     my $configuration;
 473
 474     my $conf = C4::Context->config('elasticsearch');
 475     Koha::Exceptions::Config::MissingEntry->throw(
 476         "Missing 'elasticsearch' block in config file")
 477       unless defined $conf;
 478
 479     if ( $conf && $conf->{server} ) {
 480         my $nodes = $conf->{server};
 481         if ( ref($nodes) eq 'ARRAY' ) {
 482             $configuration->{nodes} = $nodes;
 483         }
 484         else {
 485             $configuration->{nodes} = [$nodes];
 486         }
 487     }
 488     else {
 489         Koha::Exceptions::Config::MissingEntry->throw(
 490             "Missing 'server' entry in config file for elasticsearch");
 491     }
 492
 493     if ( defined $conf->{index_name} ) {
 494         $configuration->{index_name} = $conf->{index_name};
 495     }
 496     else {
 497         Koha::Exceptions::Config::MissingEntry->throw(
 498             "Missing 'index_name' entry in config file for elasticsearch");
 499     }
 500
 501     return $configuration;
 502 }
 503
 504 1;
 505
 506 __END__
 507
 508 =head1 AUTHOR
 509
 510 =over 4
 511
 512 =item Chris Cormack C<< <chrisc@catalyst.net.nz> >>
 513
 514 =item Robin Sheat C<< <robin@catalyst.net.nz> >>
 515
 516 =item Jonathan Druart C<< <jonathan.druart@bugs.koha-community.org> >>
 517
 518 =back
 519
 520 =cut