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